Deposit Creation Endpoint

Learn how to generate deposits

Deposit creation

POST https://api-stg.onekeypayments.com/v3/deposits

This endpoint allows you to generate deposit transactions.

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 deposit

amount

number

Amount of the deposit

invoice_id

string

Unique deposit ID on your side

currency

string

Currency of the deposit

request_payer_data_on_validation_failure

boolean

Flag specifying if you want to ignore errors because of invalid phone, zip_code and/or city's state

payer

object

Object containing details about the customer. See "Payer object" section for details

payment_method

string

Payment method code

payment_types

array

Array of payment methods' types to show the customer on our Hosted Checkout

bank_accounts

object

Object containing details about the customer's bank account. Used to enforce a close-loop policy

bonus_amount

number

Used to show the customer a bonus amount (Pay 100, receive 120)

bonus_relative

boolean

Used to define if the bonus_amount was specified as an absolute value or as a percentage

strikethrough_price

number

Used to show the customer a strikethrough amount

description

string

Description of the deposit

client_ip

string

Valid IPv4/v6 Address of the customer

device_id

string

Unique customer's device ID created using our JS library

language

string

Language of the view page

back_url

string

HTTPS URL used to redirect the customer in case of cancelling the deposit

success_url

string

HTTPS URL used to redirect the customer in case of success

error_url

string

HTTPS URL used to redirect the customer in case of error while generating the payment

notification_url

string

HTTPS URL used to send the notifications about deposit's change of status

logo

string

HTTPS URL used as the Merchant logo on our cashier

test

boolean

Used to mark a deposit as test. If true, the deposit will not affect the merchant's balance

mobile

boolean

Used to specify if the redirection will be made on a mobile device

early_release

boolean

Used to specify if the deposit should be released earlier

fee_on_payer

boolean

Used to specify if you want to let the customer assume the deposit fee

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout-stg.directa24.com/v1/gateway/show?id_payment=56578849&signature=fff0e0a6a98066c19caf",
    "deposit_id": 300000025,
    "user_id": "11",
    "merchant_invoice_id": "postmanTest943044826",
    "payment_info": {
        "type": "BANK_DEPOSIT",
        "payment_method": "BB",
        "payment_method_name": "Banco do Brasil",
        "amount": 49.99,
        "currency": "BRL",
        "expiration_date": "2020-06-17 07:04:16",
        "created_at": "2020-06-16 19:04:16",
        "metadata": {
            "beneficiary_name": "Directa24 LLP",
            "agency": "3229-X",
            "CNPJ": "33.444.368/0001-39",
            "account": "253393-4"
        }
    }

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "invoiceId: must match \"^[A-Za-z0-9]*$\""
    ]
}

Experiences

When generating a deposit request there are 2 possibilities, either the deposit is created in One Shot and you can display the user directly with the payment information, or you redirect the user to our Hosted Checkout to complete the missing details.

In any of those cases, a field called checkout_type will be part of the response, containing which one of the flows it is:

Checkout_type

Description

ONE_SHOT

The deposit request was successfully completed in One Shot and the user will be directly presented with the information to complete the payment.

HOSTED

The information sent is missing details required to complete the request. Redirect the customer to our Hosted Checkout to collect those details.

This flow works as a fallback method, so that in cases which by mistake a piece of information was missing or additional information is required in order to create a Deposit, we can collect it and avoid a failure in the deposit creation.

Test all the API features with our Postman collection here.

OneShot Experience

On this Experience, you will send all the information required to complete the deposit request and we will respond you with the payment metadata for you to build the Checkout or with an external link for the user to see the payment information.

In case you didn't send one field that is required, we won't decline the request and instead we will prompt the customer for it .

OneShot Request example

Each Country and Payment Method has a minimum set of fields you need to send for the OneShot Experience. In case of looking to develop this Experience on your Cashier visit the Payment Methods page to learn more about those requirements.

