WePay

Beta

The Subscriptions API is in beta. Please provide feedback - api@wepay.com

The /subscription_charge API calls

The "subscription charge" object represents a single payment for a subscription The following calls let you view and refund "subscription charge" objects on WePay:

Subscription Charge States

The "subscription charge" object has the following states and the following possible state transitions (you can receive callback notifications when the subscription charge changes state, please read our IPN Tutorial for more details):

new
The subscription charge was just created.
authorized
WePay was successfully able to charge the payment method.
failed
The subscription charge failed.
refunded
The subscription charge was refunded.
captured
The subscription charge was credited to the payee's account.
charged back
The subscription charge payment has been charged back by the payer and the payment has been debited from the payee account.

API Subscription Charge State Diagram

/subscription_charge

This call allows you to lookup the details of a specific subscription charge on WePay using a subscription_charge_id.

Arguments:

Parameter Required Type Description
subscription_charge_id Yes Integer (64 bits) The unique ID of the subscription charge you want to look up.

Example:

{
  "subscription_charge_id":12345
}

Response:

Response Type Description
subscription_charge_id Integer (64 bits) The unique ID of the subscription charge that you want to look up.
subscription_plan_id Integer (64 bits) The unique ID of the subscription plan that the subscription is associated with.
subscription_id Integer (64 bits) The unique ID of the subscription that the charge belongs to.
type String (255 chars) The type of the charge. This can be either 'recurring_charge','setup_fee', or 'prorated_charge'.
amount Decimal (64 bits) The amount that the subscription pays every period. This amount determined by the subscription plan.
currency String (3 chars) The currency used.
fee Decimal (64 bits) The WePay fee.
app_fee Decimal (64 bits) The dollar amount that the application received in fees. App fees go into the API application's WePay account.
gross Decimal (64 bits) The total amount paid by payer.
amount_refunded Decimal (64 bits) Amount refunded so far, if this subscription charge has been fully or partially refunded.
amount_charged_back Decimal (64 bits) If this charge has been fully or partially charged back, this has the amount that has been charged back so far.
state String (255 chars) The state the subscription charge is in. See the subscription charge states section for a listing of all states.
create_time Integer (64 bits) The unixtime when the subscription charge was created.
end_time Integer (64 bits) This subscription charge is good through this date (unixtime). Ex: If subscription charge was created at Mar 7, 2013 for a weekly subscription, end_time will be Mar 14, 2013.
prorate_time Integer (64 bits) The unixtime when the subscription charge was prorated. Applicable only if proration happened during this charge.

Example:

{
  "subscription_charge_id": 19432416,
  "subscription_plan_id": 54321,
  "subscription_id": 12345,
  "type": "recurring_charge",
  "amount": 20,
  "currency": "USD",
  "amount_refunded": 0,
  "amount_charged_back": 0,
  "fee": 0.88,
  "app_fee": 0,
  "gross": 20,
  "state": "captured",
  "create_time": 1376089559,
  "end_time": null,
  "prorate_time": 0
}

/subscription_charge/find

This call allows you to search for subscription charges (for a specific subscription) that match the search parameters.

Arguments:

Parameter Required Type Description
subscription_id Yes Integer (64 bits) The subscription you want to look for charges under.
start No Integer (64 bits) The start position for your search (default 0).
limit No Integer (64 bits) The maximum number of returned entries (default 50).
start_time No Integer (64 bits) or String (255 chars) The subscription charges that occurred after this start time. Can be a unix_timestamp or a valid, parse-able date time.
end_time No Integer (64 bits) or String (255 chars) The subscription charges that occurred before this end time. Can be a unix_timestamp or a valid, parse-able date-time.
type No String (255 chars) The type of the charge. This can be either 'recurring_charge', 'setup_fee', 'prorated_charge'.
amount No Decimal (64 bits) The amount of the subscription_charge.
state No String (255 chars) What state the subscription charge is in (see the subscription charge states section for details).

Example:

{
  "subscription_id":12345,
  "start":10,
  "limit":20,
  "state":"new"
}

Response:

An array of subscription charges matching the search parameters. Each element of the array will include the same data as returned from the /subscription_charge call.

Example:

[
  {
    "subscription_charge_id": 19432416,
    "subscription_plan_id": 54321,
    "subscription_id": 12345,
    "type": "recurring_charge",
    "amount": 20,
    "currency": "USD",
    "amount_refunded": 0,
    "amount_charged_back": 0,
    "fee": 0.88,
    "app_fee": 0,
    "gross": 20,
    "state": "captured",
    "create_time": 1376089559,
    "end_time": null,
    "prorate_time": 0
  }
,
  {
    "subscription_charge_id": 749832489,
    "subscription_plan_id": 54321,
    "subscription_id": 12345,
    "type": "recurring_charge",
    "amount": 20,
    "currency": "USD",
    "amount_refunded": 0,
    "amount_charged_back": 0,
    "fee": 0.88,
    "app_fee": 0,
    "gross": 20,
    "state": "captured",
    "create_time": 1386066290,
    "end_time": null,
    "prorate_time": 0
  }
]

/subscription_charge/refund

Refunds a subscription charge.

Arguments:

Parameter Required Format Description
subscription_charge_id Yes Integer (64 bits) The unique ID of the subscription charge you want to refund.
refund_reason No String (255 chars) Reason for refunding the charge.

Example:

{
   "subscription_charge_id":54321,
   "refund_reason":"User wants the charge on a different credit card."
}

Response:

Response Format Description
subscription_plan_id Integer (64 bits) The unique ID of the subscription plan.
subscription_id Integer (64 bits) The unique ID of the subscription.
subscription_charge_id Integer (64 bits) The unique ID of the subscription charge that was refunded.
state String (255 chars) The state of the charge. It will be 'Refunded'.

Example:

{
  "subscription_plan_id":22345,	
  "subscription_id":12345,
  "subscription_charge_id":54321,
  "state":"Refunded"
}