Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Create a Subscription

POST /subscriptionsplans/v1/subscriptions

Create a Subscription requests allow you to create customer subscriptions/ recurring payment schedules with Paysafe using active product plans.

Before sending an API request to create a subscription for a customer, you must convert the single-use payment handle token (SUT) provided by Paysafe on the initial verification/ authorization to a multi-use payment token (MUT). You must send the MUT as the paymentHandleToken of this API request.

Request Parameters

The request contains the following parameters:

Element Child Element Type Required Description
planId   string<uuid> Yes The Plan ID returned in the response of the Create a Plan request.
Authorization   string Yes

Your Base64 encoded API Key

Default: Basic BASE64-ENCODED-API-KEY
startDate   string<date> No

Start date of the subscription and the date of the first billing. Date format = YYYY-MM-DD, ISO 8601 expected. UTC Date Format.

Note: The start date CANNOT be in the past.

Example:
2023-06-10
additionalNumberOfCycles   number
>= 0
<= 99		 No

The additional number of times this billing cycle is executed after the plan's number of cycles are executed.

Note: The additional number of cycles can only be increased.
paymentHandleToken   string
>= 0 chars
<= 50 chars		 Yes

The payment token generated by Paysafe Payments API that will be used for the Payment request.

Example:
SAJyTBzCvS8YHwwb
discountPercent   number
>= 0
<= 100		 No

A discount that is applied on the subscription's payments.

Example:
10.00
itemQuantity   number
>= 1		 No

Indicates the quantity of goods and services provided in the subscription. When this field is specified, it will be used along with the plan.quantifiableAmount for the billing.

Example:
If you have a subscription for a service that costs $20 and 10 licenses for this service which cost $5 each (the price is specified in the quantifiableAmount field). The total amount that will be charged is calculated as such: amount + subscription.itemQuantity * quantifiableAmount($20 + 10 * $5)
merchantDescriptor   object No

The merchant descriptor that will be displayed on the customer's card or bank statement.
dynamicDescriptor string No

A merchant descriptor that will be displayed on a customer’s card statement.
phone string No

Your merchant phone number that is appended to the merchant descriptor on a customer’s card statement.
statusReason   object Yes

Status Reason.
initiator string Yes

Initiator of the status change reason.

Allowed values:

  • MERCHANT
  • SUBSCRIBER
  • AUTO
message string No

Description for the status change reason.
accountId   string
>= 0 chars
<= 36 chars		 Yes

This is the account with which all of the payments will be processed.

Note: The account currency should be the same with plan currency.
merchantRefNum   string
>= 0 chars
<= 255 chars		 Yes

This is a unique ID that you can use for subscription look-up.

Note: This ID is unique for this accountId. The payments will use other merchantRefNums that are internally generated.
status   string No

Allowed value:
ACTIVE
billingCycleHandling   string No

Allowed values:

  • FIRST_CYCLE_COMPLETED
  • ALL_CYCLES_PENDING
initialTransactionId   string
<= 36 chars		  

Id of the initial Recurring Payment transaction.

  • For billingCycleHandling: FIRST_CYCLE_COMPLETED this id must be the id of Initial Recurring payment transaction. For more information see Create payment.
  • For billingCycleHandling: ALL_CYCLES_PENDING this id must be the id of Initial Recurring verification transaction. For more information see Create verification.

Note: This reference must meet PSD 2 authentication process requirements for merchant initiated transactions successfully.

Example:
a02e52c7-c991-4418-966a-b62989cb0eae
externalInitialTransactionId   string
<= 256 chars		  

Id of the initial Recurring Payment transaction in case this transaction was processed through external PSP.

Note: This reference cannot be provided along with initialTransactionId.

Response Parameters

The response parameters that are not included in the request are described below:

Element Child Element Type Description
creationTime   string<date-time> yyyy-MM-dd'T'HH:mm:ss'Z'
lastdUpdatedTime   string<date-time> yyyy-MM-dd'T'HH:mm:ss'Z'
id   string<uuid> An internally generated ID.
paymentType   string