{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "juanCarlos@hotmail.com",
        "phone": "+23385266942",
        "address": {
            "street": "Rua 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "payment_method": "BL",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.onekeypayments.com/deposit_cancelled",
    "success_url": "https://www.onekeypayments.com/deposit_completed",
    "error_url": "https://www.onekeypayments.com/deposit_error",
    "notification_url": "https://www.onekeypayments.com/okp/notify",
    "logo": "https://www.onekeypayments.com/onekeypayments.png",
    "test": true,
    "mobile": false,
    "language": "pt"
}

curl --location --request POST 'https://api-stg.onekeypayments.com/v3/deposits' \
--header 'X-Login: xxxxxxx' \
--header 'X-Date: 2020-06-09T19:42:51Z' \
--header 'Authorization: D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "phone": "+23385266942",
        "email": "juanCarlos@hotmail.com",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "payment_method": "BL",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.onekeypayments.com/deposit_cancelled",
    "success_url": "https://www.onekeypayments.com/deposit_completed",
    "error_url": "https://www.onekeypayments.com/deposit_error",
    "notification_url": "https://www.onekeypayments.com/okp/notify",
    "logo": "https://www.onekeypayments.com/okp.png",
    "test": true,
    "mobile": false,
    "language": "pt"
}'

import java.io.*;
import okhttp3.*;
public class main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n       \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"juanCarlos@hotmail.com\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.onekeypayments.com/deposit_cancelled\",\n    \"success_url\": \"https://www.onekeypayments.com/deposit_completed\",\n    \"error_url\": \"https://www.onekeypayments.com/deposit_error\",\n    \"notification_url\": \"https://www.onekeypayments.com/okp/notify\",\n    \"logo\": \"https://www.onekeypayments.com/okp.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}");
    Request request = new Request.Builder()
      .url("https://api-stg.onekeypayments.com/v3/deposits")
      .method("POST", body)
      .addHeader("X-Login", "xxxxxxx")
      .addHeader("X-Date", "2020-06-09T19:42:51Z")
      .addHeader("Authorization", "D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-stg.onekeypayments.com/v3/deposits');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "phone": "+23385266942",
        "email": "juanCarlos@hotmail.com",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "payment_method": "BL",
    "description": "test description",
    "client_ip": "123.123.123.123",
    "device_id": "00000000-00000000-01234567-89ABCDEF",
    "back_url": "https://www.d24.com/deposit_cancelled",
    "success_url": "https://www.d24.com/deposit_completed",
    "error_url": "https://www.d24.com/deposit_error",
    "notification_url": "https://www.d24.com/d24/notify",
    "logo": "https://www.d24.com/d24.png",
    "test": true,
    "mobile": false,
    "language": "pt"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'X-Login' => 'xxxxxxxx',
  'X-Date' => '2020-06-09T19:42:51Z',
  'Authorization' => 'D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

using System;
using RestSharp;
namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.onekeypayments.com/v3/deposits");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("X-Login", "xxxxxxx");
            request.AddHeader("X-Date", "2020-06-09T19:42:51Z");
            request.AddHeader("Authorization", "D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n        \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"juanCarlos@hotmail.com\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.d24.com/deposit_cancelled\",\n    \"success_url\": \"https://www.d24.com/deposit_completed\",\n    \"error_url\": \"https://www.d24.com/deposit_error\",\n    \"notification_url\": \"https://www.d24.com/d24/notify\",\n    \"logo\": \"https://www.d24.com/d24.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}

import requests

url = "https://api-stg.onekeypayments.com/v3/deposits"

payload = "{\n    \"invoice_id\" : \"1000000001\",\n    \"amount\": \"1000\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payer\": {\n        \"id\": \"11\",\n        \"document\": \"84932568207\",\n        \"first_name\": \"Ricardo\",\n        \"last_name\": \"Carlos\",\n        \"phone\": \"+23385266942\",\n        \"email\": \"juanCarlos@hotmail.com\",\n        \"address\": {\n            \"street\": \"Calle 13\",\n            \"city\": \"bahia\",\n            \"state\": \"SP\",\n            \"zip_code\": \"12345-678\"\n        }\n    },\n    \"payment_method\": \"BL\",\n    \"description\": \"test description\",\n    \"client_ip\": \"123.123.123.123\",\n    \"device_id\": \"00000000-00000000-01234567-89ABCDEF\",\n    \"back_url\": \"https://www.onekeypayments.com/deposit_cancelled\",\n    \"success_url\": \"https://www.onekeypayments.com/deposit_completed\",\n    \"error_url\": \"https://www.onekeypayments.com/deposit_error\",\n    \"notification_url\": \"https://www.onekeypayments.com/okp/notify\",\n    \"logo\": \"https://www.onekeypayments.com/okp.png\",\n    \"test\": true,\n    \"mobile\": false,\n    \"language\": \"pt\"\n}"
headers = {
  'X-Login': 'xxxxxxx',
  'X-Date': '2020-06-09T19:42:51Z',
  'Authorization': 'D24 a491ad04b303b6a5b9f219a14eeb496ea8ca086d4644889faa4309bea1feae38',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

OneShot Experience Response: OneShot

In case you sent all the details required for a payment method and the method supports it, we will return you all the metadata required for you to build the checkout on your own website avoiding the redirection.

Success Response fields

The fields returned in this integration are the same than the REDIRECT one. The difference lies in the new metadata and secondary_metadata objects containing the information you need to build your own checkout for each payment method:

Field name

Format

Description

metadata

object

Object containing the metadata of the payment

metadata.beneficiary_name

string

Name of the account beneficiary

metadata.agency

string

Agency of the beneficiary

metadata.CNPJ

string

CNPJ of the beneficiary

metadata.account

string

Account of the beneficiary

metadata.bar_code

string

Voucher bar code token

metadata.digitable_line

string

Voucher identifier line

metadata.payer_document

string

Document number of the payer

metadata.payer_document_type

string

Type of the payer's document sent

metadata.reference

string

Reference your customer needs to pay

secondary_metadata

object

Object containing the secondary metadata of the payment

secondary_metadata.reference

string

Reference of the deposit

secondary_metadata.qr_code

string

PNG image encoded in base64 of the QR code used to display the Pix QR natively on your site

secondary_metadata.digitable_line

string

Plain text string line the user can use to manually pay for the PIX instead of scanning the QR

Please note that the metadata and the secondary_metadataobjects will respond with different values depending upon the payment method and the provider we use, the ones above are only examples. It is for that reason that you should be able to iterate through them to display the values on your cashier to your customers.

Success Response example

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment-stg.onekeypayments.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjYwODA5NSIsImlhdCI6MTYyMTUzOTYzNCwiZXhwIjoxNjIyODM1NjM0LCJsYW5ndWFnZSI6InB0In0.dDo0kMPEhZRSSeDPiH8Km0EXD1zEd1kg0gFdyhOvQ5iBfPl9skD2NYuD2_b-spE2",
    "iframe": true,
    "deposit_id": 300642187,
    "user_id": "kj2n3432n4k23",
    "merchant_invoice_id": "postmanTest433710480",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "IX",
        "payment_method_name": "Pix",
        "amount": 11.65,
        "currency": "BRL",
        "expiration_date": "2021-05-20 22:47:33",
        "created_at": "2021-05-20 19:40:32",
        "metadata": {
            "reference": 56608095,
            "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACMUlEQVR4Xt3UMZKsIBAGYEjkCkOCV1sTuQIkioleQRK4miRyhSahH6Uzr2qRucASflXa0Pw0wd8LyJ8CIEKwUwentKFNSGi3tLlu3haf2rB4mHqjlAw7/wI2Rsc9HvIreKeoefFz/gZozWC9Rev/7+M3AOH2vT5nqQAxMyD9TtF++lEBUMOSIZ0gapRNSOeQGYZohui+AV9fMwjphLq3XgOuetmyXHaJRjcBRtEJac+Rm942IW0Jo5tGnuW77AOMGLJMIVMzXT99AIZDdUInM2fShpQp/NC4uaG0uwlZSfRYKsu4XmWfwFYdfHTzTtT10wckGF9TJ0HJ8122BhjsVgLjSlz80oaXUorazI9J3DdXQzI0hJKEg+7vKjVgSE6R3hpp4Qske+rFrtOPttfxH5BsCuvst/1Hw132ASVTYiQMLdDUBOgz3UI49Bbyffwa0kpI+UT0dqV32RowphDdi3nM9/EfUK4y4WYk8O0O3RPW+RyFtscM7wTVkBXzaZ8YmmG5yj4A95F0E7U263zvowbQPqZVsQhjx5uQ1ZCnjsJwknFuAhpmSxzwLB26y9ZQHnqnSKcYzD62YXr1B3caBLsHyhNYeX8h2kPC9I52BdCbrowtloeD+iaUMcM39Isv2brKPqCMLScm7oHbe/Q9IKEbbPJliCYY2rDYQ0jDYgB6PY8WlAbJoz+0+XzygKU0aSzZxWvrT8BdSY/p4NHd+agByEsMRskYYrqfaQ2/19+GfwmGnDkcom5PAAAAAElFTkSuQmCC",
            "digitable_line": "00020126850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/ab4d2855-ee85-401a-a16d-716c743aa3af5204000053039865802BR5909AP Brasil6003Pix62070503***6304428B"
        }
    }
}

// Metadata explanation
//
// reference: ID of the deposit on our end.
//
// qr_code: PNG image encoded in base64. You can use the following HTML tag 
//          to render the QR code on your website: 
// <img src='qr_code'/>
//
// digitable_line: Plain text string line the user can use to manually pay for the PIX 
//                 instead of scanning the QR
//
// Make sure the user can't see the QR code after the expiration_date was reached

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout.onekeypayments.com/v1/gateway/show?id_payment=172969591&signature=514ff34c08c7c19e8f7d",
    "deposit_id": 30000000001,
    "user_id": "121",
    "merchant_invoice_id": "postmanTest800032729",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "BL",
        "payment_method_name": "Boleto",
        "amount": 165.64,
        "currency": "BRL",
        "expiration_date": "2020-07-20 22:42:41",
        "created_at": "2020-07-13 22:42:41",
        "metadata": {
            "receipt_url": "https://checkout.astropay.com//v1/gateway/getFullFile?id_payment=172969591&signature=514ff34c08c7c19e8f7d",
            "bar_code": "iVBORw0KGgoAAAANSUhEUgAAAioAAABkAQMAAACSM4nFAAAABlBMVEX///8AAABVwtN+AAAAAXRSTlMAQObYZgAAAGpJREFUWIXtzLEJxEAMRcEFpwK1IthUoNYXfgFuRaDUYF8Pl75solnjut3tKdmcidczs1uj3vcVP45kaVkZ8dhYumcpTsvNyvfqrn0WDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ3Nf80HB11x3a9nZU8AAAAASUVORK5CYII=",
            "digitable_line": "00190.00009 03141.056030 01870.806179 8 83180000016564"
        }
    }
}

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout-stg.onekeypayments.com/v1/gateway/show?id_payment=56578849&signature=fff0e0a6a98066c19caf",
    "deposit_id": 300000025,
    "user_id": "11",
    "merchant_invoice_id": "postmanTest943044826",
    "payment_info": {
        "type": "BANK_DEPOSIT",
        "payment_method": "BB",
        "payment_method_name": "Banco do Brasil",
        "amount": 49.99,
        "currency": "BRL",
        "expiration_date": "2020-06-17 07:04:16",
        "created_at": "2020-06-16 19:04:16",
        "metadata": {
            "beneficiary_name": "Directa24 LLP",
            "agency": "3229-X",
            "CNPJ": "33.444.368/0001-39",
            "account": "253393-4"
        },
        "secondary_metadata": {
            "reference": 56608095,
            "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACMUlEQVR4Xt3UMZKsIBAGYEjkCkOCV1sTuQIkioleQRK4miRyhSahH6Uzr2qRucASflXa0Pw0wd8LyJ8CIEKwUwentKFNSGi3tLlu3haf2rB4mHqjlAw7/wI2Rsc9HvIreKeoefFz/gZozWC9Rev/7+M3AOH2vT5nqQAxMyD9TtF++lEBUMOSIZ0gapRNSOeQGYZohui+AV9fMwjphLq3XgOuetmyXHaJRjcBRtEJac+Rm942IW0Jo5tGnuW77AOMGLJMIVMzXT99AIZDdUInM2fShpQp/NC4uaG0uwlZSfRYKsu4XmWfwFYdfHTzTtT10wckGF9TJ0HJ8122BhjsVgLjSlz80oaXUorazI9J3DdXQzI0hJKEg+7vKjVgSE6R3hpp4Qske+rFrtOPttfxH5BsCuvst/1Hw132ASVTYiQMLdDUBOgz3UI49Bbyffwa0kpI+UT0dqV32RowphDdi3nM9/EfUK4y4WYk8O0O3RPW+RyFtscM7wTVkBXzaZ8YmmG5yj4A95F0E7U263zvowbQPqZVsQhjx5uQ1ZCnjsJwknFuAhpmSxzwLB26y9ZQHnqnSKcYzD62YXr1B3caBLsHyhNYeX8h2kPC9I52BdCbrowtloeD+iaUMcM39Isv2brKPqCMLScm7oHbe/Q9IKEbbPJliCYY2rDYQ0jDYgB6PY8WlAbJoz+0+XzygKU0aSzZxWvrT8BdSY/p4NHd+agByEsMRskYYrqfaQ2/19+GfwmGnDkcom5PAAAAAElFTkSuQmCC",
            "digitable_line": "00020126850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/ab4d2855-ee85-401a-a16d-716c743aa3af5204000053039865802BR5909AP Brasil6003Pix62070503***6304428B"
        }
    }
}

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout-stg.onekeypayments.com/v1/gateway/show?id_payment=56579207&signature=d79896d2b815303cbed4",
    "deposit_id": 300000148,
    "user_id": "121",
    "merchant_invoice_id": "postmanTest349087674",
    "payment_info": {
        "type": "BANK_TRANSFER",
        "payment_method": "SB",
        "payment_method_name": "Santander",
        "amount": 176.02,
        "currency": "BRL",
        "expiration_date": "2020-06-21 09:48:39",
        "created_at": "2020-06-20 21:48:39",
        "metadata": {
            "beneficiary_name": "Directa24 LLP",
            "agency": "1324",
            "CNPJ": "47.222.214/0005-70",
            "account": "13023469-6"
        }
    }
}

