Links

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.
post
https://cc-api-stg.directa24.com
/v3/subscriptions
Subscription creation

Request Example with Card Details

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"
}
}

Redirect Subscriptions Endpoint

post
https://api-stg.directa24.com
/v3/subscriptions
Subscription creation

Request Example without Card Details

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.
User Journey after redirection
Users will see our hosted payment page where they will be capable of filling in their card details to create the subscription.

Response Fields Details

Response Fields

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 method code. See the list here.
payment_info.payment_method_name
String
Payment method name. See the list here.
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

Error Response Fields Details

Response Fields

Field name
Format
Description
code
Number
Error code. See the list of error codes
description
String
Description of the error
details[]
String
Details about the errors. It is shown in case of invalid details
type
String
Error code name. It is not always shown. See the list of error codes

Response Examples

{
"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"
]
}

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
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

Request Fields Description

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
See Currencies
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

Request Objects

Subscription Object

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

Credit Card Object

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

Payer Object

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

Payer.address Object

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)
Customer's state code in ISO 3166-2 code format
Valid state code in ISO 3166-2 format. Check our States endpoint here
No
zip_code
string (max length: 16)
Customer's zip code
No