Subscriptions Endpoint
Learn how to use the Subscriptions endpoint to create recurring payments with cards.
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.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.post
https://cc-api-stg.directa24.com
/v3/subscriptions
Subscription creation
Request JSON
Response JSON
Subscription API
{
"invoice_id": "800000001",
"amount": 1000,
"country": "BR",
"currency": "BRL",
"payer": {
"id": "11111",
"document": "84932568207",
"email": "[email protected]",
"first_name": "John",
"last_name": "Smith",
"address": {
"street": "Calle 13",
"city": "bahia",
"state": "SP",
"zip_code": "12345-678"
}
},
"credit_card": {
"cvv": "123",
"card_number": "4111111111111111",
"expiration_month": "10",
"expiration_year": "25",
"holder_name": "JOHN SMITH"
},
"subscription": {
"start_date": "2023-04-12",
"plan": "MONTHLY",
"plan_unit": 3,
"auto_renewal": false
},
"description": "Monthly subscription. Pack premium",
"client_ip": "123.123.123.123",
"device_id": "knakvuejffkiebyab",
"fee_on_payer": false
}
Response Example
{
"subscription_id": 700000001,
"deposit_id": 300604089,
"user_id": "80000001",
"merchant_invoice_id": "test82347893",
"payment_info": {
"type": "CREDIT_CARD",
"result": "SUCCESS",
"payment_method": "VI",
"payment_method_name": "Visa",
"amount": 1000.00,
"currency": "BRL",
"created_at": "2022-03-15 12:24:53"
}
"subscription_info": {
"payment_period": 0,
"type": "monthly",
"start_date": "2022-03-15 12:24:53",
"end_date": "2023-03-01 00:00:00"
}
}
post
https://api-stg.directa24.com
/v3/subscriptions
Subscription creation
Request JSON
Response JSON
Webhook JSON
Subscription API
{
"invoice_id": "800000001",
"amount": 1000,
"country": "BR",
"currency": "BRL",
"payer": {
"id": "11111",
"document": "84932568207",
"email": "[email protected]",
"first_name": "John",
"last_name": "Smith",
"address": {
"street": "Calle 13",
"city": "bahia",
"state": "SP",
"zip_code": "12345-678"
}
},
"subscription": {
"start_date": "2023-04-12",
"plan": "MONTHLY",
"plan_unit": 3,
"auto_renewal": false
},
"notification_url": "https://webhook.site/token", "
"description": "Monthly subscription. Pack premium",
"client_ip": "123.123.123.123",
"device_id": "knakvuejffkiebyab",
"fee_on_payer": false
}
Response Example
{
"subscription_id": 700000001,
"deposit_id": 300604089,
"user_id": "80000001",
"merchant_invoice_id": "test82347893",
"redirect_url": "https://pay.directa24.com/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI0NjE4ODIwODIiLCJpYXQiOjE2NDg1MjI0NjAsImV4cCI6MTY1MTExNDQ2MH0.t_fRgBbVR7mXTydJu2VMOEe99noc3j34hb5hj34b5j34brj3qO_5C?q=0",
payment_info: {
"type": "CREDIT_CARD",
"result": "PENDING",
"payment_method_supported": ["VI", "MC", "AE"],
"amount": 1000.00,
"currency": "BRL",
"created_at": "2022-03-15 12:24:53",
"expiration_date": "2022-03-15 13:24:53"
},
"subscription_info": {
"payment_period": 0,
"type": "monthly",
"start_date": "2022-03-15 12:24:53",
"end_date": "2023-03-01 00:00:00"
}
}
An async notification will be sent to your
notification_url
to confirm the result of the payment.Notification Example
{
"subscription_id": 700000001,
"deposit_id": 300604089
}
Use the Deposit Status Endpoint to check the status of this deposit, or use the Subscription Status Endpoint to check the status of the Subscription.
Field name | Format | Description |
---|---|---|
subscription_id | Integer | IF of the subscription generated on our ID. Store this ID for future reference |
deposit_id | Integer | ID of the deposit generated on our end. Store this ID for future reference |
user_id | String | ID of the user. If you didn't send it, it is generated by us |
merchant_invoice_id | String | ID of the deposit on your end. If you didn't send it, it is generated by us |
redirect_url | String | URL to redirect the user to our Hosted Checkout. Only shown if you didn't send the credit_card object |
payment_info[] | Object | Object containing the information about the payment |
payment_info.type | String | Type of transaction (Always CREDIT_CARD) |
payment_info.result | String | Status of the transaction: [SUCCESS, REJECTED, PENDING] |
payment_info.reason | String | Transaction result. Only shown in case of rejection |
payment_info.reason_code | String | Code of the result. Only shown in case of rejection |
payment_info.payment_method | String | |
payment_info.payment_method_name | String | |
payment_info.payment_method_supported | Array | An array of the card types supported. Only shown if you didn't send the credit_card object |
payment_info.amount | Number | Amount sent to the card acquirer |
payment_info.currency | String | Currency of the amount sent to the card acquirer |
payment_info.created_at | String | Transaction date time |
payment_info.expiration_date | String | Transaction expiration datetime |
subscription_info[] | Object | Object containing information about the Subscription |
subscription_info.payment_period | Number | Payment period with 0 meaning the initial payment |
subscription_info.type | String | Type of subscription |
subscription_info.start_date | String | Datetime in which the subscription started |
subscription_info.end_date | String | Datetime in which the subscription ends |
Field name | Format | Description |
---|---|---|
code | Number | |
description | String | Description of the error |
details[] | String | Details about the errors. It is shown in case of invalid details |
type | String |
{
"code": 201,
"description": "Field validation error. Check details",
"details": [
"payer.document: Invalid document type and/or document",
"payer.address.state: Invalid State for Country"
]
}
{
"code": 201,
"description": "Field validation error. Check details",
"details": [
"amount: invalid numeric format",
"country: Invalid value. Accepted values: AR|BR|CL|CM|CN|CO|EC|GH|IN|ID|KE|MY|MX|NG|PA|PE|PH|PY|TH|TZ|UG|UY|VN|ZA"
]
}
{
"code": 502,
"description": "Invalid request body",
"type": "INVALID_REQUEST_BODY"
}
{
"code": 304,
"description": "The user limit has been exceeded",
"type": "USER_LIMIT_EXCEEDED"
}
{
"code": 201,
"description": "Field validation error. Check details",
"details": [
"creditCard.cardNumber: size must be between 13 and 20, rejected value is 345678***********1090"
]
}
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 |
REJECTED | EXTERNAL_HIGH_RISK | The card issuer rejected the payment because of their anti-fraud rules |
REJECTED | TRX_NOT_SUPPORTED | Transaction type is not supported for acquirer |
REJECTED | INVALID_CARD_NUMBER | Invalid credit card number |
REJECTED | INVALID_CARD_HOLDER | Invalid card holder |
REJECTED | INVALID_CARD_EXPIRATION | Invalid expiration date |
REJECTED | INVALID_SECURITY_CODE | Invalid CVV/CVV2 |
REJECTED | INVALID_ISSUER | Invalid card issuer |
REJECTED | INVALID_PIN | Invalid card pin |
REJECTED | DUPLICATE_PAYMENT | Payment duplicated |
REJECTED | MAX_ATTEMPTS_REACHED | Max attempts reached for this user and card |
REJECTED | INSUFFICIENT_FUNDS | Insufficient funds |
REJECTED | AUTHORIZATION_CALL_REQUIRED | The transaction was rejected because the user needs to call their bank to activate the card |
REJECTED | CARD_BIN_NOT_FOUND | Credit card bin number not found |
REJECTED | CARD_EXPIRED | Credit card expired |
REJECTED | CARD_DECLINED | Card declined by issuer |
REJECTED | CARD_REPORTED_STOLEN | Card reported as stolen |
REJECTED | CARD_REPORTED_LOST | Card reported as lost |
REJECTED | CARD_RESTRICTED_BY_BANK | The card was blocked by the bank |
REJECTED | CARD_REQUESTED_BY_BANK | The card is requested by the bank |
REJECTED | CARD_BLACKLISTED | Card blacklisted |
REJECTED | CARD_DISABLED | Card disabled |
REJECTED | OTHER_REASON | Generic rejection reason |
Field name | Format | Description | Default | Validations | Required |
---|---|---|---|---|---|
country | string (length: 2) | Country code of the deposit in ISO 3166-1 alpha-2 code format | | Yes | |
amount | decimal (max decimals: 2) | Deposit amount in the currency specified | | Number of up to 18 integers and 2 decimals places | Yes |
currency | string (length: 3) | Currency code of the amount in ISO 4217 format | USD | Yes | |
invoice_id | string (max length: 128) | Unique deposit ID on the merchant end | random string | ^[A-Za-z0-9-_]*$ | Yes |
payer | object[] | | Yes | ||
credit_card | object[] | | Yes | ||
subscription | object[] | | Yes | ||
description | string (max length: 100) | Transaction description. It could be shown on the customers credit card extract | | String of up to 100 characters | No |
client_ip | string | Valid IPv4 or IPv6 Address | | IPv4/v6 Address | Yes |
device_id | 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 |
fee_on_payer | boolean | Choose if the deposit's fee will be paid by the customer or debited from your balance | false | [true, false] | No |
Field name | Format | Description | Required |
---|---|---|---|
start_date | ISO8601 Datetime with Timezone:
yyyy-MM-dd'T'HH:mm:ssZ | Datetime that will start the subscription billing cycle. | Yes |
plan | Value of enum: [ MONTHLY , YEARLY ] | Frequency of collections. It can be MONTHLY or YEARLY | Yes |
plan_unit | integer | Amount of times that the subscription will be charged. | Yes |
auto_renewal | boolean | Used to indicate if the subscription will auto-renovate after a complete billing cycle. | Yes |
Field name | Format | Description | Validations | Required |
cvv | String (max length: 4 digits) | Credit card CVV/CVV2 code | ^\d{3,4}$ size must be between 3 and 4 | Yes |
card_number | String (max length: 16 digits) | The credit card number consisting of up to 16 digits | Yes | |
expiration_month | String(length: 2) | Credit card expiration month | ^(1[0-2]|0[1-9]|[1-9])$ | Yes |
expiration_year | String(length: 2) | Credit card expiration year last two digits | ^\d{2}$ Valid year: 25 | Yes |
holder_name | String (max length: 256) | The name of the credit card owner | Valid name | Yes |
Field name | Format | Description | Default | Validations | Required |
---|---|---|---|---|---|
id | 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 | ^[A-Za-z0-9]*$ | Recommended |
document | 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 | |
document_type | string (max length: 10) | Customer's document type. Optional, if sent must be a valid document type | | Yes | |
email | string (max length: 255) | Valid customer's email address | | Valid email address | Yes |
first_name | string (max length: 128) | Customer's first name | | String of up to 128 characters | Yes |
last_name | string (max length: 128) | Customer's last name | | String of up to 128 characters | Yes |
address | object[] | | No | ||
phone | string (max length: 32) | Valid customer's phone number | | No | |
birth_date | string (max length: 8) | Customer's birthdate in format yyyyMMdd. E.g.: 19801027 | | Numeric format expected: yyyyMMdd | No |
Field name | Format | Description | Validations | Required |
street | string (max length: 255) | Customer's street | String of up to 255 characters | No |
city | string (max length: 128) | Customer's city | String of up to 128 characters | No |
state | string (max length: 3) | No | ||
zip_code | string (max length: 16) | Customer's zip code | No |
Last modified 5mo ago