// OXXO - Mexico
{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout-stg.onekeypayments.com/v1/gateway/show?id_payment=56578556&signature=17dc33898a1e6f3f5b8a",
    "deposit_id": 300000037,
    "user_id": "11",
    "merchant_invoice_id": "postmanTest88062572",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "OX",
        "payment_method_name": "OXXO",
        "amount": 1343.07,
        "currency": "MXN",
        "expiration_date": "2020-06-22 19:42:45",
        "created_at": "2020-06-16 19:42:45",
        "metadata": {
            "bar_code": "440056578856202006210001343070",
            "digitable_line": "44005 65788 56202 00621 00013 43070 "
        }
    }
}

This integration is an extension of the REDIRECT one. It will always contain a link to redirect the customer in case you don't wan't to develop the checkout with the metadata on your website.

Secondary Metadata

The object secondary_metadata is used to display the customer with a second way to pay for the same deposit allowing them to choose the best option. For example, the user could create a deposit for a bank deposit method in Brasil, and show them our Bank Details (field metadata) as well as a Pix QR code (field secondary_metadata) in case they prefer that option.

OneShot Experience Response: Redirect

This integration generates a link to redirect the customer where they will see the details required to pay.

Success Response fields

Field name

Format

Description

checkout_type

String

Field containing the type of the request. [ONE_SHOT, HOSTED]

