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
​
​Country codes​
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[]
​Object containing details about the payer​
​
​Payer object​
Yes
credit_card
object[]
​Object containing the credit card details​
​
​Credit card object​
Yes
subscription
object[]
​Object containing the subscription details​
​
​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
​Luhn Algorithm​
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
​
​document validations​
Yes
document_type
string (max length: 10)
Customer's document type. Optional, if sent must be a valid document type
​
​document types validations​
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[]
​Object containing customer's address details​
​
​address object​
No
phone
string (max length: 32)
Valid customer's phone number
​
​phone number validations​
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
​zip_code validations​
No
​
​
​

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

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

Field name	Format	Description	Default	Validations	Required
`country`	string (length: 2)	Country code of the deposit in ISO 3166-1 alpha-2 code format		Country codes	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[]	Object containing details about the payer		Payer object	Yes
`credit_card`	object[]	Object containing the credit card details		Credit card object	Yes
`subscription`	object[]	Object containing the subscription details		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	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		document validations	Yes
`document_type`	string (max length: 10)	Customer's document type. Optional, if sent must be a valid document type		document types validations	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[]	Object containing customer's address details		address object	No
`phone`	string (max length: 32)	Valid customer's phone number		phone number validations	No
`birth_date`	string (max length: 8)	Customer's birthdate in format yyyyMMdd. E.g.: 19801027		Numeric format expected: `yyyyMMdd`	No

PCI Deposit Creation Endpoint

Deposit Status Endpoint

Last modified 5mo ago

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

Subscriptions Endpoint

Subscription API Requests

PCI Compliant Subscriptions Endpoint

Request Example with Card Details

Redirect Subscriptions Endpoint

Request Example without Card Details

Response Fields Details

Response Fields

​

Error Response Fields Details

Response Fields

Response Examples

Status reasons

Request Fields Description

Request Objects

Subscription Object

Credit Card Object

Payer Object

Payer.address Object

​