PCI Deposit Creation Endpoint

Learn how to use the PCI Deposit endpoint to create One Shot payments with credit cards

post
Deposit creation

https://cc-api.directa24.com/v3/deposits
STG: https://cc-api-stg.directa24.com/v3/deposits This endpoint allows you to generate credit cards transactions by sending the Credit Card details.
Request
Response
Request
Headers
Content-Type
required
string
application/json
X-Date
required
string
ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login
required
string
Merchant X-Login API Key
Authorization
required
string
Authorization control hash
X-Idempotency-Key
optional
string
Unique idempotency key
Body Parameters
country
required
string
Country of the transaction
amount
required
number
Amount of the transaction
currency
optional
string
Currency of the amount specified
invoice_id
optional
string
Unique deposit ID on the merchant end
payer
required
object
Object containing details about the customer. See "Payer object" section for details
credit_card
required
object
Object containing the credit card details
description
optional
string
Descriptor for the transaction
client_ip
required
string
Valid IPv4/v6 Address of the customer
device_id
optional
string
Unique customer's device ID created using our JS library
fee_on_payer
optional
boolean
Used to specify if you want to let the customer assume the deposit fee
Response
200: OK
Transaction successfully processed
{
"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"
}
}
400: Bad Request
Transaction failed due to field validation error
{
"code": 201,
"description": "Field validation error. Check details",
"details": [
"creditCard.cardNumber: size must be between 13 and 20, rejected value is 345678***********1090"
],
"type": "BEAN_VALIDATION_ERROR"
}

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
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
Success
{
"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"
}
}
Rejection
{
"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

country

string (length: 2)

Country code of the deposit in ISO 3166-1 alpha-2 code format

Country codes

amount

decimal (max decimals: 2)

Deposit amount in the currency specified

Number of up to 18 integers and 2 decimals places

currency

string (length: 3)

Currency code of the amount in ISO 4217 format

USD

See Currencies

invoice_id

string (max length: 128)

Unique deposit ID on the merchant end

random

^[A-Za-z0-9-_]*$

payer

object[]

Object containing details about the payer

Payer object

credit_card

object[]

Object containing the credit card details

Credit card object

fee_on_payer

boolean

Choose if the deposit's fee will be paid by the customer or debited from your balance

false

[true, false]

description

string (max length: 100)

Transaction description. It could be shown on the customers credit card extract

String of up to 100 characters

client_ip

string

Valid IPv4 or IPv6 Address

IPv4/v6 Address

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

Request Objects

Credit Card Object

Field name

Format

Description

Validations

cvv

String (max length: 4 digits)

Credit card CVV/CVV2 code

^\d{3,4}$

size must be between 3 and 4

card_number

String (max length: 16 digits)

The credit card number consisting of up to 16 digits

Luhn Algorithm

expiration_month

String(length: 2)

Credit card expiration month

^(1[0-2]|0[1-9]|[1-9])$

expiration_year

String(length: 2)

Credit card expiration year last two digits

^\d{2}$

Valid year: 25

holder_name

String (max length: 256)

The name of the credit card owner

Valid name

Payer Object

Field name

Format

Description

Default

Validations

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]*$

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

document_type

string (max length: 10)

Customer's document type. Optional, if sent must be a valid document type

document types validations

email

string (max length: 255)

Valid customer's email address

Valid email address

first_name

string (max length: 128)

Customer's first name

String of up to 128 characters

last_name

string (max length: 128)

Customer's last_name

String of up to 128 characters

address

object[]

Object containing customer's address details

address object

phone

string (max length: 32)

Valid customer's phone number

phone number validations

birth_date

string (max length: 8)

Customer's birthdate in format yyyyMMdd. E.g.: 19801027

Numeric format expected: yyyyMMdd

Payer.address Object

Field name

Format

Description

Validations

street

string (max length: 255)

Customer's street

String of up to 255 characters

city

string (max length: 128)

Customer's city

String of up to 128 characters

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

zip_code

string (max length: 16)

Customer's zip code

zip_code validations