Create a subscription for a customer with a Billing Frequency Type (Daily, Weekly, Biweekly, Monthly, Bimonthly, Quarterly, Semiannually, Yearly), subscription Billing Plans items, the payment method objects list with priorities and tax amount (each object with billing address, billing first name, billing last name, payment method type (credit card, ach, google pay)) or existing payment method object with tax amount (with an authorized payment method id or payment method id) must be provided.
Optionally, a Merchant Subscription Ref ID, Tax Address, Start Date, Trial Duration, Trial Duration Type (the same values as in Billing Frequency Type), Subscription Status Type (Current, Recycle) and Subscription Cancel Type (Immediate, EndOfCycle) may be included.
Upon successful creation of the subscription, a status code of 201 (Created) will be returned.
If the provided Customer ID does not exist, a status code of 404 (Not Found) will be returned.
If a subscription cannot be created with the provided data, a status code of 400 (Bad Request) will be returned.
Description of request parameters
- paymentMethods
Conditional. At least one payment method is required if an existing payment method is not supplied.
No validation rules- billingAddress
Optional
The address associated with a payment method that is used for billing purposes. Either an Address ID or detailed address information can be provided.
No validation rules- addressId
Optional
The unique identifier of the address.
No validation rules- addressLine1
Optional
Address
Validation rules:- The length should be between 2 and 40 characters
- addressLine2
Optional
Supplemental information for the address.
Validation rules:- Maximum length 40 characters
- city
Optional
City
Validation rules:- The length should be no more than 25 characters
- state
Optional
Two-letter state abbreviation
Validation rules:- Must be 2 characters in length
- postalCode
Optional
Postal code
Validation rules:- The length should be between 2 and 20 characters
- phoneNumber
- Optional
The phone number associated with a payment method that is used for billing purposes.
- The length must not exceed 18 characters if a Nuvei processor is used.
Optional
The email associated with a billing address.
No validation rules- country
Optional
Country
Validation rules:- The input must be a valid Alpha2 code, Alpha3 code, UN code, or full country name
- billingFirstName
Required
The customers’s first name associated with a payment method that is used for billing purposes.
No validation rules- billingLastName
Required
The customers’s last name associated with a payment method that is used for billing purposes.
No validation rules- creditCard
Conditional. One payment method type is required if neither the payment method ID nor the payment method authorization ID is supplied in an existing payment method.
Payment card information.
Validation rules:- Only one payment method type can be supplied
- paymentAccountNumber
- Conditional. The PAN is required if the credit card payment method type is supplied in the request.
Validation rules:
- The number must be a valid credit card number and will be verified using the Luhn algorithm.
- expirationDate
Conditional. The expiration date is required if the credit card payment method type is supplied in the request.
The card expiration date.
Validation rules:- Must be in one of the following formats: MMYY, MMYYYY, MM/YYY and MM/YYYYY
- securityCode
Optional
The card verification code. It is considered best practice to always include this value for card-not-present transactions. Failure to do so may lead to higher rates of declines, an increase in chargeback cases, and/or transaction downgrades.
Validation rules:- The length should be between 3 and 4 characters
- ach
Conditional. One payment method type is required if neither the payment method ID nor the payment method authorization ID is supplied.
ACH account information.
Validation rules:- Only one payment method type can be supplied
- routingNumber
Conditional. The routing number is required if the ACH payment method type is supplied in the request.
The 9-digit ACH routing number of the account.
Validation rules:- Must be 9 characters in length
- accountNumber
Conditional. The account number is required if the ACH payment method type is supplied in the request.
The US bank account number from which the payment will be debited.
Validation rules:- The length should be between 4 and 17 characters
- accountType
Conditional. The account type is required if the ACH payment method type is supplied in the request.
Bank account type.
Validation rules:- Possible values: Checking or Savings
- googlePay
Conditional. One payment method type is required if neither the payment method ID nor the payment method authorization ID is supplied.
GooglePay information.
Validation rules:- Only one payment method type can be supplied
- googlePayPaymentDataResponse
Conditional. The GooglePayPaymentDataResponse is required if the GooglePay payment method type is supplied in the request.
The data returned by Google Pay.
Validation rules:- Must contain the valid serialized JSON object
- merchantPaymentMethodRefId
Conditional. A merchantPaymentMethodRefId is required if the eligibility check is configured.
Merchant's unique identifier for the payment method.
No validation rules- priority
Conditional. The priority is required if at least one payment method is supplied.
The priority of the payment method. The numbers should follow a sequence, starting from 0 and incrementing by one.
Validation rules:- Must be greater than or equal to 0
- taxAmount
Optional
Tax amount associated with billing address.
Validation rules:- Must be greater than or equal to 0
- originalNetworkTransactionId
- Optional
Element defines the networkTransactionId returned in the response messages for Visa, Mastercard, and Discover Auth/Sale transactions. You must include this element and the original value returned for subsequent (after the initial) Visa, Mastercard or Discover recurring/installment payments.
Follow the link or contact Revolv3 support for more information.
No validation rules
- existingPaymentMethod
Conditional. An existing payment method is required if payment methods are not supplied.
Existing payment method identifiers with additional information.
Validation rules:- PaymentMethodAuthorizationId OR paymentMethodId must be specified in the existingPaymentMethod.
- paymentMethodAuthorizationId
Conditional. A payment method authorization ID is required if neither the payment methods array nor the payment method ID is supplied.
Unique identifier for a previously pre-authorized payment method.
No validation rules- paymentMethodId
Conditional. A payment method ID is required if neither the payment method authorization ID nor the payment methods array is supplied.
Unique identifier for the customer's payment information.
No validation rules- merchantSubscriptionRefId
Conditional. A merchantSubscriptionRefId is required if the eligibility check is configured.
Merchant's unique identifier for the subscription.
No validation rules- billingFrequencyType
Required
How often the subscription should be attempted for billing.
Validation rules:- Possible values: Daily, Weekly, Biweekly, Monthly, Bimonthly, Quarterly, Semiannually, Yearly
- subscriptionStatusType
Optional. Default value - Current.
The subscription's current standing.
Validation rules:- Possible values: Current, Recycle, Cancelled, PendingCancellation
- subscriptionCancelType
Optional. Default value - EndOfCycle.
The circumstances under which a subscription must be cancelled.
Validation rules:- Possible values: Immediate, EndOfCycle
- startDate
Optional. Default value - Today.
Start date of the subscription.
No validation rules- trialDuration
Optional. Default value - 0.
The amount of trial duration time in the unit of TrialDurationType.
Validation rules:- Must be greater than or equal to 0
- trialDurationType
Optional. Default value - Daily.
The type of trial duration.
Validation rules:- Possible values: Daily, Weekly, Biweekly, Monthly, Bimonthly, Quarterly, Semiannually, Yearly
- taxAddress
Optional
Address to be used for taxation purposes.
No validation rules- includeRawProcessorResponse
Optional. Default: false.
Determine whether to return raw processor data in the response.
No validation rules- customer
Required
Customer information.
No validation rules- id
Optional
The unique identifier of the customer.
No validation rules
- firstName
Conditional. The first name is required if the customer ID is not provided.
Customer's first name.
Validation rules:- Either the CustomerId or the customer's first and last name should be provided
- lastName
Conditional. The last name is required if the customer ID is not provided.
Customer's last name.
Validation rules:- Either the CustomerId or the customer's first and last name should be provided
- subscriptionBillingPlans
Required
The subscription's individual billing items.
Validation rules:
At least one standard plan must be included into subscription. Only one price overriding plan can be included into subscription.- Must contain at least one plan with standard type.
- Should contain no more than 1 plan with price override type.
- The total amount, considering the types of billing plans, must not be less than zero.
- name
Required
Name of the subscription billing plan.
No validation rules- value
Required
Value for which the billing plan should be executed for.
Validation rules:- Must be greater than or equal to 0
- In case the valueType is DiscountPercentage, the length must be between 0 and 100 characters
- cycleCount
Optional. Default value: -1 (unlimited number of cycles).
The number of times the billing plan should be billed before expiration.
Validation rules:- Must be greater than 0 or equal to -1.
- valueType
Optional. Default value: Standard.
A qualifier for how the value should be interpreted.
Validation rules:- Possible values: Standard, Discount, DiscountPercentage, FinalDiscount, PriceOverride
- startCycleDelay
Optional. Default value: 0.
The amount of days by which to delay the start date of the billing plan's subscription cycle.
Validation rules:- Must be greater than or equal to 0
- recycleImmediatePayment
Optional. Default value: false.
The parameter defines whether the very first subscription payment should be recycled if failed for a subscription with the start date today or earlier in case the recycle schedule is configured for the Merchant.
No validation rules.
Description of response parameters
- processorRawResponse
- Conditional. The value is returned if includeRawProcessorResponse = true.
This field contains the raw data received from the processor after attempting to bill this payment. It does not contain any sensitive information. The field value is a string with the serialized response from the processor in JSON format.