redirect_url

URL

URL used to redirect the customer where they can see the details to pay

deposit_id

Integer

ID of the deposit generated. 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. 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 the payment method. See the

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

Exact amount the customer has to pay

payment_info.currency

string

Currency of the amount to pay

payment_info.expiration_date

string

Date in which the deposit will be marked as expired

payment_info.created_at

string

Deposit creation date

Success Response example

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment-stg.onekeypayments.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjU3ODQ2NCIsImlhdCI6MTU5MTgyOTYzNiwiZXhwIjoxNTkzMTI1NjM2LCJsYW5ndWFnZSI6bnVsbH0.XIlYyskFpE_rh1-8sA0Bs3JzB2iMmqAXdovClPzorrZXmzol69JqkeU7TR5FMBRn",
    "deposit_id": 300000011,
    "user_id": "11",
    "merchant_invoice_id": "test123456789",
    "payment_info": {
        "type": "VOUCHER",
        "payment_method": "BC",
        "payment_method_name": "BCP",
        "amount": 6.9448,
        "currency": "PEN",
        "expiration_date": "2020-06-15 22:53:56",
        "created_at": "2020-06-10 22:53:55"
    }
}

Hosted Checkout Experience

In case that you can't collect any of the details required for the OneShot Experience, you can avoid sending it.

