Discontinued
Subscription payments are available to current subscription API users only.
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.
/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" }