Comment on page
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.
​
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:
- Synchronic answer confirming the result of the transaction (in case that no 3DS authentication is required), hence no notifications will be sent by default.
- In case of requiring a 3DS Authentication of the payer, then the result of the transaction will be
PENDING_AUTHENTICATIONin order to trigger the corresponding flow. In this case a webhook notification will be sent to check the final status of the Deposit. Please visit Deposits with 3DS Authentication for more details.
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
}
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_info.payment_method_name | String | |
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 |
authentication_url | URL | URL to display to the end-user in order to complete the 3DS Authentication. |
Success
Rejection
Pending Authentication
{
"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"
}
}
​
This response will occur for all deposits that are eligible for a 3DS Authentication.
{
"deposit_id": 300854027,
"merchant_invoice_id": "postmanTest488131304",
"payment_info": {
"type": "CREDIT_CARD",
"result": "PENDING_AUTHENTICATION",
"reason": "Require 3DS Authentication",
"reason_code": "AUTHORIZATION_PENDING",
"payment_method": "VI",
"payment_method_name": "Visa",
"created_at": "2023-10-19 16:57:55",
"authentication_url": "https://checkout.cc-stg.directa24.com/authentication/MM15BgQjHVjGEpQLCYZQ1dBoMOcJuDAc"
}
}
The
authentication_url should be displayed to the end-user in order to proceed with the authentication, and posterior payment processing if successful.
The URL can be opened within an iframe or a redirection into a new tab.For more information about Pending Authentication result, please visit Deposits with 3DS Authentication.
Field name | Format | Description |
code | Number | |
description | String | Description of the error |
details[] | String | Details about the errors. It is shown in case of invalid details |
type | String |
{
"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"
]
}
​
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 |
​
​
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 | 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[] | ​ | Yes | ||
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 |
​
​
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 |
​
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 |
​
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) | No | ||
zip_code | string (max length: 16) | Customer's zip code | No |
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)
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. |
​
Last modified 1mo ago