Using OneShot improves the experience because it reduces the amount of interactions required by the end-user.

The more details you send will personalize the Experience on our Hosted Checkout and will help in not having to ask the customer for the information again.

Hosted Checkout Request

Request Example

{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11",
        "document": "84932568207",
        "email": "juanCarlos@hotmail.com"
    },
    "description": "test description",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.onekeypayments.com/deposit_cancelled",
    "success_url": "https://www.onekeypayments.com/deposit_completed",
    "error_url": "https://www.onekeypayments.com/deposit_error",
    "notification_url": "https://www.onekeypayments.com/okp/notify",
    "logo": "https://www.onekeypayments.com/okp.png",
    "test": true,
    "request_payer_data_on_validation_failure": true,
    "mobile": false,
    "language": "pt"
}

curl --location --request POST 'https://api-stg.onekeypayments.com/v3/deposits' \
--header 'X-Login: {{X-Login}}' \
--header 'X-Date: {{X-Date}}' \
--header 'Authorization: {{Authorization}}' \
--header 'X-Idempontency-Key: {{X-Idempotency-Key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invoice_id" : "100000001",
    "amount": "100",
    "country": "BR",
    "currency": "BRL",
    "payment_types": ["BANK_TRANSFER", "BANK_DEPOSIT"]
}
'