The payment type associated with the Payment Handle used for this request.

Example:
CARD
plan   object  
name string The name of the plan.
description string The description of the plan.
amount number

The amount of the plan, in minor units.

Note: If your merchant account is set up for a currency that has 3 decimal units, our system will half round up the least significant digit.

Example:
To process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.
quantifiableAmount number

If the subscription quantity is specified then this amount is multiplied by it. This is the quantifiableAmount of the plan, in minor units.

Note: The same restriction applies as in the amount field.

Example:
If you have a subscription for a service that costs $20 and 10 licenses for this service which cost $10 each (the price is specified in the quantifiableAmount field). The total amount that will be charged is calculated as such: amount + subscription.itemQuantity * quantifiableAmount ($20 + 10 * $10)
retryPolicy   object

Retry policy in case of failed payment. If this object is not present, a retry policy with default values will be used.

Note: This setting will apply to all subscriptions. Disabling an active retryPolicy will CANCEL all pending retries.

Example:
If you have frequency DAILY and number of retries 5. If a payment fails it will be retried every day until it is successful for maximum of 5 days.
enabled boolean

If this field is true, then the frequency and numberOfRetries must be provided.

Default = true
frequency string

The frequency of the retry attempts for the failed payment.

Default = DAILY
numberOfRetries number

Maximum number of retries that will be attempted for the failed payment.

Default = 5
setupFee number

The fee which is used to set up a plan and it is charged only once at the beginning. This is the amount of the plan, in minor units. 

Note: If the merchant account is set up for a currency that has 3 decimal units, our system will half round up the least significant digit.

Example:
To process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.
billingCycle   object

This is the setup for the billing cycle.

Example:
If you have MONTHLY frequency, interval of 3 and numberOfCycles 4, this means that you will be billed every 3 months for a total of 4 times (in this case, billed 4 times over the course of 12 months).
frequency string

Frequency shows how often the payment for the plan will be executed.

Example:
MONTHLY
interval number

The number of intervals after which a subscriber is billed. This field is required when a plan is created.

Maximum interval count:

  • DAILY - 365 is the maximum value for interval if the frequency is DAILY.
  • MONTHLY - 12 is the maximum value for interval if the frequency is MONTHLY.
  • YEARLY - 1 is the maximum value for interval if the frequency is YEARLY.
numberOfCycles number The number of times this billing cycle gets executed. Billing cycles can be executed infinite times (value of 0 for numberOfCycles) or a finite number of times (value between 1 and 99 for numberOfCycles). This field is required when a plan is created.
startTime string<date-time>

Start date and time of the plan. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ. You cannot create subscriptions for this plan before this date.

Example:
2023-01-27T10:14:26Z
endTime string<date-time>

End date and time of the plan. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ. You cannot create subscriptions for this plan after this date. Not providing an end date means that the plan can be used indefinitely.

Example:
2024-06-01T09:12:15Z
subscriptionBehaviourOnDeactivation string

This property controls what will happen with the plan's subscriptions when it is deactivated.

The property must be provided either on plan creation or when its status is set to INACTIVE.

  • DO_NOTHING - When a plan is deactivated it will not affect the subscriptions associated with it.
  • TERMINATE_IMMEDIATELY - When a plan is deactivated the subscriptions associated with it will be terminated immediately.
  • TERMINATE_AFTER_NEXT_BILLING - When a plan is deactivated the subscriptions associated with it will be terminated after their next billing.

Example:
If the value of subscriptionBehaviourOnDeactivation is TERMINATE_IMMEDIATELY, then the subscriptions of this plan will be set to status CANCELLED and no further billing will occur.
creationTime string yyyy-MM-dd'T'HH:mm:ss'Z'
lastUpdatedTime string yyyy-MM-dd'T'HH:mm:ss'Z'
id string<uuid>  
currencyCode any

The currency code, for example, USD or CAD. See Currency Codes.

