PCI Deposit Creation Endpoint

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

Deposit creation

POST https://cc-api-stg.directa24.com/v3/deposits

This endpoint allows you to generate credit cards transactions by sending the Credit Card details.

Headers

Name	Type	Description
Content-Type	string	application/json
X-Date	string	ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login	string	Merchant X-Login API Key
Authorization	string	Authorization control hash
X-Idempotency-Key	string	Unique idempotency key

Request Body

Name	Type	Description
country*	string	Country of the transaction
amount*	number	Amount of the transaction
currency*	string	Currency of the amount specified
invoice_id*	string	Unique deposit ID on the merchant end
payer*	object	Object containing details about the customer. See "Payer object" section for details
credit_card	object	Object containing the credit card details
card_token	string	Card Token obtained from our Cards SDK
description	string	Descriptor for the transaction
client_ip*	string	Valid IPv4/v6 Address of the customer
device_id	string	Unique customer's device ID created using our JS library
fee_on_payer	boolean	Used to specify if you want to let the customer assume the deposit fee

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

• 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_AUTHENTICATION in 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.

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": "[phone]",
        "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 / Pending Authentication

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
authentication_url	URL	URL to display to the end-user in order to complete the 3DS Authentication.

Response Example

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

Pending Authentication

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.

Pending Provider Authentication

This response will occur for deposits which are pending 3DS authentication from the provider.

    "deposit_id": 300854027,
    "merchant_invoice_id": "postmanTest488131304", 
    "payment_info": { 
        "type": "CREDIT_CARD", 
        "result": "IN_PROGRESS", 
        "reason": "Payment in progress, awaiting the acquirer's response.", 
        "reason_code": "PENDING_ACK", 
        "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 a redirection into a new tab.

For more information about Pending Authentication results, please visit Deposits with 3DS Authentication.

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
external_subscription_id	string (max length: 128)	ID of the generated subscription on your end, that will be charged to the card_identifier.			This field is mandatory when creating a subscription with card_identifier.
payer	object[]	Object containing details about the payer		Payer object	Yes
credit_card	object[]	Object containing the credit card details		Credit card object	No
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
card_token	string (max length: 50)	Card Token generated with Cards SDK Without User Interface.		String of up to 50 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
sub_merchant_id	integer	Used to specify for which SubMerchant ID the deposit will be created.

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.