import java.io.*;
import okhttp3.*;
public class main {
  public static void main(String []args) throws IOException{
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n");
    Request request = new Request.Builder()
      .url("https://api-stg.onekeypayments.com/v3/deposits")
      .method("POST", body)
      .addHeader("X-Login", "{{X-Login}}")
      .addHeader("X-Date", "{{X-Date}}")
      .addHeader("Authorization", "{{Authorization}}")
      .addHeader("X-Idempontency-Key", "{{X-Idempotency-Key}}")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
  }
}

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-stg.onekeypayments.com/v3/deposits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n",
  CURLOPT_HTTPHEADER => array(
    "X-Login: {{X-Login}}",
    "X-Date: {{X-Date}}",
    "Authorization: {{Authorization}}",
    "X-Idempontency-Key: {{X-Idempotency-Key}}",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

using System;
using RestSharp;
namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-stg.onekeypayments.com/v3/deposits");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("X-Login", "{{X-Login}}");
            request.AddHeader("X-Date", "{{X-Date}}");
            request.AddHeader("Authorization", "{{Authorization}}");
            request.AddHeader("X-Idempontency-Key", "{{X-Idempotency-Key}}");
            request.AddHeader("Content-Type", "application/json");
            request.AddParameter("application/json", "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}

import http.client
import mimetypes
conn = http.client.HTTPSConnection("api-stg.onekeypayments.com")
payload = "{\n    \"invoice_id\" : \"100000001\",\n    \"amount\": \"100\",\n    \"country\": \"BR\",\n    \"currency\": \"BRL\",\n    \"payment_types\": [\"BANK_TRANSFER\", \"BANK_DEPOSIT\"]\n}\n"
headers = {
  'X-Login': '{{X-Login}}',
  'X-Date': '{{X-Date}}',
  'Authorization': '{{Authorization}}',
  'X-Idempontency-Key': '{{X-Idempotency-Key}}',
  'Content-Type': 'application/json'
}
conn.request("POST", "/v3/deposits", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Notice that this request will return a Hosted Checkout because we didn't include the fields payment_method, first_name and last_name which are required for OneShot.

Hosted Checkout Response: Success

Response Fields

Field name

Format

Description

checkout_type

String

Field containing the type of the request. [ONE_SHOT, HOSTED]

redirect_url

URL

URL used to redirect the customer to our Hosted Checkout

deposit_id

Number

ID of the deposit on OKP end

user_id

String

ID of the user on your end. 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, make sure you save it as it is generated auto-generated and may be needed in the future (See )

Response Example

{
    "checkout_type": "HOSTED",
    "redirect_url": "https://payin-stg.onekeypayments.com/validate/eyJhbGciOiJIUR_JErX-j3S1pVaD",
    "deposit_id": 300000010,
    "user_id": "4-2845801292757825290",
    "merchant_invoice_id": "100000001"
}

Click here for the error response format.

Error Response

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 not always shown

type

String

Error code name. It is not always shown. See the

Error Response examples

{
    "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: TRANSACTION",
    "type": "USER_LIMIT_EXCEEDED"
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "invoiceId: must match \"^[A-Za-z0-9-_]*$\""
    ],
    "type": "BEAN_VALIDATION_ERROR"
}

Crypto payments

Please get in touch with your Account Manager in order to start processing payments with Cryptocurrencies.

When processing payments to a Cryptocurrency e-wallet, you must send in the request an object called crypto with the currency the wallet address and the network the wallet belongs to. Please click here for more details about the crypto object.

To retrieve the actual exchange of any currency against a cryptocurrency, please use the Crypto Exchange Endpoint.

When a customer pays a crypto transaction, the money is credited directly into the customer's wallet address and not into your merchant balance. After the transaction was paid by the customer, the status of the transaction will be APPROVED while we are transferring the funds to the user's wallet. As soon as the money gets into the user's wallet, the deposit will change to COMPLETED status. Please click here for more information about deposit statuses.

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

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

invoice_id

string (max length: 128)

Unique deposit ID on the merchant end

random

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

merchant_external_reference

string

Optional parameter to include additional internal information on the merchant end.

request_payer_data_on

_validation_failure

boolean

Boolean used to specify if you want to receive declines by invalid data even if it is not required by the payment method. for more info

false

[true, false]

payer

object[]

Object containing details about the customer

payment_method

string (max length: 3)

Payment method code

payment_type

string

Type of payment methods to show the customer. If null is sent and payment_method is null, "ALL" will be assumed

All

payment_types

array

Same as payment_type but multiple payment methods' types can be specified with an array. I.e.: payment_types: ["BANK_DEPOSIT", "BANK_TRANSFER"]

All

sub_merchant_id

integer

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

allow_installments

boolean

Used to specify if the credit card deposit can be created with installments. For more info visit this .

false

bank_accounts

object[]

Object containing details about the bank account from which the deposit will be made

fee_on_payer

boolean

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

false

[true, false]

surcharge_on_payer

boolean

Choose if the surcharge will be paid by the customer or debited from your balance

true

[true, false]

bonus_amount

decimal (max decimals: 2)

Used to show the customer a bonus amount. I.e.: amount:100, bonus_amount:50

User will see: Pay 100, receive 150

Number of up to 18 integers and 2 decimals

bonus_relative

boolean

Used to define if the bonus_amount was specified as a percentage of the amount or as an absolute value

false

[true, false]

strikethrough_price

decimal (max decimals: 2)

Used to show the customer a strikethrough amount. I.e.: Before: ~~150~~ Now: 100

Number of up to 18 integers and 2 decimals

description

string (max length: 100)

Deposit description. It will be shown to the customer on our Hosted Checkout as the description of the product to be acquired

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. Used to identify and prevent fraud.

String of up to 100 characters

language

string (length: 2)

Language to show the customer on the deposit page in ISO 639-1 code format. *Not all the languages are available

String of 2 characters [es, en, pt, ja]

back_url

string (max length: 2048)

Valid URL over HTTPS used to redirect the customer.

HTTPS URL

success_url

string (max length: 2048)

Valid URL over HTTPS used to redirect the customer in case the deposit flow was completed.

HTTPS URL

error_url

string (max length: 2048)

Valid URL over HTTPS used to redirect the customer in case of error while generating the deposit

HTTPS URL

notification_url

string (max length: 2048)

Valid URL over HTTPS used to receive the notifications about the deposit's changes of status. If none is sent, we will use the one configured on the Merchant Panel

HTTPS URL

logo

string (max length: 2048)

Valid URL over HTTPS used to show your logo on our Hosted Checkout Experience. If none is sent, we will use the one configured on the Merchant Panel

HTTPS URL

test

boolean

Used to flag a deposit as test. If true, the deposit will not affect the merchant's balance

false

[true, false]

mobile

boolean

Used to specify if the redirection will be made on a mobile device

false

[true, false]

early_release

boolean

Used to specify if the deposit should be early released. Useful when you want to release payments to your VIP users before it were completed

false

[true, false]

expiration

numeric

Used to express, in minutes, how long after its creation the deposit should expire. Cannot be more than the default expiration of the payment method.

Number, up to 5 integers

The fields bonus_amount, bonus_relative, strikethrough_price, and description only affect our Hosted Checkout GUI and doesn't affect any balance or calculations.

Using the same back_url, success_url and error_url is ok if you want to show your customers with a generic message when being redirected. Even better is to generate one unique link for each deposit for better user experience when being redirected. I.e.: https://www.example.com/deposit/{deposit_id_hashed}/pending

Required flags

We recommend sending the following flags to prevent declines and improve conversion rates.

mobile

The flag mobile is a boolean and has to be sent equal to true if the customer generating the deposit is using a mobile device/application. If not sent it defaults to false.

There are some payment methods that have a different flow on mobile devices compared to the flow on web devices because the payment method doesn't work the same way in those devices. When a deposit gets created as ONE_SHOT, it means the flow is assigned before the user navigates into our website, and therefore, we can't identify if the customer comes from a mobile device or not.

Considering that, if the flag mobile is not sent we could route a mobile user through the web flow, therefore, affecting the ability of the customer to complete the deposit.

request_payer_data_on_validation_failure

The flag request_payer_data_on_validation_failure can be used to prevent the request to be declined in case you send an invalid payer.phone, payer.address.state and/or payer.address.zip_code.

If it is required by the payment method, we will return you with a HOSTED CHECKOUT link where the customer will fill in the incorrect details on our checkout and if the details is not needed by the payment method, it will be ignored and the link for ONE SHOT will be returned.

Example responses:

// With the flag request_payer_data_on_validation_failure = false
// or not sent (it defaults to false)

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "payer.address.zipCode: Invalid zip code format for Country",
        "payer.address.state: Invalid State for Country",
        "payer.phone: Invalid phone for Country"
    ],
    "type": "BEAN_VALIDATION_ERROR"
}

