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.onekeypayments.com/v3/deposits

Deposit creation

POST https://cc-api-stg.onekeypayments.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

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

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

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

Headers

Name

Type

Description

Content-Type

string

nNrM42ejXSqA

X-Date

string

JlPl4srSQ0iV

X-Login

string

KR4b6wf45Pzd

Authorization

string

P06sWVWt55jZ

X-Idempotency-Key

string

hmnq9J1vyo9N

Request Body

Name

Type

Description

country*

string

be9OL4uQbc6N

amount*

number

sAuQeP54Gk0U

currency*

string

6MHwBq7x6R90

invoice_id*

string

0XHzVRvrw9CG

payer*

object

NloFHb9RB0sO

credit_card

object

grMJuJV7Sn3Z

card_token

string

Card Token obtained from our Cards SDK

description

string

pQehONcGWw0C

client_ip*

string

Nex4vugUCVti

device_id

string

rDSU7VQB8zeD

fee_on_payer

boolean

EwC5yxsSO5bQ

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

{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "document_type": "CPF",
        "email": "johnSmith12@hotmail.com",
        "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

payment_info.payment_method_name

String

Payment method name. See the

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

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

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

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

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

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.

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

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

card_token

string (max length: 50)

Card Token generated with .

String of up to 50 characters

fee_on_payer

boolean

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

false

[true, false]

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

address

object[]

phone

string (max length: 32)

Valid customer's phone number

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

Required

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

Valid state code in format. Check our

zip_code

string (max length: 16)

Customer's zip code

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.

PreviousUnderstanding the Solution NextDeposit Status Endpoint

Last updated 6 months ago