Subscriptions Endpoint

Payment Methods Document ID Validations Cashout Bank Codes
Search…
Learn how to use the Subscriptions endpoint to create recurring payments with cards
Subscription API Request
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 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.
​
post
https://cc-api-stg.directa24.com
/v3/subscription
Deposit creation
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. A merchant without PCI can still use this API to charge their customers through our hosted payment page.
​
Request Example with Card Details
Request JSON
Response JSON
Subscription API
1
{
2
    "invoice_id": "800000001",
3
    "amount": 1000,
4
    "country": "BR",
5
    "currency": "BRL",
6
    "payer": {
7
        "id": "11111",
8
        "document": "84932568207",
9
        "email": "[email protected]",
10
        "first_name": "John",
11
        "last_name": "Smith",
12
        "address": {
13
            "street": "Calle 13",
14
            "city": "bahia",
15
            "state": "SP",
16
            "zip_code": "12345-678"
17
        }
18
    },
19
    "credit_card": {
20
        "cvv": "123",
21
        "card_number": "4111111111111111",
22
        "expiration_month": "10",
23
        "expiration_year": "25",
24
        "holder_name": "JOHN SMITH"
25
    },
26
    "subscription": {
27
        "backdate_start_date" : "2022-03-01'T'00:00:00Z",
28
        "end_date": "2023-03-01'T'00:00:00Z",
29
        "type": "monthly",
30
        "billing_cycle_date": "01"
31
    },
32
    "description": "Monthly subscription. Pack premium",
33
    "client_ip": "123.123.123.123",
34
    "device_id": "knakvuejffkiebyab",
35
    "fee_on_payer": false
36
}
Copied!
Response Example
1
{
2
    "subscription_id": 700000001,
3
    "deposit_id": 300604089,
4
    "user_id": "80000001",
5
    "merchant_invoice_id": "test82347893",
6
    "payment_info": {
7
        "type": "CREDIT_CARD",
8
        "result": "SUCCESS",
9
        "payment_method": "VI",
10
        "payment_method_name": "Visa",
11
        "amount": 1000.00,
12
        "currency": "BRL",
13
        "created_at": "2022-03-15 12:24:53"
14
    }
15
    "subscription_info": {
16
        "payment_period": 0,
17
        "type": "monthly",
18
        "start_date": "2022-03-15 12:24:53",
19
        "end_date": "2023-03-01 00:00:00"
20
    }
21
}
Copied!
​
Request Example without Card Details
Request JSON
Response JSON
Webhook JSON
Subscription API
1
{
2
    "invoice_id": "800000001",
3
    "amount": 1000,
4
    "country": "BR",
5
    "currency": "BRL",
6
    "payer": {
7
        "id": "11111",
8
        "document": "84932568207",
9
        "email": "[email protected]",
10
        "first_name": "John",
11
        "last_name": "Smith",
12
        "address": {
13
            "street": "Calle 13",
14
            "city": "bahia",
15
            "state": "SP",
16
            "zip_code": "12345-678"
17
        }
18
    },
19
    "subscription": {
20
        "backdate_start_date" : "2022-03-01'T'00:00:00Z",
21
        "end_date": "2023-03-01'T'00:00:00Z",
22
        "type": "monthly",
23
        "billing_cycle_date": "01"
24
    },
25
    "notification_url": "https://webhook.site/token",  "
26
    "description": "Monthly subscription. Pack premium",
27
    "client_ip": "123.123.123.123",
28
    "device_id": "knakvuejffkiebyab",
29
    "fee_on_payer": false
30
}
Copied!
Response Example
1
{
2
    "subscription_id": 700000001,
3
    "deposit_id": 300604089,
4
    "user_id": "80000001",
5
    "merchant_invoice_id": "test82347893",
6
    "redirect_url": "https://pay.directa24.com/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI0NjE4ODIwODIiLCJpYXQiOjE2NDg1MjI0NjAsImV4cCI6MTY1MTExNDQ2MH0.t_fRgBbVR7mXTydJu2VMOEe99noc3j34hb5hj34b5j34brj3qO_5C?q=0",
7
    payment_info: {
8
        "type": "CREDIT_CARD",
9
        "result": "PENDING",
10
        "payment_method_supported": ["VI", "MC", "AE"],
11
        "amount": 1000.00,
12
        "currency": "BRL",
13
        "created_at": "2022-03-15 12:24:53",
14
        "expiration_date": "2022-03-15 13:24:53"        
15
    },
16
    "subscription_info": {
17
        "payment_period": 0,
18
        "type": "monthly",
19
        "start_date": "2022-03-15 12:24:53",
20
        "end_date": "2023-03-01 00:00:00"
21
    }
22
}
Copied!
An async notification will be sent to your notification_url to confirm the result of the payment.
Notification Example
1
{
2
    "subscription_id": 700000001,
3
    "deposit_id": 300604089
4
}
5
​
Copied!
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.
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
​
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
1
{
2
    "code": 201,
3
    "description": "Field validation error. Check details",
4
    "details": [
5
        "payer.document: Invalid document type and/or document",
6
        "payer.address.state: Invalid State for Country"
7
    ]
8
}
9
​
10
{
11
    "code": 201,
12
    "description": "Field validation error. Check details",
13
    "details": [
14
        "amount: invalid numeric format",
15
        "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"
16
    ]
17
}
18
​
19
{
20
    "code": 502,
21
    "description": "Invalid request body",
22
    "type": "INVALID_REQUEST_BODY"
23
}
24
​
25
{
26
    "code": 304,
27
    "description": "The user limit has been exceeded",
28
    "type": "USER_LIMIT_EXCEEDED"
29
}
30
​
31
{
32
    "code": 201,
33
    "description": "Field validation error. Check details",
34
    "details": [
35
        "creditCard.cardNumber: size must be between 13 and 20, rejected value is 345678***********1090"
36
    ]
37
}
Copied!
​
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
​
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
Default value
Required
backdate_start_date
ISO8601 Datetime with Timezone: 
yyyy-MM-dd'T'HH:mm:ssZ
A past datetime to backdate the subscription’s start date to. If sent, the initial payment will contain a proration for the datetime between the start date and the current time with a maximum of 30 days
Current datetime
No
end_date
ISO8601 Datetime with Timezone: 
yyyy-MM-dd'T'HH:mm:ssZ
Date in which the subscription ends
Never
No
type
Value of enum: [monthly, yearly]
Type of subscription. It can be monthly or yearly
​
Yes
billing_cycle_date
Numeric [0-31]. With 0 meaning last day of the month
Day of the month in which the payment will be charged to the customer's card.
​
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
​
​
​