// With the flag request_payer_data_on_validation_failure = true
// The payment method requires any of the fields so a Hosted Checkout link 
// is returned to collect those

// Typical HOSTED response

{
    "checkout_type": "HOSTED",
    "redirect_url": "https://payin.astro2pay.com/validate/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIzMzg4Mjc3OTIiLCJpYXQiOjE2MTY2MDcyMDIsImV4cCI6MTYxOTE5OTIwMn0.0-_gFW0F0Yk73J8SoAddPUaOrgsKILMVbYa1cZehrF_PEk6cj17dIXDDs6FRjkkd",
    "deposit_id": 338827792,
    "user_id": "4-1874596909371448397",
    "merchant_invoice_id": "postmanTest640841435"
}

// With the flag request_payer_data_on_validation_failure = true
// The fields payer.phone, payer.address.state and payer.address.zip_code are not
// required for the payment method

// Typical ONE_SHOT response

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment.onekeypayments.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIyMDQxNzcxMjMiLCJpYXQiOjE2MTY2MDY5NzcsImV4cCI6MTYxNzkwMjk3NywibGFuZ3VhZ2UiOiJwdCJ9.sVh4-WAW2Q5lehuDMWXhUuOVQUzqmN_XRrNBDhyOZUb36dWd9a6QX9i-JB_ocjWJ",
    "iframe": true,
    "deposit_id": 338827003,
    "user_id": "4-1874596909371448397",
    "merchant_invoice_id": "postmanTest806586134",
    "payment_info": {
        "type": "BANK_DEPOSIT",
        "payment_method": "B",
        "payment_method_name": "Bradesco",
        "amount": 571.03,
        "currency": "BRL",
        "expiration_date": "2021-03-24 22:29:37",
        "created_at": "2021-03-24 17:29:37",
        "metadata": {
            "reference": 204177123,
            "beneficiary_name": "OKP LLP",
            "account_type": "Conta corrente",
            "beneficiary_document_type": "CNPJ",
            "agency": "6444",
            "bank_url": "http://www.bradesco.com.br/html/classic/index.shtm",
            "beneficiary_document": "37.123.123/0001-53",
            "account": "49110-3"
        }
    }
}

