--- title: "Creates a new subscription" method: POST path: "/subscriptions" tags: ["Subscriptions"] --- # Creates a new subscription `POST /subscriptions` Use to create a Subscription (whereby Ryft manage the automatic scheduling and billing of a recurring payment series) ## Request body - object — The request body for creating a subscription - `customer` object, required — The customer the subscription is for - `id` string — The id of the customer - `price` object, required — Defines how much and how often to charge the customer for the subscription - `amount` integer — The amount (in minor units) that is charged on each recurring payment throughout the subscription. Minimum and maximum amounts [vary by currency](https://developer.ryftpay.com/documentation/overview/core_concepts/currencies). - `currency` string — The ISO currency code - `interval` RecurringIntervalRequest - `unit` 'Days' | 'Months', required — The type of interval to wait for between charges - `count` number, required — The number of intervals between charges. e.g. `type = Days` & `count = 60` would charge the customer every 60 days. - `times` number, nullable — (optional) The total number of charges throughout the lifecycle of the recurring series. Leave `null` for products that continue indefinitely. - `paymentMethod` object — Use if you want to select an already stored card on file for the subscription and skip collecting new payment details from your customer. Must belong to the `customerId` provided in this request. Note that 3DS will be required on the initial payment. - `id` string — The Id of an already stored PaymentMethod belonging to the customer that you want to use to pay for the subscription. Note that this is optional. If not supplied the subscription will require you to collect card details from your customer. - `description` string, nullable — (optional) description that helps you personalise/identify the specific subscription - `billingCycleTimestamp` number, nullable — The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month. Defaults to today if not provided. - `metadata` object — use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata. - `shippingDetails` ShippingDetails, nullable - `address` object, nullable - `firstName` string — The first name of the customer - `lastName` string — The last name of the customer - `lineOne` string — First line of the address - `lineTwo` string — Second line of the address - `city` string — The address city/town - `country` string, required — The two-character ISO country code - `postalCode` string, required — The postal code/zip of the address - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code - `phoneNumber` string, nullable — The phone number of the recipient receiving the goods, in E.164 format - `paymentSettings` object, nullable — Settings for controlling fields/options on the underlying Payment Session's created by this subscription. - `statementDescriptor` StatementDescriptor - `descriptor` string — The statement descriptor that will be shown on the customer's bank statement for this payment. If you don't specify this then the descriptor set on your account will be used instead. It must satisfy the following regex pattern: ^[A-Za-z0-9 ]*[A-Za-z][A-Za-z0-9 ]*$ - `city` string — This is the city that will be shown on the statements of the account's customers. If you don't specify this then the descriptor set on your account will be used instead. It must satisfy the following regex pattern: ^[A-Za-z0-9 ]*[A-Za-z][A-Za-z0-9 ]*$ ## Response `200` The subscription was created successfully - Subscription - `id` string — The ID of the subscription - `status` 'Pending' | 'Active' | 'Cancelled' | 'PastDue' | 'Ended' | 'Paused' - `description` string, nullable — (optional) description helps you personalise/identify the specific subscription - `customer` object - `id` string — The Id of the customer this subscription belongs to - `paymentMethod` object, nullable - `id` string — The Id of the PaymentMethod belonging to the customer that will be used to pay for the subscription - `paymentSessions` object - `initial` SubscriptionPaymentSession - `id` string — The Id of the PaymentSession - `clientSecret` string, nullable — The client secret of the payment session, only supplied when action is required by the customer Supply this to the frontend (web/iOS/Android) to collect the payment details / handle any required actions (3ds) - `requiredAction` RequiredAction, nullable — The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS) - `type` 'Redirect' | 'Identify' | 'Challenge' — The type of action - `url` string, nullable — The url to redirect to (if the requiredAction has type `Redirect`) - `identify` union - object, nullable — Contains the details required to perform device data collection during 3DS (for browser/web authentication only) We recommend using our embedded SDK to handle this action for you. - `uniqueId` string, nullable — A uniqueId used to identify the transaction within the 3ds-server - `threeDsMethodUrl` string - `threeDsMethodSignature` string - `sessionId` string - `sessionSecret` string - `threeDsMethodData` string - `scheme` string - `paymentMethodId` string — The Id of the tokenized payment method belonging to this 3DS session - object, nullable — Contains the details required to perform device data collection during 3DS (for native iOS & Android) **Note** that this is subject to change and should only be handled by our native SDKs. - `sessionId` string - `sessionSecret` string - `scheme` string, required - `paymentMethodId` string, required — The Id of the tokenized payment method belonging to this 3DS session - `protocolVersion` string — The 3DS message protocol version the native SDK should target when creating the Ravelin transaction. - `ravelinPublicKey` string — The Ravelin public API key. Used as a Bearer token when initialising the Ravelin 3DS service on iOS / Android. - `challenge` union — Details required to perform the 3DS challenge step for browser/web or native iOS & Android flows. - object - `acsUrl` string, required — Fully qualified URL of the ACS to be used for the 3DS challenge - `cReq` string, required — base64 encoded challenge request message - `threeDSServerTransactionID` string — 3DS Server transaction ID issued for this authentication. - `acsTransactionID` string — ACS transaction ID returned by the issuer's ACS. - `acsRefNumber` string — ACS reference number identifying the issuer's ACS implementation. - `acsSignedContent` string — Signed JWS from the ACS containing the challenge protocol data. - object - `acsUrl` string — Fully qualified URL of the ACS to be used for the 3DS challenge - `cReq` string — base64 encoded challenge request message - `threeDSServerTransactionID` string, required — 3DS Server transaction ID issued for this authentication. - `acsTransactionID` string, required — ACS transaction ID returned by the issuer's ACS. - `acsRefNumber` string, required — ACS reference number identifying the issuer's ACS implementation. - `acsSignedContent` string, required — Signed JWS from the ACS containing the challenge protocol data. - `latest` SubscriptionPaymentSession - `id` string — The Id of the PaymentSession - `clientSecret` string, nullable — The client secret of the payment session, only supplied when action is required by the customer Supply this to the frontend (web/iOS/Android) to collect the payment details / handle any required actions (3ds) - `requiredAction` RequiredAction, nullable — The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS) - `type` 'Redirect' | 'Identify' | 'Challenge' — The type of action - `url` string, nullable — The url to redirect to (if the requiredAction has type `Redirect`) - `identify` union - object, nullable — Contains the details required to perform device data collection during 3DS (for browser/web authentication only) We recommend using our embedded SDK to handle this action for you. - `uniqueId` string, nullable — A uniqueId used to identify the transaction within the 3ds-server - `threeDsMethodUrl` string - `threeDsMethodSignature` string - `sessionId` string - `sessionSecret` string - `threeDsMethodData` string - `scheme` string - `paymentMethodId` string — The Id of the tokenized payment method belonging to this 3DS session - object, nullable — Contains the details required to perform device data collection during 3DS (for native iOS & Android) **Note** that this is subject to change and should only be handled by our native SDKs. - `sessionId` string - `sessionSecret` string - `scheme` string, required - `paymentMethodId` string, required — The Id of the tokenized payment method belonging to this 3DS session - `protocolVersion` string — The 3DS message protocol version the native SDK should target when creating the Ravelin transaction. - `ravelinPublicKey` string — The Ravelin public API key. Used as a Bearer token when initialising the Ravelin 3DS service on iOS / Android. - `challenge` union — Details required to perform the 3DS challenge step for browser/web or native iOS & Android flows. - object - `acsUrl` string, required — Fully qualified URL of the ACS to be used for the 3DS challenge - `cReq` string, required — base64 encoded challenge request message - `threeDSServerTransactionID` string — 3DS Server transaction ID issued for this authentication. - `acsTransactionID` string — ACS transaction ID returned by the issuer's ACS. - `acsRefNumber` string — ACS reference number identifying the issuer's ACS implementation. - `acsSignedContent` string — Signed JWS from the ACS containing the challenge protocol data. - object - `acsUrl` string — Fully qualified URL of the ACS to be used for the 3DS challenge - `cReq` string — base64 encoded challenge request message - `threeDSServerTransactionID` string, required — 3DS Server transaction ID issued for this authentication. - `acsTransactionID` string, required — ACS transaction ID returned by the issuer's ACS. - `acsRefNumber` string, required — ACS reference number identifying the issuer's ACS implementation. - `acsSignedContent` string, required — Signed JWS from the ACS containing the challenge protocol data. - `price` RecurringPrice - `amount` integer — The amount (in minor units) that is charged on each recurring payment - `currency` string — The ISO currency code - `interval` RecurringInterval - `unit` 'Days' | 'Months' — The type of interval to wait for between charges - `count` number — The number of intervals between charges. e.g. `type = Days` & `count = 60` would charge the customer every 60 days. - `times` number, nullable — (optional) The total number of charges throughout the lifecycle of the recurring series. Leave `null` for products that continue indefinitely. - `balance` SubscriptionBalance — The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price) - `amount` integer — The amount owed (in minor units of the currency in price) - `pausePaymentDetail` object, nullable — Non-null if you have paused payments for the subscription. - `reason` string, nullable — Field describing why the subscription is paused. - `resumeAtTimestamp` number, nullable — The epoch timestamp (seconds) when the subscription should resume collecting payments - `pausedAtTimestamp` number — The epoch timestamp (seconds) when the subscription was paused - `cancelDetail` object, nullable — Non-null if the subscription is cancelled - `reason` string, nullable — Field describing why the subscription is cancelled. - `cancelledAtTimestamp` integer — The epoch timestamp (seconds) when the subscription was cancelled - `billingDetail` object - `totalCycles` number — The total number of billing cycles throughout the lifespan of the subscription. - `currentCycle` number — The subscription's current billing cycle. e.g. given a monthly subscription for a 12 month recurring product, where the current date is 4 months removed from the initial charge will have `currentCycle = 4` - `currentCycleStartTimestamp` number — The (epoch) timestamp representing the start date for the current billing period. - `currentCycleEndTimestamp` number — The (epoch) timestamp representing the end date for the current billing period. - `billingCycleTimestamp` number — The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month. - `nextBillingTimestamp` number, nullable — The (epoch) timestamp representing the date on which we will next try to bill your customer. This will be equal to the `billingCycleTimestamp` at the start of each new billing cycle, but is updated should we fail to successfully charge the customer. The updated timestamp reflects when our recurring engine will retry payment. When 'null' it means that we are not currently planning to bill the customer again (it is Cancelled, Ended or Paused indefinitely) - `failureDetail` object, nullable — Non-null if the Subscription has become `PastDue` and one or more payment attempts have been unsuccessful. - `paymentAttempts` number — The number of consecutive payment attempts that have failed. - `lastPaymentError` 'insufficient_funds' | 'declined_do_not_honour' | 'invalid_card_number' | 'cvv2_failure' | 'restricted_card' | 'blacklisted_card' | 'blacklisted_bin' | 'blacklisted_country' | 'blacklisted_ip' | 'risk_declined' | 'security_violation' | 'expired_card' | 'gateway_reject' | 'suspected_fraud' | 'contact_issuer' | 'not_permitted' | 'invalid_account' | 'pickup_card' | 'stolen_card' | 'issuer_decline' | 'closed_account' | 'account_not_activated' | 'limit_exceeded' | 'withdrawal_limit_exceeded' | 'blocked_by_cardholder' | '3ds_authentication_failure' | '3ds_cardholder_not_participating' | '3ds_authentication_required' | 'payment_method_option_amex_disabled' | 'cvc_required' | 'payment_method_not_available' | 'payment_method_option_amex_not_available' | 'credit_card_not_permitted' | 'issuer_error' | 'system_error' | 'unknown_error', nullable — The most recent error when attempting to Pay. Note that we may add further values without notice. - `shippingDetails` ShippingDetails, nullable - `address` object, nullable - `firstName` string — The first name of the customer - `lastName` string — The last name of the customer - `lineOne` string — First line of the address - `lineTwo` string — Second line of the address - `city` string — The address city/town - `country` string, required — The two-character ISO country code - `postalCode` string, required — The postal code/zip of the address - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code - `phoneNumber` string, nullable — The phone number of the recipient receiving the goods, in E.164 format - `metadata` object, nullable — use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata. - `paymentSettings` object — Settings for controlling fields/options on the underlying Payment Session's created by this subscription. - `statementDescriptor` NullableStatementDescriptor, nullable - `descriptor` string — The statement descriptor that will be shown on the customer's bank statement for this payment. If you don't specify this then the descriptor set on your account will be used instead. It must satisfy the following regex pattern: ^[A-Za-z0-9 ]*[A-Za-z][A-Za-z0-9 ]*$ - `city` string — This is the city that will be shown on the statements of the account's customers. If you don't specify this then the descriptor set on your account will be used instead. It must satisfy the following regex pattern: ^[A-Za-z0-9 ]*[A-Za-z][A-Za-z0-9 ]*$ - `createdTimestamp` integer — The epoch timestamp (seconds) when the subscription was created ## Other responses - `400` — One or more inputs are invalid - `500` — An unexpected error occurred when executing this request --- [API](https://skmtc.net/ryftpay/apis/ryft-payment-api.md) · [All operations](https://skmtc.net/ryftpay/apis/ryft-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ryftpay/ryft-payment-api/versions/a042f64d4305/schema)