Note: When creating a subscription, the currencyCode specified in the plan must match the processing currency of the account.

Example:
USD
trialPeriod   object

Trial period will be applied only at the beginning of the subscription.

Example:
If the trialPeriod is with amount 0 then for the duration of it, there won't be any billing.
numberOfCycles number How many cycles the trial period will last.
frequency string Frequency shows how often the trial payment for the plan will be executed.
amount number

The amount of the trial period, in minor units.

Note: If your merchant account is set up for a currency that has 3 decimal units, our system will half round up the least significant digit.

Example:
To process US $10.99, this value should be 1099. To process 1000 Japanese yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.
status string
  • INITIAL - This is the status in which you can update all fields of the plan.
  • ACTIVE - This is the status in which you can create subscriptions.
  • INACTIVE - This is the status in which you can NOT create subscriptions.
customerProfile   object  
id string<uuid> The Customer ID in the system.
merchantCustomerId string The reference number for the customer that you create and submit as part of the request. It must be unique for each customer.
locale string Indicates the customer's locale preference.
firstName string The customer’s first name.
lastName string The customer’s last name.
dateOfBirth   object  
year number The year of birth.
month number The month of birth.
day number The day of birth.
gender string Indicates the Customer's gender.
nationality string Indicates the Customer's nationality.
phone string The customer's phone number.
mobile string The customer's mobile number.
email string The customer's email address.
status string The status of customer in the system.
paymentsInformation   object  
previousPayment   object The last processed payment.
id string An internally generated ID from subscriptions API that is used as a merchantRefNum for the payment.
amount number The amount of the payment.
accountId string

The account with which the payment will be processed.

Note: This account is set on subscription creation.
paymentHandleToken string The payment token generated by Paysafe Payments API that will be used for the Payment request.
paymentType string The payment type associated with the Payment Handle used for this request.
scheduledTime string<date-time> The time when the payment is scheduled to be executed.
executionStage string

The execution stage of the subscription.

Example:
TRIAL_PAYMENT
previousPaymentId string<uuid> A reference to the previous processed payment.
originalPaymentId string<uuid>

A reference to the payment for which this retry is initiated.

NOTE: This field is present only for retries.
numberOfRetriesLeft number

The number of retries left initiated for a failed payment.

NOTE: This field is present only for retries.
processedPaymentDetails   object  
id string The ID that is returned from Payments API.
txnTime string<date-time>

The date and time the request was processed.

Example:
2022-12-16T17:45:28Z
status string

The status of the transaction request. Possible values are:

  • COMPLETED – The transaction was completed.
  • HELD – The request has been placed on hold due to risk considerations.
  • FAILED – The transaction failed, due to either an error or being declined.
  • PENDING – The transaction awaiting the payment service provider's response.
error   object  
code string

The error code.

Example:
1000
message string

A description of the error.

Example:
An internal error occurred.
merchantRefNum string  
nextPayment   object The next payment of the billing cycle.
id string An internally generated ID from subscriptions API that is used as a merchantRefNum for the payment.
amount number The amount of the payment.
accountId string

The account with which the payment will be processed.

Note: This account is set on subscription creation.
paymentHandleToken string The payment token generated by Paysafe Payments API that will be used for the Payment request.
paymentType string The payment type associated with the Payment Handle used for this request.
scheduledTime string<date-time> The time when the payment is scheduled to be executed.
executionStage string

The execution stage of the subscription.

Example:
TRIAL_PAYMENT
previousPaymentId string<uuid> A reference to the previously processed payment.
originalPaymentId string<uuid>

A reference to the payment for which this retry is initiated.

Note: This field is present only for retries.
numberOfRetriesLeft number

The number of retries left initiated for a failed payment.

Note: This field is present only for retries.
startTime   string<date-time>

Start date and time of the subscription and the first billing. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.

Note: The start date CANNOT be in the past.

Example:
2023-01-27T10:14:26Z
On this Page