Request Objects

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

Object containing customer's address details

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

registration_date

string (max length: 8)

Customer's registration date in your website in UTC with format yyyyMMdd. E.g.: 20211123

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

Valid state code in format. Check our

zip_code

string (max length: 16)

Customer's zip code

Bank_accounts Object

Before utilizing this feature on staging environment - Please let your responsible Account manager or Technical Account Manager know.

The bank accounts object is utilized to report the account, or multiple accounts that the customer is going to utilize before a deposit. This is done to properly match the details of the payer with the previously provided client details, making sure that the transaction is compliant.

Field name

Format

Description

Validations

account_number

string

Bank account number of the customer

String up to 45 characters

ispb_code

string

ISPB code of the customer's bank

String up to 45 characters

bank_code

string

bank_code of the customer's bank

bank_branch

string

Customer's bank branch number

String up to 45 characters

On staging environment, you can utilize the CPF "01234567890" in order to receive these details on the deposit status endpoint. BCO SANTANDER (BRASIL) S.A. branch: 0199 account: 1234567 ispb_code: 90400888 These are the details begin used for the mock customer's account, by utilizing these details on the deposit request it will be automatically completed to simulate a 100% compliant transaction.

Crypto object

This object will be used to specify that the deposit will be credited into a crypto e-wallet.

Field name

Format

Description

Validations

currency

string (max length: 10)

Symbol of the Cryptocurrency

wallet

string (max length: 128)

Address of the payer's crypto e-wallet

String of up to 128 characters

network

string (max length: 12)

Network of the wallet

Valid network symbol

Cryptocurrency symbols

Name

Symbol

Binance USD

BUSD

DAI

RIF Dollar

RDOC

Tether

USDT

USD Coin

USDC

Networks

Network

Symbol

AVAX C-Chain

AVAXC

BNB Beacon Chain

BEP2

BNB Smart Chain

BEP20

Ethereum

ERC20

Polygon

Solana

Tron

TRC20

Tezos

RSK

For other networks not in that list please reach out to your Account Manager.

Payment Methods fields requirements

Click on the link below to learn about our Payment Methods and the fields required for each of them:

Payment Methods

PreviousEndpoints NextNotifications

Last updated 2 days ago