Note:
The field will be disregarded if it is marked as optional and the format provided is incorrect. However, a validation error will be displayed if the field is marked as mandatory and the format provided is incorrect.
"+" - means required (for all flows)
"-" - means not required (for any flow)
For instance, in POST Create Charge flow:
+6 means that the field is required for flow number 6
-6 means that the field is not required for flow number 6
Subscriptions
Subscriptions are recurring billing events. These can be set up to take scheduled payments from a customer without having to re-enter the billing details.
Conditions
The response is different depending on such conditions:
- Created with a credit card payment source
- Created with an existing customer
- Created with a one-time token
Subscription resource
| field | required [flow] | type | description |
|---|---|---|---|
| amount | + | float | An amount of the payment |
| currency | + | string (iso4217 alpha-3) | A currency code |
| description | - | string | A manually defined description for payments in payment systems |
| reference | - | string | A manually defined reference for payments in payment systems |
| _id | + | string (24 hex characters) | A subscription ID for any future requests |
| created_at | + | string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ) | A subscription creation date |
| updated_at | + | string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ) | A date of the last subscription update |
| status | + | string | An actual subscription status. See the status table |
| held_at | + | string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ) | The time when subscription was moved to the held status |
| expired_at | + | string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ) | An actual expiration time of the subscription |
| expired_reason | + | string | An actual expiration reason of the subscription. See the Expire reason table |
| last_change_by | + | string | Defines the origin of the last change of the subscription. Values: manual or automatic |
| latest_charge_id | + | string (24 hex characters) | The latest charge ID of the subscription |
| archived | + | bool | For newly created charges, it is always false, true is set after manual archivation |
| customer | + | object | An object with the customer’s information |
| customer.customer_id | +2 | string (24 hex characters) | A customer ID |
| customer.first_name | - | string | A customer's first name |
| customer.last_name | - | string | A customer's last name |
| customer.email | - | string | A customer's email |
| customer.phone | - | string(E.164) | A customer's phone in the E.164 international notation (Example: +12345678901) |
| customer.payment_source | + | object | An object with payment information |
| customer.payment_source.source_id | +2, -3 | string (24 hex characters) | A customer's payment source ID |
| customer.payment_source.gateway_id | + | string (24 hex characters) | A gateway id |
| customer.payment_source.gateway_type | + | string | A type of the gateway |
| customer.payment_source.gateway_name | + | string | A custom label of the gateway |
| customer.payment_source.type | + | string | A type of the payment source: card for payment sources created with a credit card, checkout for payment sources created with a checkout agreement (checkout button) |
| customer.payment_source.card_name | +1 | string | A cardholder's name (as on card) |
| customer.payment_source.card_number_last4 | +1 | string(numeric) | Card number last 4 digits |
| customer.payment_source.card_number_bin | +1 | string(numeric) | Card BIN number |
| customer.payment_source.card_scheme | +1 | string | A cardholder's scheme (e.g. visa, mastercard etc...) |
| customer.payment_source.expire_month | +1 | string(mm) | A card expiration month |
| customer.payment_source.expire_year | +1 | string(yyyy) | A card expiration year |
| customer.payment_source.address_line1 | - | string | A customer's address, line 1 |
| customer.payment_source.address_line2 | - | string | A customer's address, line 2 |
| customer.payment_source.address_state | - | string | A customer's address, State |
| customer.payment_source.address_country | - | string | A customer's addresss, Country Code |
| customer.payment_source.address_city | - | string | A customer's address, City |
| customer.payment_source.address_postcode | - | string | A customer's address, Postcode |
| schedule | + | object | An object with the subscription schedule information |
| schedule.interval | + | string | An assessment interval: one-off, day, week, month, year |
| schedule.next_assessment | + | string(Date) | A date of the next subscription assessment (payment) |
| schedule.first_assessment | + | string(Date) | A date of the first subscription assessment (payment) |
| schedule.status | + | string | A schedule status. See the Schedule status table |
| schedule.locked | + | boolean | Defines if the schedule is locked |
| schedule.completed_count | + | integer | A count of successful transactions |
| schedule.retry_count | + | integer | A count of transaction retries for unsuccessful payments |
| schedule.frequency | + | string(numeric) | An assessment frequency, 1 is set by default (e.g. “3” = “Every 3 weeks”) |
| schedule.start_date | - | string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ) | A start date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) |
| schedule.end_date | - | string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ) | An end date of the subscription in the ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or in a short type of date (yyyy-mm-dd) |
| schedule.end_amount_after | - | float | A total amount of all successful transactions (equals or exceeds) |
| schedule.end_amount_before | - | float | A total amount of all successful transactions (not to exceed) |
| schedule.end_amount_total | - | float | A total amount to be paid on the subscription (equals). NOTE: If the last payment of the subscription schedule is less than $ 1.00, some gateways may respond with an error and the subscription status will become ‘failed’. |
| schedule.end_transactions | - | integer | A total count of all successful transactions |
| statistics | + | object | An object with statistics information by charge |
| statistics.successful_transactions | + | number | A number of succesfull transactions |
| statistics.total_collected_amount | + | number | A total amount by subscription |
| meta | - | object | An optional object with specific fields for different gateways |
| meta.account_id | - | string | An ID of the existing, connected Stripe account. It is used to create Stripe connect Direct Charges |
| retry | - | object | An optional object with specific fields for retry settings |
| retry.limit | - | integer | A maximum amount of retried payments |
| retry.frequency | - | integer | A retry frequency, 1 is used by default (i.e. “3” = “Every 3 weeks”) |
| retry.interval | - | string | A retry interval. Possible values: week, month, year, day |
| retry.fail_status | - | string | A status of the subscription after all the retries have gone through (active, held, failed, deleted, etc.)## |
Status
| status | description |
|---|---|
| active | A subscription is active, and there are more payments to be collected |
| complete | A subscription is complete, and all payments have been collected |
| deleted | A subscription has been removed |
| failed | This typically occurs when the number of failed payments has been exceeded (see details of an error) |
| expired | A subscription that is complete, and has reached its end date |
| held | A subscription was manually put on hold |
Expire reason
| status | description |
|---|---|
| manual | A subscription was expired manually |
| end_date | A subscription was expired by the end date settings |
| end_amount_total | A subscription was expired by the 'total amount' settings |
| end_amount_before | A subscription was expired by the 'before amount' settings |
| end_amount_after | A subscription was expired by the 'after amount' settings |
| end_transactions | A subscription was expired by the 'count of transaction' settings |
Schedule status
| status | description |
|---|---|
| complete | The payment on the last schedule is processed successfully |
| failed | The payment on the last schedule was not processed successfully |
| held | The held charge on the last schedule is created successfully |