Flow

You can create a subscription using:

  1. One-time token (customer will be created automatically before creating a subscription)
  2. An existing customer (with default or non-default payment source)
  3. Direct with credit card (customer will be created automatically before creating a subscription)
  4. Using vault-token (customer will be created automatically before creating a subscription)
  5. 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

fieldrequired[flow]typedescription
amount+floatAmount of payment
currency+string (iso4217 alpha-3)Currency code
description-stringManually defined description for payments in payment systems
reference-stringManually defined reference for customer in payment systems
token+1string(UUID)One-time token with all the payment source information
customer_id+2, +5string (24 hex characters)Existing customer ID
gateway_id+5string (24 hex characters)Existing gateway ID
customer+3, +4objectObject with the customer’s information.
customer.first_name-stringCustomer first name
customer.last_name-stringCustomer last name
customer.email-stringCustomer email
customer.phone-string(E.164)Customer phone in E.164 international notation (Example: +12345678901)
customer.reference-stringManually defined reference for customer in payment systems
customer.payment_source+objectObject with payment information
customer.payment_source.gateway_id+string (24 hex characters)Gateway id
customer.payment_source.type+stringType of payment. By default card. Use card for payment with credit card.
customer.payment_source.card_name+3stringCardholder name (as on card)
customer.payment_source.card_number+3string(numeric)Card number
customer.payment_source.expire_month+3string(mm)Card expiration month mm
customer.payment_source.expire_year+3string(yyyy)Card expiration year
customer.payment_source.card_ccv-3string(numeric)Card CCV number
customer.payment_source.address_line1-stringCustomer Address, line 1
customer.payment_source.address_line2-stringCustomer Address, line 2
customer.payment_source.address_state-stringCustomer Address, State
customer.payment_source.address_country-stringCustomer Address, Country Code
customer.payment_source.address_city-stringCustomer Address, City
customer.payment_source.address_postcode-stringCustomer Address, Postcode
customer.payment_source.vault_token+4string(UUID)Vault token
schedule+objectObject with subscription schedule information
schedule.interval+stringAssessment 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-floatTotal amount of all successful transactions (equals or exceeds)
schedule.end_amount_before-floatTotal amount of all successful transactions (not to exceed)
schedule.end_amount_total-floatTotal 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-integerTotal count of all successful transactions
meta-objectOptional object with specific fields for different gateways
meta.account_id-stringID of an existing, connected account. Use to create MPGS connect Direct Charges
retry-objectOptional object with specific fields for retry settings
retry.limit-integermaximum amount of retried payments
retry.frequency-integeramount of hours/days between retried payments
retry.interval-stringhours/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-stringa parameter allowing a subscription to be set to particular status upon maximum retries (active, held, failed, deleted) etc.
Language
URL