Create deposit (credit card operations)

This deposit creation endpoint is used only for

• Credit and debit cards deposits with the following integrations:

  • ✔️ Server2Server

  • ✔️ Fragments Lite

Create a deposit (credit card operations only)

post

Allow merchants to create credit card operations by sending credit card details, card token or card identifier.

Header parameters

Content-TypestringRequired

Media type of the body sent to the API.

Default: application/json

X-Datestring · date-timeRequired

ISO8601 Datetime with Timezone (yyyy-MM-dd'T'HH:mm:ssZ).

X-LoginstringRequired

Merchant X-Login API Key.

AuthorizationstringRequired

Authorization control hash.

X-Idempotency-KeystringOptional

Unique idempotency key for ensuring that the same request is not processed more than once.

Body

application/json

Details for creating a PCI deposit.

countrystring · min: 2 · max: 2Required

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

Example: BR

amountnumber · doubleRequired

Deposit amount in the currency specified. Up to 18 integers and 2 decimal places.

Example: 1000

currencystring · min: 3 · max: 3Required

Currency code of the amount in ISO 4217 format.

Example: BRL

installmentsinteger · int32 · min: 1 · max: 12Optional

Number of installments in which the deposit will take place. *Check eligibility with your commercial contact.

Example: 1

invoice_idstring · max: 128Required

Unique deposit ID on the merchant end.

Example: 800000001Pattern: ^[A-Za-z0-9-_]*$

external_subscription_idstring · max: 128Optional

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.

card_tokenstring · max: 50Optional

Card Token generated with Cards SDK Without User Interface. Typically used if credit_card object is not provided.

card_identifierstring · max: 50Optional

Card Identifier generated with Cards-on-file API. Typically used if credit_card object is not provided.

sub_merchant_idinteger · int64Optional

Used to specify for which SubMerchant ID the deposit will be created.

descriptionstring · max: 100Optional

Transaction description. It could be shown on the customer's credit card extract.

Example: Test transaction

client_ipstringRequired

Valid IPv4 or IPv6 Address of the customer.

Example: 123.123.123.123

device_idstring · max: 100Optional

Unique customer's device ID. Used to identify and prevent fraud.

Example: knakvuejffkiebyab

fee_on_payerbooleanOptional

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

Default: falseExample: false

Responses

200

Successful operation. The transaction outcome is indicated by the payment_info.result field. Refer to the PaymentInfo schema, specifically the result field description, for detailed explanations of possible transaction statuses and their implications (e.g., SUCCESS, REJECTED, PENDING_AUTHENTICATION).

application/json

Response structure for a PCI deposit creation request.

deposit_idinteger · int64Required

ID of the deposit generated on our end. Store this ID for future reference.

Example: 300604089

user_idstringOptional

ID of the user. If you didn't send it, it is generated by us.

Example: 80000001

merchant_invoice_idstringRequired

ID of the deposit on your end. If you didn't send it, it is generated by us.

Example: test766106146

authentication_urlstring · url · nullableOptional

URL to display to the end-user to complete 3DS Authentication. Present if 3DS authentication is required (e.g., when payment_info.result is PENDING_AUTHENTICATION).

Example: https://checkout.cc-stg.onekeypayments.com/authentication/MM15BgQjHVjGEpQLCYZQ1dBoMOcJuDAc

400

Bad Request - Field validation error or invalid request structure.

application/json

post

/v3/deposits

HTTPcURLJavaScriptPython

POST /v3/deposits HTTP/1.1
Host: cc-api-stg.onekeypayments.com
X-Date: 2026-03-03T03:43:53.314Z
X-Login: text
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 598

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

{
  "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-05T22:10:45Z"
  }
}

Error codes

For more information regarding error codes, please visit API Codes page