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
{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "document_type": "CPF",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Smith",
        "phone": "+233852662222",
        "birth_date": "19880910",
        "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"
    },
    "description": "Test transaction",
    "client_ip": "123.123.123.123",
    "device_id": "knakvuejffkiebyab",
    "fee_on_payer": false
}
​
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
{
    "deposit_id": 300604089,
    "user_id": "80000001",
    "merchant_invoice_id": "test766106146",
    "payment_info": {
        "type": "CREDIT_CARD",
        "result": "SUCCESS",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}
​
{
    "deposit_id": 300604089,
    "user_id": "80000001",
    "merchant_invoice_id": "test766106146",
    "payment_info": {
        "type": "CREDIT_CARD",
        "result": "REJECTED",
        "reason": "Insufficient funds",
        "reason_code": "INSUFFICIENT_FUNDS",
        "payment_method": "AE",
        "payment_method_name": "American Express",
        "amount": 505.95,
        "currency": "MXN",
        "created_at": "2021-02-05 22:10:45"
    }
}
​
​
​
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
{
    "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
installments
integer (max length: 2)
Number of installments in which the deposit will take place.
*Check eligibility with your commercial contact.
​
Integer number between 1 and 12.
No
invoice_id
string (max length: 128)
Unique deposit ID on the merchant end
random
^[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
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. 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
​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
Card Numbers for Testing
In the following table you will find card numbers from specific brands to test different payment flows and our systems' responses.
For all Results:
Expiration date has to be in the future (expiration_month + expiration_year)
cvv: any three numeric digits.
holder_name : any name.
For Success Results in STG: any card number not listed below, will simulate a success scenario.
(For example, Card Number: 4111111111111111)
Visa
 Card Number
 Result
4222222222222220
Card Rejected.
4000000000000060
Card Expired.
4444444444444440
Insufficient funds.
4000000000000110
Card reported as stolen.
4000000000000040
The card issuer rejected the payment because of their anti-fraud rules.
Mastercard
Card Number
Result
5454545454545450
Card Rejected.
5555555555554440
Card Expired. 
5105105105105100
Insufficient funds. 
5451951574925480
Card reported as stolen.
5406251139676600
The card issuer rejected the payment because of their anti-fraud rules. 
American Express
Card Number
Result
340000000000009
Card Rejected.
373737373737374
Card Expired. 
370000000000002
Insufficient funds. 
343434343434343
Card reported as stolen. 
341111111111111
The card issuer rejected the payment because of their anti-fraud rules. 
JCB
Card Number
Result
3530185156387080
Card Rejected. 
3566002020360500
Card Expired. 
3555555555555552
Insufficient funds.
3539189698635270
Card reported as stolen. 
3588430314874690
The card issuer rejected the payment because of their anti-fraud rules. 
​

Notifications

Subscriptions Endpoint

Last modified 2mo 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

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

Card Number	Result
4222222222222220	Card Rejected.
4000000000000060	Card Expired.
4444444444444440	Insufficient funds.
4000000000000110	Card reported as stolen.
4000000000000040	The card issuer rejected the payment because of their anti-fraud rules.

Card Number	Result
5454545454545450	Card Rejected.
5555555555554440	Card Expired.
5105105105105100	Insufficient funds.
5451951574925480	Card reported as stolen.
5406251139676600	The card issuer rejected the payment because of their anti-fraud rules.

Card Number	Result
340000000000009	Card Rejected.
373737373737374	Card Expired.
370000000000002	Insufficient funds.
343434343434343	Card reported as stolen.
341111111111111	The card issuer rejected the payment because of their anti-fraud rules.

Card Number	Result
3530185156387080	Card Rejected.
3566002020360500	Card Expired.
3555555555555552	Insufficient funds.
3539189698635270	Card reported as stolen.
3588430314874690	The card issuer rejected the payment because of their anti-fraud rules.

PCI Deposit Creation Endpoint

V3 PCI Request

Request Example

​

Response Example: Success/rejection

Response Fields

​

Response Example

Response Example: Error

Response Fields

​

Response Example

Status reasons

Request Fields Description

Request Objects

Credit Card Object

Payer Object

Payer.address Object

Card Numbers for Testing

Visa

Mastercard

American Express

JCB