Subscriptions Endpoint
Learn how to use the Subscriptions endpoint to create recurring payments with cards.
Subscription API Requests
A request made through the Subscription API allows you to charge the users a recurring amount on their cards, either by sending the Card Details on the request if you are PCI Compliant or by redirecting the user to our hosted payment page where we will collect the card details allowing you to remain PCI Compliant.
When the credit_card
object is sent, the transaction is confirmed (or denied) synchronously, therefore you can continue the payment flow on your page transparently. With the Hosted Checkout, we send you a webhook once the user completes the payment.
PCI Compliant Subscriptions Endpoint
The usage of this endpoint with the credit_card
object is restricted to PCI Compliant merchants* who have shared their PCI AOC certificate with their Account Manager.
Subscription creation
POST
https://cc-api-stg.directa24.com/v3/subscriptions
This endpoint allows you to generate recurring cards transactions by sending the card details and the recurring options
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string |
|
X-Date* | string | ISO8601 Datetime with Timezone:
|
X-Login* | string | Merchant X-Login API Key |
Authorization* | string | Authorization control hash |
X-Idempotency-Key | string | Unique idempotency key |
Request Body
Name | Type | Description |
---|---|---|
country* | string | Country of the transaction |
amount* | number | Amount of the transaction |
currency* | string | Currency of the amount specified |
invoice_id* | string | Unique deposit ID on the merchant end |
payer* | object | Object containing details about the customer. See "Payer object" section for details |
credit_card* | object | Object containing the credit card details |
description | string | Descriptor for the transaction |
client_ip* | string | Valid IPv4/v6 Address of the customer |
device_id | string | Unique customer's device ID created using our JS library |
fee_on_payer | boolean | Used to specify if you want to let the customer assume the deposit fee |
subscription* | object | Object containing the details of the subscription |
Request Example with Card Details
Redirect Subscriptions Endpoint
Subscription creation
POST
https://api-stg.directa24.com/v3/subscriptions
This endpoint allows you to generate recurring cards transactions by sending the recurring options, and avoiding the card details.
Headers
Name | Type | Description |
---|---|---|
Content-Type* | string |
|
X-Date* | string | ISO8601 Datetime with Timezone:
|
X-Login* | string | Merchant X-Login API Key |
Authorization* | string | Authorization control hash |
X-Idempotency-Key | string | Unique idempotency key |
Request Body
Name | Type | Description |
---|---|---|
country* | string | Country of the transaction |
amount* | number | Amount of the transaction |
currency* | string | Currency of the amount specified |
invoice_id* | string | Unique deposit ID on the merchant end |
payer* | object | Object containing details about the customer. See "Payer object" section for details |
description | string | Descriptor for the transaction |
client_ip* | string | Valid IPv4/v6 Address of the customer |
device_id | string | Unique customer's device ID created using our JS library |
fee_on_payer | boolean | Used to specify if you want to let the customer assume the deposit fee |
subscription* | object | Object containing the details of the subscription |
Request Example without Card Details
Response Fields Details
Response Fields
Field name | Format | Description |
---|---|---|
| Integer | IF of the subscription generated on our ID. Store this ID for future reference |
| Integer | ID of the deposit generated on our end. Store this ID for future reference |
| String | ID of the user. If you didn't send it, it is generated by us |
| String | ID of the deposit on your end. If you didn't send it, it is generated by us |
| String | URL to redirect the user to our Hosted Checkout. Only shown if you didn't send the |
| Object | Object containing the information about the payment |
| String | Type of transaction (Always CREDIT_CARD) |
| String | Status of the transaction: [SUCCESS, REJECTED, PENDING] |
| String | Transaction result. Only shown in case of rejection |
| String | Code of the result. Only shown in case of rejection |
| String | Payment method code. See the list here. |
| String | Payment method name. See the list here. |
| Array | An array of the card types supported. Only shown if you didn't send the |
| Number | Amount sent to the card acquirer |
| String | Currency of the amount sent to the card acquirer |
| String | Transaction date time |
| String | Transaction expiration datetime |
| Object | Object containing information about the Subscription |
| Number | Payment period with 0 meaning the initial payment |
| String | Type of subscription |
| String | Datetime in which the subscription started |
| String | Datetime in which the subscription ends |
Error Response Fields Details
Response Fields
Field name | Format | Description |
---|---|---|
| Number | Error code. See the list of error codes |
| String | Description of the error |
| String | Details about the errors. It is shown in case of invalid details |
| String | Error code name. It is not always shown. See the list of error codes |
Response Examples
Status reasons
Along with every REJECTED transaction, we will provide you with a reason
and a reason_code
you can use to map the error codes on your end.
Transaction status | Reason code | Reason |
|
| The card issuer rejected the payment because of their anti-fraud rules |
|
| Transaction type is not supported for acquirer |
|
| Invalid credit card number |
|
| Invalid card holder |
|
| Invalid expiration date |
|
| Invalid CVV/CVV2 |
|
| Invalid card issuer |
|
| Invalid card pin |
|
| Payment duplicated |
|
| Max attempts reached for this user and card |
|
| Insufficient funds |
|
| The transaction was rejected because the user needs to call their bank to activate the card |
|
| Credit card bin number not found |
|
| Credit card expired |
|
| Card declined by issuer |
|
| Card reported as stolen |
|
| Card reported as lost |
|
| The card was blocked by the bank |
|
| The card is requested by the bank |
|
| Card blacklisted |
|
| Card disabled |
|
| Generic rejection reason |
Request Fields Description
Field name | Format | Description | Default | Validations | Required |
---|---|---|---|---|---|
| string (length: 2) | Country code of the deposit in ISO 3166-1 alpha-2 code format | Yes | ||
| decimal (max decimals: 2) | Deposit amount in the currency specified | Number of up to 18 integers and 2 decimals places | Yes | |
| string (length: 3) | Currency code of the amount in ISO 4217 format |
| See Currencies | Yes |
| string (max length: 128) | Unique deposit ID on the merchant end | random string |
| Yes |
| object[] | Yes | |||
| object[] | Yes | |||
| object[] | Yes | |||
| string (max length: 100) | Transaction description. It could be shown on the customers credit card extract | String of up to 100 characters | No | |
| string | Valid IPv4 or IPv6 Address |
| Yes | |
| string (max length: 100) | Unique customer's device ID created using our JS library. Used to identify and prevent fraud | String of up to 100 characters | No | |
| boolean | Choose if the deposit's fee will be paid by the customer or debited from your balance |
|
| No |
Request Objects
Subscription Object
Field name | Format | Description | Required |
---|---|---|---|
| ISO8601 Datetime with Timezone:
| Datetime that will start the subscription billing cycle. | Yes |
| Value of enum: [ | Frequency of collections. It can be | Yes |
| integer | Amount of times that the subscription will be charged. | Yes |
| boolean | Used to indicate if the subscription will auto-renovate after a complete billing cycle. | Yes |
Credit Card Object
Field name | Format | Description | Validations | Required |
| String (max length: 4 digits) | Credit card CVV/CVV2 code |
size must be between 3 and 4 | Yes |
| String (max length: 16 digits) | The credit card number consisting of up to 16 digits | Yes | |
| String(length: 2) | Credit card expiration month |
| Yes |
| String(length: 2) | Credit card expiration year last two digits |
Valid year: 25 | Yes |
| String (max length: 256) | The name of the credit card owner | Valid name | Yes |
Payer Object
Field name | Format | Description | Default | Validations | Required |
---|---|---|---|---|---|
| string (max length: 128) | Customer's ID generated on your end. Used to locate user's transaction on our Merchant Panel | If none is sent, we will autogenerate it |
| Recommended |
| string (max length: 30) | Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits | Yes | ||
| string (max length: 10) | Customer's document type. Optional, if sent must be a valid document type | Yes | ||
| string (max length: 255) | Valid customer's email address | Valid email address | Yes | |
| string (max length: 128) | Customer's first name | String of up to 128 characters | Yes | |
| string (max length: 128) | Customer's last name | String of up to 128 characters | Yes | |
| object[] | No | |||
| string (max length: 32) | Valid customer's phone number | No | ||
| string (max length: 8) | Customer's birthdate in format yyyyMMdd. E.g.: 19801027 | Numeric format expected: | No |
Payer.address Object
Field name | Format | Description | Validations | Required |
| string (max length: 255) | Customer's street | String of up to 255 characters | No |
| string (max length: 128) | Customer's city | String of up to 128 characters | No |
| string (max length: 3) | Customer's state code in ISO 3166-2 code format | Valid state code in ISO 3166-2 format. Check our States endpoint here | No |
| string (max length: 16) | Customer's zip code | No |
Last updated