PCI Deposit Creation Endpoint
Learn how to use the PCI Deposit endpoint to create One Shot payments with credit cards
post
https://cc-api-stg.directa24.com
/v3/deposits
Deposit creation
The usage of this endpoint is restricted to PCI Compliant merchants who have shared their PCI AOC certificate with their Account Manager.

V3 PCI Request

A request made through the PCI Deposit Creation endpoint works almost in the same way than the non-PCI Deposits endpoint does, with the difference being on the credit_card object you need to send.
The transactions created using the V3 PCI endpoint will receive a synchronic answer confirming the result of the transaction, hence no notifications will be sent by default.

Request Example

JSON
1
{
2
"invoice_id": "800000001",
3
"amount": 1000,
4
"country": "BR",
5
"currency": "BRL",
6
"payer": {
7
"id": "11111",
8
"document": "84932568207",
9
"document_type": "CPF",
10
"email": "[email protected]",
11
"first_name": "John",
12
"last_name": "Smith",
13
"phone": "+233852662222",
14
"birth_date": "19880910",
15
"address": {
16
"street": "Calle 13",
17
"city": "bahia",
18
"state": "SP",
19
"zip_code": "12345-678"
20
}
21
},
22
"credit_card": {
23
"cvv": "123",
24
"card_number": "4111111111111111",
25
"expiration_month": "10",
26
"expiration_year": "25",
27
"holder_name": "JOHN SMITH"
28
},
29
"description": "Test transaction",
30
"client_ip": "123.123.123.123",
31
"device_id": "knakvuejffkiebyab",
32
"fee_on_payer": false
33
}
Copied!

Response Example: Success/rejection

Response Fields

Field name
Format
Description
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
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 or REJECTED
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.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

Response Example

Success
Rejection
1
{
2
"deposit_id": 300604089,
3
"user_id": "80000001",
4
"merchant_invoice_id": "test766106146",
5
"payment_info": {
6
"type": "CREDIT_CARD",
7
"result": "SUCCESS",
8
"payment_method": "AE",
9
"payment_method_name": "American Express",
10
"amount": 505.95,
11
"currency": "MXN",
12
"created_at": "2021-02-05 22:10:45"
13
}
14
}
15
Copied!
1
{
2
"deposit_id": 300604089,
3
"user_id": "80000001",
4
"merchant_invoice_id": "test766106146",
5
"payment_info": {
6
"type": "CREDIT_CARD",
7
"result": "REJECTED",
8
"reason": "Insufficient funds",
9
"reason_code": "INSUFFICIENT_FUNDS",
10
"payment_method": "AE",
11
"payment_method_name": "American Express",
12
"amount": 505.95,
13
"currency": "MXN",
14
"created_at": "2021-02-05 22:10:45"
15
}
16
}
17
Copied!

Response Example: Error

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 Example

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
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
^[A-Za-z0-9-_]*$
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

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