post http://{{url}}/v1/subscriptions
Flow
You can create a subscription using:
- One-time token (customer will be created automatically before creating a subscription)
- An existing customer (with default or non-default payment source)
- Direct with credit card (customer will be created automatically before creating a subscription)
- Using vault-token (customer will be created automatically before creating a subscription)
- An existing customer (with default or non-default vault token payment source)
Subscriptions can run on different intervals (ie daily, weekly, monthly etc) and frequencies (ie ‘every X days’). You can also control the start date for a subscription.
Subscriptions can also be configured to end after:
- a certain number of transactions
- an amount (eg end before reaching $1000 or end after reaching $1000)
- a date
If a subscription is created without a customer ID, a new customer will be created and the customer ID will be returned in the response.
Request body
| field | required[flow] | type | description |
|---|---|---|---|
| amount | + | float | Amount of payment |
| currency | + | string (iso4217 alpha-3) | Currency code |
| description | - | string | Manually defined description for payments in payment systems |
| reference | - | string | Manually defined reference for customer in payment systems |
| token | +1 | string(UUID) | One-time token with all the payment source information |
| customer_id | +2, +5 | string (24 hex characters) | Existing customer ID |
| gateway_id | +5 | string (24 hex characters) | Existing gateway ID |
| customer | +3, +4 | object | Object with the customer’s information. |
| customer.first_name | - | string | Customer first name |
| customer.last_name | - | string | Customer last name |
| customer.email | - | string | Customer email |
| customer.phone | - | string(E.164) | Customer phone in E.164 international notation (Example: +12345678901) |
| customer.reference | - | string | Manually defined reference for customer in payment systems |
| customer.payment_source | + | object | Object with payment information |
| customer.payment_source.gateway_id | + | string (24 hex characters) | Gateway id |
| customer.payment_source.type | + | string | Type of payment. By default card. Use card for payment with credit card. |
| customer.payment_source.card_name | +3 | string | Cardholder name (as on card) |
| customer.payment_source.card_number | +3 | string(numeric) | Card number |
| customer.payment_source.expire_month | +3 | string(mm) | Card expiration month mm |
| customer.payment_source.expire_year | +3 | string(yyyy) | Card expiration year |
| customer.payment_source.card_ccv | -3 | string(numeric) | Card CCV number |
| customer.payment_source.address_line1 | - | string | Customer Address, line 1 |
| customer.payment_source.address_line2 | - | string | Customer Address, line 2 |
| customer.payment_source.address_state | - | string | Customer Address, State |
| customer.payment_source.address_country | - | string | Customer Address, Country Code |
| customer.payment_source.address_city | - | string | Customer Address, City |
| customer.payment_source.address_postcode | - | string | Customer Address, Postcode |
| customer.payment_source.vault_token | +4 | string(UUID) | Vault token |
| schedule | + | object | Object with subscription schedule information |
| schedule.interval | + | string | Assessment interval one-off, week, month, year, day |
| schedule.frequency | + | string(numeric) | Assessment frequency, 1 by default (i.e. “3” = “Every 3 weeks”) |
| schedule.start_date | - | string(Date) | Start date, ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) |
| schedule.end_date | - | string(Date) | End date, ISO 8601 format (yyyy-mm-ddThh:mm:ss.sssZ) or short type of date (yyyy-mm-dd) or specify time offsets from UTC (yyyy-mm-ddThh:mm:ss+hh:mm) |
| schedule.end_amount_after | - | float | Total amount of all successful transactions (equals or exceeds) |
| schedule.end_amount_before | - | float | Total amount of all successful transactions (not to exceed) |
| schedule.end_amount_total | - | float | Total amount to be paid with subscription (equals). NOTE: If last payment of subscription schedule will be less then $ 1.00, some gateways may respond with error and subscription status will become ‘failed’. |
| schedule.end_transactions | - | integer | Total count of all successful transactions |
| meta | - | object | Optional object with specific fields for different gateways |
| meta.account_id | - | string | ID of an existing, connected account. Use to create MPGS connect Direct Charges |
| retry | - | object | Optional object with specific fields for retry settings |
| retry.limit | - | integer | maximum amount of retried payments |
| retry.frequency | - | integer | amount of hours/days between retried payments |
| retry.interval | - | string | hours/days (I’ve added this to account for daylight savings etc. If customers want payments to be attempted at same time every day) |
| retry.fail_status | - | string | a parameter allowing a subscription to be set to particular status upon maximum retries (active, held, failed, deleted) etc. |