# OKP APIs Welcome to OKP APIs documentation page. Here you will find all you need to know to integrate our products to start sending and receiving payments from your customers. ## Payments Processing APIs Our main Payment Processing APIs are listed below.\ Within each one of them you may find resourceful endpoints to consume and build a seamless integration.
Deposits APICreate a deposit request by collecting and sending the information needed to pay. We will return you with the metadata required to create the checkout on your own website or redirect the customer to the payment site./pages/-M7EsY5DfFpxd1LnXhL7/files/flwjzN7nCfwXD44d50fW
Cashouts APIDevelop your own checkout page where you will collect and send us all the details required to process the cashouts./pages/-M8big5Sd0w_zMCIpDJP/files/4lOCCIbhQ6gtuc56AYvY
Credit Cards PCI APIThis API allows you to build your own Credit Card checkout form to collect and send to us the customer's credit card details, allowing for a seamless experience without redirecting the customer to an external checkout./pages/-MNeL1IlOfzXDJNzB0k9/files/HQeRF45Irfc9jEIFX74q
{% hint style="success" %} For world-class UX and integration, we strongly suggest the use of our Deposits API OneShot Experience flow! :rocket: {% endhint %} {% hint style="info" %} Have in mind that the Deposits API Hosted Checkout 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. {% endhint %} ### Deposits API integration tools Below you will find tools to facilitate the connection and integration with our Deposits API.
Java SDK/pages/-MDB27Ucv56bd5UZlBBu/files/O4ewUOtFpDHkhilijN1T
PHP SDK/pages/-MDB2FLdN0OJFmRUECv7/files/UYNu3zj24HXppnMeWlBy
Javascript Library/pages/-MDB2fmWvC5kB_UHMDYN/files/COgyf5fL7whDf8ZeqFSR
### Deposits Plugins for Marketplaces
WooCommerce plugin/pages/kL0Cpf8UUcIMmQGLvtWl/files/Kxs0Kc234yFzLQkpmCHQ
Shopify plugin/pages/LnpTah81n5wZBQNjIgfh/files/y17mTif5IHrbixljOG8G
Magento pluginContact us./files/14UQ7KweGTHm5gOVv2j0
# Getting Started with OKP Get started with OKP by creating your own account on our Merchant Panel! In order to get started with us, you must Sign Up in our Merchant Panel to get you created a Merchant Account you will use along the way! ## Merchant Account ### Sign Up

Signup Form

Once the Sign Up was requested, we will contact you and approve your Sign Up request. {% hint style="info" %} [Sign Up request form.](https://merchants.onekeypayments.com/signup) {% endhint %} ### Account Creation As soon as we accept your request to start processing with us, you will receive an email to configure your account in our STG environment.Environments Our STG environment is a safe environment you can use to test your integration and any new features you need to test risk-free. Once you are done with the integration, we will create you an account in our PRODUCTION environment! ### Integration Integrate the [solution you are looking for](/) and make sure everything is working smoothly :nerd: ### Go Live When you have completed the integration step, you will want to start processing. For that you need an account in our PRODUCTION environment. You will be able to click on "Request Go Live" from the Home of the STG Merchant Panel. We will receive your request, review your tests and if everything is fine, you will receive an email to activate your account in production. # Deposits API Our latest Deposits API is focused on simplicity, usability and personalization and it is used to allow your customers to deposit with their local payment methods of preference. We work as a bridge between you and your customer's local payment methods such as banks, e-wallets, credit cards among others. With only one integration, you have access to the most popular payment methods in the emerging markets. In order to make that possible, we have developed our API v3 of Deposits allowing you to create payments **directly** from your own cashier **or** from one of ours in case you want us to take care of the fields needed for each country and payment method. ## Solutions Our API v3 of deposits is meant to be used on the way that fits best to your needs and technical requirements. With only one API, you can opt for different integrations: 1. [OneShot Experience](/api-documentation/deposits-api#oneshot-experience): You collect, validate and send all the details required for the payment, and you display the payment's metadata directly on your website or redirect the customers to the payment page. 2. [Hosted Checkout Experience](/api-documentation/deposits-api#hosted-checkout-experience): We take the user to a checkout page to complete missing payment details manually. This flow is triggered as Oneshot experience fallback flow. 3. [V3 PCI](/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint): You collect and send to us the Credit Card details for processing. The payment is approved/rejected instantaneously. **A PCI certificate is required for this integration**. {% hint style="success" %} Start testing all the API features with our [Postman collection here.](/api-documentation/deposits-api#postman-collection) {% endhint %} ## OneShot Experience The **OneShot Experience** is an integration where you send all the details required for the deposit and the customer itself and we will return you the metadata of the payment for you to build the payment page on your own website or a URL to redirect the customer to the payment page! > We call it **OneShot** because the customer only has to generate the payment on your cashier and pay. {% hint style="success" %} Once the payment is generated, we will send a field specifying whether the payment experience can be done **OneShot:** native on your cashier with the metadata we give you or with **Redirect**. {% endhint %} This integration offers a more personalized user experience, as the user won't leave your site but for pay (if at all). In order to make the payment creation process as smoother as possible and to avoid errors, in case you don't send a field that is required for the payment method/country, we will take care of it by asking the missing information to the customer on our Hosted Checkout instead of declining the payment:wink: . {% hint style="success" %} With this integration, it is a good idea to **ask the customer** to fill in their details **only once** and **store them in your database** so you don't have to ask them for those details each time and **instead, you send us the information directly from your database**. In case they need to **modify** something, they should do it from **their profile** and not from your cashier. {% endhint %} #### Flow
## Hosted Checkout Experience *(Not available for new integrations)* The Hosted Checkout Experience is an integrating solution where you only need to send basic details about the deposit itself, and we will generate a link you will use to redirect your customers to our Hosted Checkout where we will prompt them for any missing details like the payment method, the document, email and full name. {% hint style="info" %} This flow works only as a fallback method for ONE SHOT experience, 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. {% endhint %} Once integrated, adding new payment methods and countries with this integration requires no further development on your end since we will take care of the user experience! With this integration, you only need to send the amount and the country of the deposit and we will handle the rest. The customers will be able to choose the payment method on our Checkout, input their data and pay. {% hint style="info" %} If you already have the customer's name, email address, document ID or any other details on your database, you can opt for sending it on the request so we don't ask the customer for it again. {% endhint %} The **Hosted Checkout Experience**, allows you to personalize our Checkout by sending details like the `payment_type` to group our payment methods on different sections of your page, the `bonus_amount` or a `strikethrough_amount` to show a promo on our Hosted Checkout, the `description` to show them what they are paying for or even your own `logo` so the customer can see it on our **Hosted Checkout**. All of that, with only one integration [described here](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#deposit-creation). #### Flow ![](/files/-MK15XpDM4Ij6t5CNBn6) ## V3 PCI for Credit Cards Processing The **API V3 PCI for Credit Cards Processing** allows you to build your own Credit Card checkout form to collect and send to us the customer's credit card details, allowing for a Seamless experience without redirecting the customer to an external checkout. {% hint style="info" %} With this integration you will be handling sensitive Credit Card data, therefore, we require you to be PCI Compliant and send us your **PCI AOC certificate**. {% endhint %} #### Flow ![](/files/-MNjI7qcXaO-PYjDXe09) ## Getting Started Follow this steps to start processing payments with the OneKey Deposits API: **1 - Sign Up:** [Create your merchant](/getting-started-with-okp) account in our Merchant Panel. **2 - Get Credentials:** After your account has been activated, you will have access to your Staging (STG) Merchant Panel where you will need to * Whitelist your IPs * Retrieve your API Keys Than can be done by going to Settings -> API Access. **3 - Integrate the APIs:** Follow the instructions over this documentation to integrate our Deposits APIs. In order to move your account from STG to PRODUCTION, there are a few tests you need to check you are able to do: * [ ] [Create deposits](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint) * [ ] Manually approve and cancel (at least) one deposit from the STG Merchant Panel * [ ] Make sure you are receiving and handling our notifications correctly in your site according to [response statuses](/api-documentation/deposits-api/api-codes#deposits-status-codes) and [reject codes](/api-documentation/deposits-api/api-codes#api-error-codes) * [ ] Use the [Payment Methods](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) endpoint to retrieve payment methods availability **4 - Go Live:** Once you have completed the tests required in step 3, Request Go Live on the Home of the STG Merchant Panel to generate your account in our Production environment. We will review your tests, if everything is fine you will receive an email to activate your account on our production environment. In case there is something missing, we will let you know! **5 - Process payments:** Get the production credentials, whitelist your IPs on the production environment and start processing your payments with **OneKey**! Don't get stuck! In case you have any technical doubts not covered on this documentation, reach out to for assistance. ## Postman collection In order for you to start testing our Deposits APIs right away, we have prepared a Postman Collection you can use to test and validate your integration along with the functionalities we offer. [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.postman.co/run-collection/7b1a3f387e2f4f7ec220?action=collection%2Fimport) {% hint style="success" %} Make sure you replace the `login` and `secretKey` values with your own API Key and API Signature deposit credentials {% endhint %} # Technical and Security Aspects Learn about the technical and security aspects of our Deposits APIs ## Security Considerations * All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. * API requests without [Authentication](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature) will also fail. * You will be able to hit our APIs only from the IPs you have [previously whitelisted](/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting) on the Merchant Panel. ## Environments All the integration must be performed on our **TEST environment**, where you can perform your tests freely without risks of any kind. When you sign up with us, we will generate you an account on our STG environment where you will be able to: * See the transactions created * Approve and cancel transactions * Retrieve your API Keys * Whitelist your IPs, and more ### Endpoint domains Each environment has its own domain. The path of the [endpoints ](/api-documentation/deposits-api/endpoints)doesn't change. | Environment | Domain | | ----------- | -------------------------------------- | | Testing | `https://api-stg.onekeypayments.com/` | | Production | Provided once you complete the testing | {% hint style="info" %} Notes: * You will use the STG endpoints to integrate. * The STG and PROD environments are not communicated in any way. * No transaction created on the STG environment will be reflected on the PROD environment or vice versa. * The API Keys and configurations between environments are also different. {% endhint %} ## API Keys Our Deposits APIs uses API Keys in all of the requests to authenticate. Your API Keys can be retrieved from the Merchant Panel by going to Settings -> API Access. {% hint style="info" %} * The API Keys on the STG and PROD environments are different. {% endhint %} There are basically two set of credentials: * One API Key and one API Signature for POST operations. * One API Key key for read-only endpoints. Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). You must provide your API Key in all the requests as the basic auth username value. You do not need to provide a password. Your API Key must be sent in all the API calls using the X-Login field on the header of the request. Your API Keys, along with your [IP Addresses](/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting) are your way to authenticate yourself, therefore, do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth. ## Headers All the requests sent through the API of Deposits v3 must have the following headers. | Header | Format | Mandatory | Description | | ----------------- | :----: | :-------: | -------------------------------------------------------------------------------------------------------------- | | Authorization | String | Yes | `"D24 "` plus a hash HMAC256 to verify request integrity | | X-Login | String | Yes | Merchant `API Key` | | X-Date | String | Yes | ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z` | | Content-Type | String | Yes | `application/json` | | X-Idempotency-Key | String | No | Unique value generated by the client which the server uses to recognize subsequent retries of the same request | ### ### Authorization Signature All the requests you send must contain the `Authorization` header with an HMAC256 control string signature using your own API Signature. This is used to verify the request integrity as we will calculate the same Signature and compare it with the one you send. In case of mismatch we will decline the request. In the case of the notifications given by our APIs, those will also contain an `Authorization` value which you should calculate and compare to make sure the content was not altered by a Man in the Middle attack. Check the following page for instructions on how to calculate the Control Signature. {% content-ref url="/pages/-M7ic8P-kyDs3BecUOKC" %} [Calculating the Signature](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature) {% endcontent-ref %} ### X-Login All the requests you send must contain the header `X-Login` with your own API Key value used to authenticate yourself. Check [API Keys](/api-documentation/deposits-api/technical-and-security-aspects#api-keys). ### X-Date All the requests you send must contain the header `X-Date` with the time in which the request was created. The format is in ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. {% hint style="warning" %} Make sure you use UTC as the timezone specified and not your client's local timezone. {% endhint %} If the date you send differs in **more than 5 seconds** with the time in our servers, we will block the request for security reasons. #### Example of how to generate the correct X-Date value {% tabs %} {% tab title="Java" %} {% code title="source: JAVA SDK > src/main/java/com/directa24/client/util/ClientUtils.java" %} ```java import java.time.LocalDateTime; import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; public class ClientUtils { private static final String DATE_PATTERN = "yyyy-MM-dd'T'HH:mm:ss'Z'"; private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern(DATE_PATTERN); public static String now() { return LocalDateTime.now(ZoneOffset.UTC).format(DATE_TIME_FORMATTER); } } ``` {% endcode %} {% endtab %} {% tab title="PHP" %} {% code title="source: PHP SDK > src/util/Helpers.php" %} ```php ` header with a random and unique string. Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including `500` errors. An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. All `POST` requests accept idempotency keys. Sending idempotency keys in `GET` and `DELETE` requests has no effect and should be avoided as these requests are idempotent by definition. ### Content-Type All of our Deposits APIs are designed to receive and respond the information in JSON format. This header won't change across the requests, and shall always be: `application/json` ## IP Whitelisting For security purposes, you need to whitelist the IPs from where you will call our API. In order to whitelist your IPs and make the process as smoother as possible, you should go to **Settings -> API Access** and add the list of IPs you will possibly use under the **Deposit IP Address** section. Reach out to if you need to whitelist **our servers IPs** on your firewall. ## Best Practices We recommend you follow this list of technical and security practices to maximize the security of the information end-to-end. 1. Always ensure to verify the Signatures control string sent in the notifications to validate its veracity. 2. We convert all the data we receive to UTF-8. Make sure you are also converting it into UTF-8 to make sure both parties have the same details. 3. Always validate that a deposit is not released more than once based on the `deposit_id` (The notifications can be sent multiple times). Go to the next page to learn how to generate the requests signatures control string to verify the requests' you send and receive integrity. # Calculating the Signature Learn how to calculate and send the Signature header value to verify requests integrity ## Calculating the Signature All the calls to our Deposits APIs will contain an `Authorization` field on the header used to ensure request integrity and to authenticate yourself since you will use your own secret key (API Signature) to generate and encrypt a hash. It has to be created using **HMAC-SHA-256 (RFC 2104)** encoding and the payload must include the following details: > [X-Date](/api-documentation/deposits-api/technical-and-security-aspects#x-date) + [X-Login](/api-documentation/deposits-api/technical-and-security-aspects#x-login) + `JSONPayload` {% hint style="success" %} Use your API Signature to generate the Authorization value {% endhint %} The `Authorization` field on the header of the requests will contain the string "D24 " plus the hash generated, in the following format: > Authorization: "D24 " + HMAC256(X-Date + X-Login + JSONPayload) Example: > Authorization: D24 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf ### Notes The [`X-Login`](/api-documentation/deposits-api/technical-and-security-aspects#x-login) is your login API Key, it can be retrieved from the Merchant Panel by going to Settings -> API Access -> Deposit credentials -> API Key. The [`X-Date`](/api-documentation/deposits-api/technical-and-security-aspects#x-date) is the date in ISO8601 Datetime with Timezone. Format expected: ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. The `Authorization` value is case sensitive and must include all the above mentioned values. The `JSONPayload` is the exact same JSON you sent in the body of the request. In case the `JSONPayload` value is empty (for example in the status or payment methods endpoints), use an empty string ("") instead. The `JSONPayload` should be converted to UTF-8 before hashing it to prevent *Invalid Signature* error when sending characters with different encodings. ## Examples Check the examples in the different languages on how to properly calculate the Signature. You can also check the code of our SDKs in [Java](/deposits-tools/java-sdk) and [PHP](/deposits-tools/php-sdk) to see how it is calculated. {% tabs %} {% tab title="Java" %} ```java import java.io.ByteArrayOutputStream; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Formatter; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public static final String D24_AUTHORIZATION_SCHEME = "D24 "; private static final String HMAC_SHA256 = "HmacSHA256"; public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String JSONPayload) throws NoSuchAlgorithmException, InvalidKeyException, IOException { byte[] hmacSha256 = null; Mac mac = Mac.getInstance(HMAC_SHA256); SecretKeySpec secretKeySpec = new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), HMAC_SHA256); mac.init(secretKeySpec); hmacSha256 = mac.doFinal(buildByteArray(xDate, apiKey, JSONPayload)); return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256); } private static byte[] buildByteArray(String xDate, String apiKey, String JSONPayload) throws IOException { ByteArrayOutputStream bos = new ByteArrayOutputStream(); bos.write(xDate.getBytes(StandardCharsets.UTF_8)); bos.write(apiKey.getBytes(StandardCharsets.UTF_8)); if (JSONPayload != null) { bos.write(payload.getBytes(StandardCharsets.UTF_8)); } return bos.toByteArray(); } private static String toHexString(byte[] bytes) { Formatter formatter = new Formatter(); for (byte b : bytes) { formatter.format("%02x", b); } return formatter.toString(); } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using System.Text; using System.IO; using System.Security.Cryptography; namespace Application { class Directa24Example { public readonly static string D24_AUTHORIZATION_SCHEME = "D24 "; private readonly static string HMAC_SHA256 = "HmacSHA256"; public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String jsonPayload) { byte[] hmacSha256 = null; var apiSignatureEncod = Encoding.UTF8.GetBytes(apiSignature); var hash = new HMACSHA256(apiSignatureEncod); hmacSha256 = hash.ComputeHash(buildByteArray(xDate, depositKey, jsonPayload)); return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256).ToLower(); } private static byte[] buildByteArray(String xDate, String apiKey, String jsonPayload) { try { MemoryStream stream = new MemoryStream(); var xDateEncod = Encoding.UTF8.GetBytes(xDate); var apiKeyEncod = Encoding.UTF8.GetBytes(apiKey); stream.Write(xDateEncod, 0, xDateEncod.Length); stream.Write(apiKeyEncod, 0, apiKeyEncod.Length); if (!string.IsNullOrWhiteSpace(jsonPayload)) { var jsonPayloadEncod = Encoding.UTF8.GetBytes(jsonPayload); stream.Write(jsonPayloadEncod, 0, jsonPayloadEncod.Length); } return stream.ToArray(); } catch (Exception ex) { throw ex; } } private static string toHexString(byte[] bytes) { return BitConverter.ToString(bytes).Replace("-", string.Empty); } } } ``` {% endtab %} {% tab title="PHP" %} ```php `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 | {% tabs %} {% tab title="201 Deposit request created successfully with ONE\_SHOT Experience" %} ```java { "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": "test943044826", "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" } } ``` {% endtab %} {% tab title="400 Deposit request failed due to field validation error" %} ```java { "code": 201, "description": "Field validation error. Check details", "details": [ "invoiceId: must match \"^[A-Za-z0-9]*$\"" ] } ``` {% endtab %} {% endtabs %} ## 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.

| {% hint style="success" %} Test all the API features with our [Postman collection here.](/api-documentation/deposits-api#postman-collection) {% endhint %} ## 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 :wink: . ### OneShot Request example {% hint style="success" %} 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](/api-documentation/deposits-api/payment-methods) to learn more about those requirements. {% endhint %} {% tabs %} {% tab title="JSON" %} ```javascript { "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" } ``` {% endtab %} {% tab title="cURL" %} ```java 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" }' ``` {% endtab %} {% tab title="Java" %} ```java 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()); } } ``` {% endtab %} {% tab title="PHP" %} ```php 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(); ``` {% endtab %} {% tab title="C#" %} ```csharp 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); } } } ``` {% endtab %} {% tab title="Python" %} ```python 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')) ``` {% endtab %} {% endtabs %} ### 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](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#response-fields) 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 | {% hint style="warning" %} Please note that the `metadata` and the `secondary_metadata`objects 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. {% endhint %} #### Success Response example {% tabs %} {% tab title="PIX" %} ```java { "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 // // qr_code: PNG image encoded in base64. You can use the following HTML tag // to render the QR code on your website: // // // 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 ``` {% endtab %} {% tab title="BOLETO" %} ```javascript { "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" } } } ``` {% endtab %} {% tab title="BANK\_DEPOSIT" %} ```javascript { "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" } } } ``` {% endtab %} {% tab title="BANK\_TRANSFER" %} ```javascript { "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" } } } ``` {% endtab %} {% tab title="VOUCHER" %} ```javascript // 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 " } } } ``` {% endtab %} {% tab title="PIX BIOMETRIC" %} ```json { "checkout_type": "ONE_SHOT", "redirect_url": "https://payment.checkoutogate.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIxMDY2MjM5MjUyIiwiaWF0IjoxNzQxNzA2NTk1LCJleHAiOjE3NDMwMDI1OTUsImxhbmd1YWdlIjoiZXMifQ.hrOpWuKKDJEfMDbfMEVcAhPaYgHXJcUxo9Wp3UddIVFdjSq6ks1PYjHhYwok2yBW/BR/IXB/9881/53332", "iframe": true, "deposit_id": 1228323211, "merchant_invoice_id": "postmanTest807480513", "payment_info": { "type": "VOUCHER", "payment_method": "IXB", "payment_method_name": "Pix Biometric", "amount": 10.00, "currency": "BRL", "expiration_date": "2025-03-11 18:23:13", "created_at": "2025-03-11 15:23:13", "metadata": { "sub_type": "REDIRECT", "redirect_url": "https://payment.checkoutogate.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIxMDY2MjM5MjUyIiwiaWF0IjoxNzQxNzA2NTk1LCJleHAiOjE3NDMwMDI1OTUsImxhbmd1YWdlIjoiZXMifQ.hrOpWuKKDJEfMDbfMEVcAhPaYgHXJcUxo9Wp3UddIVFdjSq6ks1PYjHhYwok2yBW/BR/IXB/9881/53332" } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} This integration is an extension of the [REDIRECT](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience-response-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. {% endhint %} #### 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. ![](/files/-Mjnwo2_uafi4C12G7PX) ### 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 [list here.](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types) | | `payment_info.payment_method` | String | Payment method code. See the [list here.](/api-documentation/deposits-api/payment-methods) | | `payment_info.payment_method_name` | String | Payment method name. See the [list here.](/api-documentation/deposits-api/payment-methods) | | `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 ```javascript { "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. {% hint style="success" %} 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. {% endhint %} ### Hosted Checkout Request #### Request Example {% tabs %} {% tab title="JSON" %} ```javascript { "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" } ``` {% endtab %} {% tab title="cURL" %} ```java 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"] } ' ``` {% endtab %} {% tab title="Java" %} ```java 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()); } } ``` {% endtab %} {% tab title="PHP" %} ```php "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; ``` {% endtab %} {% tab title="C#" %} ```csharp 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); } } } ``` {% endtab %} {% tab title="Python" %} ```python 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")) ``` {% endtab %} {% endtabs %} {% hint style="info" %} 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. {% endhint %} ![Select payment\_method.](/files/NbhnfgFmTzrvWXwWf9SQ) ![Fill the missing information required.](/files/niu5Kjw4G4wzv2l2WXB8) ![Payment created! ](/files/xP5aZvfoGc9wBHsoqGlu) ### Hosted Checkout Response: Success #### Response Fields
Field nameFormatDescription
Field nameFormatDescription
checkout_typeStringField containing the type of the request. [ONE_SHOT, HOSTED]
redirect_urlURLURL used to redirect the customer to our Hosted Checkout
deposit_idNumberID of the deposit on OKP end
user_idStringID of the user on your end. If you didn't send it, it is generated by us
merchant_invoice_idStringID 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 refunds)
#### Response Example ```javascript { "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](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#error-responses) for the error response format. ## Error Response ### Error Response fields | Field name | Format | Description | | ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | `code` | Number | Error code. See the[ list of error codes](/api-documentation/deposits-api/api-codes#api-error-codes) | | `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 [list of error codes](/api-documentation/deposits-api/api-codes#api-error-codes) | ### Error Response examples ```java { "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 {% hint style="info" %} Please get in touch with your Account Manager in order to start processing payments with Cryptocurrencies. {% endhint %} 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](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#crypto-object) for more details about the `crypto` object. To retrieve the actual exchange of any currency against a cryptocurrency, please use the [Crypto Exchange Endpoint.](/api-documentation/deposits-api/endpoints/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](/api-documentation/deposits-api/api-codes#deposits-status-codes) 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 | | [Country codes](/knowledge-base/countries-specifications#currencies) | | `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` | [Currencies](/knowledge-base/countries-specifications#currencies) | | `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. [here](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#request_payer_data_on_validation_failure) for more info | false | `[true, false]` | | `payer` | object\[] | Object containing details about the customer | | [Payer object](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payer-object) | | `payment_method` | string (max length: 3) | Payment method code | | [Payment method codes](/api-documentation/deposits-api/payment-methods) | | `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 available](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types) | | `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 | [Payment types available](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types) | | `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 link.

| `false` | | | `bank_accounts` | object\[] | Object containing details about the bank account from which the deposit will be made | | [bank\_accounts object](#bank_account-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]` | | `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

| {% hint style="warning" %} The fields `bonus_amount`, `bonus_relative`, `strikethrough_price`, and `description` only affect our Hosted Checkout GUI and doesn't affect any balance or calculations. {% endhint %} {% hint style="success" %} 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` {% endhint %} ### Required flags {% hint style="success" %} We recommend sending the following flags to prevent declines and improve conversion rates. {% endhint %} #### 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: {% tabs %} {% tab title="Error" %} ```java // 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" } ``` {% endtab %} {% tab title="Success: HOSTED CHECKOUT" %} ```java // 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" } ``` {% endtab %} {% tab title="Success: ONE SHOT" %} ```java // 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" } } } ``` {% endtab %} {% endtabs %} ## Request Objects ### Payer Object
Field nameFormatDescriptionDefaultValidationsRequired
idstring (max length: 128)Customer's ID generated on your end. Used to locate user's transaction on our Merchant PanelIf none is sent, we will autogenerate it^[A-Za-z0-9]*$Recommended
documentstring (max length: 30)Customer's document ID. Ensure it is correct and the user can't change it every time he/she depositsdocument validationsYes
document_typestring (max length: 10)Customer's document type. Optional, if sent must be a valid document typedocument types validationsYes
emailstring (max length: 255)Valid customer's email addressValid email addressYes
first_namestring (max length: 128)Customer's first nameString of up to 128 charactersYes
last_namestring (max length: 128)Customer's last_nameString of up to 128 charactersYes
addressobjectObject containing customer's address detailsaddress objectNo
phonestring (max length: 32)Valid customer's phone numberphone number validationsNo
birth_datestring (max length: 8)Customer's birthdate in format yyyyMMdd. E.g.: 19801027Numeric format expected: yyyyMMddNo
registration_datestring (max length: 8)Customer's registration date in your website in UTC with format yyyyMMdd. E.g.: 20211123 Numeric format expected: yyyyMMddNo
### 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](/api-documentation/deposits-api/endpoints/country-states-codes-endpoint) | Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. Check our [States endpoint here](/api-documentation/deposits-api/endpoints/country-states-codes-endpoint) | | `zip_code` | string (max length: 16) | Customer's zip code | [zip\_code validations](/knowledge-base/countries-specifications#postal-code-validations) | ### Bank\_accounts Object {% hint style="danger" %} Before utilizing this feature on staging environment - Please let your responsible Account manager or Technical Account Manager know. {% endhint %} 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.\ \ If no details are sent, then the bank account validation will not happen, **this is mandatory for regulated gambling processing.**
Field nameFormatDescriptionValidations
account_numberstring Bank account number of the customerString up to 45 characters
ispb_codestringISPB code of the customer's bankString up to 45 characters
bank_codestringbank_code of the customer's bankBank code list
bank_branchstringCustomer's bank branch numberString up to 45 characters
{% hint style="info" %} On staging environment, you can utilize the CPF "01234567890" in order to receive these details on the[ deposit status endpoint](/api-documentation/deposits-api/endpoints/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. {% endhint %} ### Crypto object This object will be used to specify that the deposit will be [credited into a crypto e-wallet](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#crypto-payments). | Field name | Format | Description | Validations | | ---------- | ------------------------ | -------------------------------------- | :-----------------------------------------------------------------------------------------------------------------------: | | `currency` | string (max length: 10) | Symbol of the Cryptocurrency | [Valid Cryptocurrency symbol](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#cryptocurrency-symbols) | | `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 | 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 | Polygon | | Solana | Solana | | Tron | TRC20 | | Tezos | Tezos | | RSK | RSK | {% hint style="success" %} For other networks not in that list please reach out to your Account Manager. {% endhint %} ## Payment Methods fields requirements Click on the link below to learn about our Payment Methods and the fields required for each of them: {% content-ref url="/pages/-M7EyIJfwI7M7iTDXAkL" %} [Payment Methods](/api-documentation/deposits-api/payment-methods) {% endcontent-ref %} # Notifications Learn about how the notifications for deposits works ## Deposit status notifications Every time a deposit changes its status, we will send you an asynchronous notification to the `notification_url` you sent in the request or the one you have configured under the section "Settings -> API Access -> Confirm URL" containing the ID of the deposit. **Once received the notification, you should check its new status with the**[ **Deposit Status Endpoint**](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) **and update it on your end accordingly.** {% hint style="info" %} Bear in mind we will only connect through ports 80 and 443. Make sure your `notification_url` has one of those ports open accepting connections from us. {% endhint %} ## STG Testing In the STG environment, in order to test the full flow you can manually set a deposit to COMPLETED / CANCELLED status by login into the [STG Merchant Panel](https://merchants-stg.directa24.com/login) and going to Transactions -> Deposits. Those options will change the status of the deposit, therefore **sending the respective notification to your notification\_url after a few minutes**. ![Approve/Cancel from the Deposits view.](/files/tX6pTBfjjGMRq1hjY0RD) ![You can also Approve/Cancel deposits from the Transaction details](/files/FXHD9EjIN9TcBdWVwNkx) ## Notifications fields | Field | Format | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `deposit_id` | Number | ID of the deposit. Use this ID to [check the status of the deposit.](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) | ## Notifications example ```javascript { "deposit_id": 3000000001 } ``` ## Retry logic Every time a deposit changes its status, we will send you a notification so you can [check its status](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) back. In case that for some reason your server was unable to handle our notification and you returned an HTTP code different than 2XX, we will retry the notification up to 5 more times or until you respond with HTTP 2XX, whatever comes first. {% hint style="success" %} In case of errors while handling the notification, make sure you will answer with an HTTP code distinct than 2XX, that way we will retry the notification. {% endhint %} The time between each of the 5 notifications attempts will be exponential: 5, 25, 125 and 625 minutes accordingly. When a notification failed to be sent, it will be shown like this in our Merchant Panel: ![](/files/-M9_UqvQBGblaqYL1-oD) If you see the errors from the screenshot above, it means the payment was successfully completed and the money was credited to your account but suddenly we couldn't notify you. Keep reading to know how to resend the notifications. ## Resend Notifications In case your system was unable to handle the notification in any of the 5 attempts, you can always check its status with the [Deposit Status Endpoint.](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the deposit (Transactions -> Deposits) and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent. {% hint style="success" %} It can take up to 1 minute for the notification to be resent. {% endhint %} ![](/files/-M9zU27QNwGCCPG-JJEq) # Transactional Account Endpoint This endpoint allows you to check your balance between your proprietary and transactional accounts, and also move balance freely from one to another. {% hint style="info" %} To get a brief summary of the flow of this endpoint, [you can check it here](/api-documentation/deposits-api/endpoints/transactional-account-endpoint/understanding-the-solution) {% endhint %} {% hint style="warning" %} Before utilizing any of our APIs, you should contact your responsible account manager, with your company's name and CNPJ so we can make the necessary configurations for you to proceed. {% endhint %} ## Move balance between accounts `POST` `https://api-stg.onekeypayments.com/v1/wallet/transaction`\ \ Allows you to move a specific amount between your proprietary accounts, and transactional account **Headers**\ \ You can check how the [headers and signature are calculated here.](/api-documentation/deposits-api/technical-and-security-aspects)
NameTypeDescription
Content-Typestringapplication/json
X-DatestringISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-LoginstringMerchant X-Login API Key
AuthorizationstringAuthorization control hash
X-Idempotency-KeystringUnique idempotency key
**Example Request:** ```json { "source": "PROPRIETARY", "destination": "TRANSACTIONAL", "currency": "BRL", "amount": 100.00 } ``` **Example response:** ```json { "currency": "BRL", "proprietary_balance": 100.00, "transactional_balance": 100.00 } ``` In this example, we've moved 100.1 BRL from our OWNER account to our TRANSACTIONAL account. ## Get Balance `GET` `https://api-stg.onekeypayments.com/v1/wallet/balance`\ \ Allows you to check your total balance between accounts.\ \ **Example of successful response:** ```json {     "balances": [         {             "amount": 200.00,             "currency": "BRL",             "type": "PROPRIETARY"         },         {             "amount": 222.00,             "currency": "BRL",             "type": "TRANSACTIONAL"         }     ] } ``` # Understanding the Solution This solution allows having a transactional account, and an proprietary account, managing different balances, and also a bank account check solution. ## Proprietary Account and Transactional Account With the transaction account Solution, you're going to have 2 accounts tied to your merchant account.\
**Proprietary account**\ \ The first is the proprietary (or owner) account, which is the account where you can utilize all the funds as you desire to do so.\ \ This account should include all the funds that no longer belong to the final clients, and cannot be altered.\ \ These funds will be used to pay fees and create settlements to your own bank account.\ \ **Transactional account**\ \ You will also have a transactional account.\ \ All funds from completed deposits would go here and should remain in this account until the funds can no longer be altered by the players.\ \ These funds cannot be used for anything until they are moved to your proprietary account.\ \ **Basic Deposit Flow**
{% hint style="info" %} * First, the user creates a deposit, and we get notified by you, the merchant. * After this, we send the payment information to the user. * Once the user completes the deposit, the funds get added to your transactional balance account {% endhint %} #### Basic Cashout Flow
{% hint style="info" %} * First, the user wants to create a cashout, once we receive all the information from you, we go to the next step. * If your transactional account has enough balance in order to process the cashout, we'll remove the balance from there * Otherwise, we'll utilize the funds directly from your proprietary's account. * After this, the cashout is processed, and the funds are sent to the customer's bank account. {% endhint %} If you want to learn more about the endpoints used in this solution, you can check them out here: {% content-ref url="/pages/uvPyxXZ7OELAWQJURIvt" %} [Transactional Account Endpoint](/api-documentation/deposits-api/endpoints/transactional-account-endpoint) {% endcontent-ref %} # 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 | {% tabs %} {% tab title="200 Transaction successfully processed" %} ```java { "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" } } ``` {% endtab %} {% tab title="400 Transaction failed due to field validation error" %} ```java { "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" } ``` {% endtab %} {% endtabs %} #### 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 | {% hint style="info" %} The usage of this endpoint is restricted to PCI Compliant merchants who have shared their PCI AOC certificate with their Account Manager. {% endhint %} ## V3 PCI Request A request made through the **PCI Deposit Creation** endpoint works almost in the same way than the [non-PCI Deposits endpoint](/api-documentation/deposits-api/endpoints/deposit-creation-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 {% tabs %} {% tab title="JSON" %} ```javascript { "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 } ``` {% endtab %} {% endtabs %} ### ### 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.](/api-documentation/deposits-api/payment-methods) | | `payment_info.payment_method_name` | String | Payment method name. See the [list here.](/api-documentation/deposits-api/payment-methods) | | `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 {% tabs %} {% tab title="Success" %} ```javascript { "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" } } ``` {% endtab %} {% tab title="Rejection" %} ```javascript { "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" } } ``` {% endtab %} {% endtabs %} ### Response Example: Error #### Response Fields | Field name | Format | Description | | ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | `code` | Number | Error code. See the[ list of error codes](/api-documentation/deposits-api/api-codes#api-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](/api-documentation/deposits-api/api-codes#api-error-codes) | #### #### Response Example ```java { "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 nameFormatDescriptionDefaultValidations
Field nameFormatDescriptionDefaultValidationsRequired
countrystring (length: 2)Country code of the deposit in ISO 3166-1 alpha-2 code formatCountry codesYes
amountdecimal (max decimals: 2)Deposit amount in the currency specifiedNumber of up to 18 integers and 2 decimals placesYes
currencystring (length: 3)Currency code of the amount in ISO 4217 formatUSDSee CurrenciesYes
installmentsinteger (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_idstring (max length: 128)Unique deposit ID on the merchant endrandom^[A-Za-z0-9-_]*$Yes
payerobject[]Object containing details about the payerPayer objectYes
credit_cardobject[]Object containing the credit card detailsCredit card objectYes
descriptionstring (max length: 100)Transaction description. It could be shown on the customers credit card extractString of up to 100 charactersNo
client_ipstringValid IPv4 or IPv6 AddressIPv4/v6 AddressYes
device_idstring (max length: 100)Unique customer's device ID. Used to identify and prevent fraud.String of up to 100 charactersNo
card_tokenstring (max length: 50)Card Token generated with Cards SDK Without User Interface.String of up to 50 charactersNo
fee_on_payerbooleanChoose if the deposit's fee will be paid by the customer or debited from your balancefalse[true, false]No
## 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](https://en.wikipedia.org/wiki/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 nameFormatDescriptionDefaultValidations
Field nameFormatDescriptionDefaultValidationsRequired
idstring (max length: 128)Customer's ID generated on your end. Used to locate user's transaction on our Merchant PanelIf none is sent, we will autogenerate it^[A-Za-z0-9]*$Recommended
documentstring (max length: 30)Customer's document ID. Ensure it is correct and the user can't change it every time he/she depositsdocument validationsYes
document_typestring (max length: 10)Customer's document type. Optional, if sent must be a valid document typedocument types validationsYes
emailstring (max length: 255)Valid customer's email addressValid email addressYes
first_namestring (max length: 128)Customer's first nameString of up to 128 charactersYes
last_namestring (max length: 128)Customer's last nameString of up to 128 charactersYes
addressobject[]Object containing customer's address detailsaddress objectNo
phonestring (max length: 32)Valid customer's phone numberphone number validationsNo
birth_datestring (max length: 8)Customer's birthdate in format yyyyMMdd. E.g.: 19801027Numeric format expected: yyyyMMddNo
### 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](/api-documentation/deposits-api/endpoints/country-states-codes-endpoint) | Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) format. Check our [States endpoint here](/api-documentation/deposits-api/endpoints/country-states-codes-endpoint) | No | | `zip_code` | string (max length: 16) | Customer's zip code | [zip\_code validations](/knowledge-base/countries-specifications#postal-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. {% hint style="info" %} For all **Results**: * Expiration date has to be in the future (`expiration_month` *+* `expiration_year)` * `cvv`: any three numeric digits. * `holder_name` : any name. {% endhint %} {% hint style="success" %} For **Success** Results in STG: any card number not listed below, will simulate a success scenario.\ (For example, Card Number: 4111111111111111) {% endhint %} ### 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. | # Deposit Status Endpoint Retrieve the status of a previously created deposit ## Deposit Status `GET` `https://api-stg.onekeypayments.com/v3/deposits/{deposit_id}` This endpoint allows you to retrieve the status of a deposit request. #### Path Parameters | Name | Type | Description | | --------------------------------------------- | ------- | --------------------------------------------------------- | | deposit\_id\* | integer | OKP deposit\_id. It is obtained when creating the deposit | #### Headers
NameTypeDescription
X-Date*stringISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*stringMerchant X-Login API Key
Authorization*stringAuthentication signature hash
{% tabs %} {% tab title="200 Deposit status successfully retrieved." %} ```java { "user_id": "11", "deposit_id": 300004285, "invoice_id": "989409592", "country": "BR", "currency": "BRL", "local_amount": 53162.00, "usd_amount": 1000.00, "bonus_amount": 1.50, "bonus_relative": "false", "payment_method": "VI", "payment_type": "CREDIT_CARD", "status": "COMPLETED", "payer": { "document": "17532655253", "document_type": "CPF", "email": "johnSmith1@directa24.com", "first_name": "John", "last_name": "Smith", "address": { "city": "Sao Paulo", "state": "SP", "street": "John Street 2453", "zip_code": "938475-234" } }, "fee_amount": 2.50, "fee_currency": "USD", "bank_account": { "account_number": "10122538", "bank_branch": "90", "ispb_code": 60746948, "bank_name": "Caixa", "account_type": "SAVING", "licensed_bank": true }, "card_detail": { "card_holder": "John Smith", "brand": "Visa", "masked_card": "1234 56** **** 6789", "expiration": "2023-12", "card_type": "DEBIT", "transaction_result": "Transaction Approved" } } ``` {% endtab %} {% tab title="400 The deposit\_id specified is not valid" %} ``` ``` {% endtab %} {% tab title="404 The deposit\_id specified could not be found." %} ``` ``` {% endtab %} {% endtabs %} ## Request You can trigger the check of the status of a deposit at any moment you consider pertinent. However, every time a deposit changes its status, we will send you a [notification](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint/notifications) containing the ID of the deposit so that you can check its status back to retrieve the new deposit's status. ### Example request In the status endpoint, all the request have to be sent as GET, containing the[ usual headers](/api-documentation/deposits-api/technical-and-security-aspects#headers). Regarding the Authorization value, since the body of the requests will be empty, you should use an empty ("") string or nothing as the `jsonPayload` field. {% tabs %} {% tab title="cURL" %} ```bash curl --location --request GET 'https://api-stg.onekeypayments.com/v3/deposits/300004285' \ --header 'X-Login: xxxxxxx' \ --header 'X-Date: 2020-06-24T17:13:21Z' \ --header 'Authorization: D24 e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a' \ --data-raw '' ``` {% endtab %} {% tab title="JAVA" %} ```java import java.io.*; import okhttp3.*; public class main { public static void main(String []args) throws IOException{ OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api-stg.onekeypayments.com/v3/deposits/300004285") .method("GET", null) .addHeader("X-Login", "xxxxxxx") .addHeader("X-Date", "2020-06-24T17:13:21Z") .addHeader("Authorization", "D24 e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/deposits/300004285"); client.Timeout = -1; var request = new RestRequest(Method.GET); request.AddHeader("X-Login", "xxxxxxx"); request.AddHeader("X-Date", "2020-06-24T17:13:21Z"); request.AddHeader("Authorization", "D24 e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a"); request.AddParameter("application/json", "", ParameterType.RequestBody); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/deposits/300004285", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "X-Login: xxxxxxxx", "X-Date: 2020-06-24T17:13:21Z", "Authorization: D24 e339247fb57b10c053159cf87d3a88415f9be567beb46a93f6839d9fc45d2c8a" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Example response {% tabs %} {% tab title="COMPLETED" %} ```java { "user_id": "11", "deposit_id": 300004285, "invoice_id": "989409592", "country": "BR", "currency": "BRL", "local_amount": 53162.00, "usd_amount": 1000.00, "bonus_amount": 100.00, "bonus_relative": "false", "payment_method": "VI", "payment_type": "CREDIT_CARD", "status": "COMPLETED", "payer": { "document": "17532655253", "document_type": "CPF", "email": "johnSmith1@onekeypayments.com", "first_name": "John", "last_name": "Smith", "address": { "city": "Sao Paulo", "state": "SP", "street": "John Street 2453", "zip_code": "938475-234" } }, "fee_amount": 2.50, "fee_currency": "USD", "refunded": False, "current_payer_verification": "UNMATCHED", "bank_account": { "account_number": "10122538", "bank_branch": "90", "ispb_code": 60746948, "bank_name": "Caixa", "account_type": "SAVING", "licensed_bank": true }, "card_detail": { "card_holder": "John Smith", "brand": "Visa", "masked_card": "1234 56** **** 6789", "expiration": "2023-12", "card_type": "DEBIT", "transaction_result": "Transaction Approved" } } ``` {% endtab %} {% tab title="PENDING" %} ```java { "user_id": "11", "deposit_id": 300004284, "invoice_id": "1000000001", "currency": "BRL", "amount": 1000.00, "bonus_amount": 1.50, "payment_method": "VI", "payment_type": "CREDIT_CARD", "status": "PENDING", "fee_amount": 2.50, "fee_currency": "USD", } ``` {% endtab %} {% tab title="CREATED" %} ```java { "user_id": "11", "deposit_id": 300004284, "invoice_id": "1000000001", "currency": "BRL", "amount": 1000.00, "bonus_amount": 1.50, "status": "CREATED" } ``` {% endtab %} {% endtabs %} ### Response fields | Field name | Format | Description | | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | String | ID generated for the user on OKP end | | `deposit_id` | Number | ID of the deposit on OKP end | | `invoice_id` | String | ID of the deposit on the merchant end | | `country` | String | [Country ISO code](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | String | [Local currency code](/knowledge-base/countries-specifications#countries-and-currencies) | | `local_amount` | Number | Amount in local currency | | `usd_amount` | Number | Amount in USD | | `bonus_amount` | Number | The amount specified as bonus in the request | | `bonus_relative` | Boolean | Specifies if the `bonus_amount` is absolute or relative. It will be shown only if the `bonus_amount` is not null | | `payment_method` | String | [Payment method code](/api-documentation/deposits-api/payment-methods) specified on the deposit request or selected by the user on our checkout. It will be shown only if the user has selected a payment method | | `payment_type` | String | [Type of the payment method](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types). It will be shown only if the user has selected a payment method | | `status` | String | [Status of the deposit](/api-documentation/deposits-api/api-codes#deposits-status-codes) | | `payer[]` | Object | Object containing information about the payer. Only the values you've sent or we've collected will be shown. | | `payer.document` | String | Payer's document of identity | | `payer.document_type` | String | Payer's type of their document of identity | | `payer.email` | String | Payer's email | | `payer.first_name` | String | Payer's first name | | `payer.last_name` | String | Payer's last name | | `payer.address[]` | Object | Object containing the address details about the payer. Only the values you've sent or we've collected will be shown. | | `payer.address.city` | String | Payer's city | | `payer.address.state` | String | Payer's state ISO code | | `payer.address.street` | String | Payer's street | | `payer.address.zip_code` | String | Payer's zip code | | `fee_amount` | Number | Fee of the deposit in the currency of your balance. It will be shown only if the payment\_method was sent by you or selected by the customer | | `fee_currency` | String | Currency of your balance. It will be shown only if the payment\_method was sent by you or selected by the customer | | `bank_account[]` | Object | Details about the bank account of the payer. This object is shown for all completed PIX transactions. | | `bank_account.account_number` | Number | Account number of the payer. | | `bank_account.bank_branch` | Number | Branch number of the payer (agencia). | | `bank_account.ispb_code` | Number | ISPB code of the payer's bank. | | `bank_account.bank_name` | String | Name of the payer's bank. | | `bank_account.account_type` | String | Account type of the payer. Savings , Checking and Payment | | `bank_account.licensed_bank` | Boolean | TRUE if the account from the payer is from a licensed bank, FALSE if it's not. | | `card_detail[]` | Object | Details about the credit card of the payer. This object will be shown only in case of credit card deposits and if we have the information. | | `card_detail.card_holder` | String | Name of the card holder used to pay | | `card_detail.brand` | String | Brand of the card used to pay | | `card_detail.masked_card` | String | Masked card number used to pay | | `card_detail.expiration` | String | Expiration of the card used to pay in format YYYY-MM (`2023-12`) | | `card_detail.card_type` | String | Type of card used: CREDIT/DEBIT | | `card_detail.transaction_result` | String | The result message of the credit card transaction | | `refunded` | Boolean | It shows if the deposit it was refunded or not. | | `current_payer_verification` | String | [It shows if the current payer is the same person who creates the deposit](#current_payer_verification). It will be shown only if it is not null. | | payment\_provider\_reference | String | (Only for PSE deposits) Payment provider reference | ## Parameter current\_payer\_verification Through the parameter current\_payer\_verification you can check if the current payer is the same person who created the deposit. Below you can see the possible results for this parameter:\ \ Match --> The document of the person who paid is the same as the one of the person who created the payment.\ \ Unmatch --> The documents are different.\ \ No client document -> It is when there is no document of the person who proceed with the payment (Current payer).\ \ No current payer data -> It is when there is no document of the person who proceed with the payment (Current payer)
{% hint style="warning" %} In order to make the experience more personalized, we may add more fields to this response's object in the future. Please develop your integration to be able to ignore new fields to avoid any issues. {% endhint %} {% hint style="success" %} If you are not sending all the payer details in the deposit request, make sure you store the details we collect and share with this endpoint so that in future attempts you can re-use them instead of having the payers to fill in the same details every time they deposit. {% endhint %} ## Status Flow [Click here](/api-documentation/deposits-api/api-codes#deposits-status-codes) to see each Deposit Status meaning. ### Hosted Checkout Status Flow ![Hosted Checkout Status Flow Diagram](/files/-MAmeg3u4xX0qi35vFPw) ### OneShot Checkout Status Flow ![OneShot Status Flow Diagram](/files/-MAmeEV0RUvkskAe1Aji) {% hint style="info" %} 1. The DECLINED status is not a status by itself. It means the transaction couldn't be created because of an error with the data, the customer or the merchant configuration. No transaction will change its status from DECLINED. 2. COMPLETED and CANCELLED\* are final status. 3. \*There are cases in which the users pays after the deposit expired, or paid an incorrect amount and the deposit gets expired. When that happens manual intervention is required to approve the deposit hence a deposit could change its status from EXPIRED or CANCELLED to COMPLETED. 4. EARLY RELEASED will only be used if you specified it in the deposit request. 5. FOR REVIEW is a transient status we use to specify that the deposit is under revision. 6. If the user doesn't pays, the transaction will be marked as EXPIRED. After 7 days it will change to CANCELLED. {% endhint %} ## Status codes Check all the possible status in the following page: {% content-ref url="/pages/-M8MAwZ0r4Szs2f\_lbbI" %} [API Codes](/api-documentation/deposits-api/api-codes) {% endcontent-ref %} # Payment Methods Endpoint The Payment Methods endpoint allows you to retrieve the complete list of payment methods you have available for the country specified ## Payment Methods `GET` `https://api-stg.onekeypayments.com/v3/payment_methods?country={country}` The **`payment_methods`** endpoint allows you to retrieve the complete list of payment methods you have available for the country specified, along with its payment method's type, code, logos and more. #### Query Parameters | Name | Type | Description | | ------- | ------ | ---------------- | | country | string | Country ISO code | #### Headers | Name | Type | Description | | ------------- | ------ | ----------------------------- | | Authorization | string | "Bearer " + Read-Only API Key | {% tabs %} {% tab title="200 Payment methods successfully retrieved" %} ```java [ { "country": "BR", "code": "BB", "name": "Banco do Brasil", "type": "BANK_DEPOSIT", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/BB.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "BZ", "name": "Banco Original", "type": "VOUCHER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/BZ.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "UL", "name": "Banrisul AM", "type": "BANK_TRANSFER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/UL.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "BL", "name": "Boleto", "type": "VOUCHER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/BL.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "B", "name": "Bradesco", "type": "BANK_DEPOSIT", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/B.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "CA", "name": "Caixa", "type": "BANK_TRANSFER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/CA.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "I", "name": "Itau", "type": "BANK_DEPOSIT", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/I.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "LC", "name": "Loterias Caixa", "type": "VOUCHER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/LC.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "PP", "name": "Picpay", "type": "VOUCHER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/PP.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "SB", "name": "Santander", "type": "BANK_TRANSFER", "status": "OK", "logo": "https://resources.directa24.com/cashin/payment_method/square/SB.svg", "daily_average": 5, "monthly_average": 5 } ] ``` {% endtab %} {% tab title="400 The country specified was incorrect" %} ``` ``` {% endtab %} {% tab title="401 Invalid credentials error" %} ```java { "code": 100, "description": "Invalid credentials" } ``` {% endtab %} {% endtabs %} {% hint style="success" %} Please find all the country codes in the [Countries Specifications](/knowledge-base/countries-specifications#details) section. {% endhint %} ## Description The **`payment_methods`** endpoint will show you all the payment methods your account has enabled for the country specified as **query params** in the request. It will also show details about each payment method like the `payment method code`, the `payment method name`, the[`payment method type`](/api-documentation/deposits-api/endpoints/payment-methods-endpoint#payment-types) as well as the `payment method logo` and others. {% hint style="info" %} In case of integrating the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#full-request-streamline) and displaying the payment methods on your cashier, make sure you check the **payment methods** with this API multiple times per day to make sure that in case a new payment method becomes available or unavailable, you will also automatically update it on your cashier without requiring manual intervention from either side. {% endhint %} ## Request In order to start using the payment methods endpoint, you need to: 1. Send the request with **GET** method. 2. Specify a [valid country code](/knowledge-base/countries-specifications#countries-and-currencies) in the request as **QUERY PARAMS**. 3. Send the **Authorization** header with your read-only API Key as Bearer as follows: > Authorization: Bearer *your\_read\_only\_key\_here* ### Example request {% tabs %} {% tab title="cURL" %} ```bash curl --location --request GET 'https://api-stg.onekeypayments.com/v3/payment_methods?country=BR' \ --header 'Authorization: Bearer your_read_only_key_here' ``` {% endtab %} {% tab title="JAVA" %} ```java import java.io.*; import okhttp3.*; public class main { public static void main(String []args) throws IOException{ OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api-stg.directa24.com/v3/payment_methods?country=BR") .method("GET", null) .addHeader("Authorization", "Bearer your_read_only_key_here") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/payment_methods?country=BR"); client.Timeout = -1; var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer your_read_only_key_here"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/payment_methods?country=BR", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Authorization: Bearer your_read_only_key_here" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Example response ```java [ { "country": "BR", "code": "BB", "name": "Banco do Brasil", "type": "BANK_DEPOSIT", "status": "OK", "logo": "https://resources.onekeypayments.com/cashin/payment_method/square/BB.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "BL", "name": "Boleto", "type": "VOUCHER", "status": "OK", "logo": "https://resources.onekeypayments.com/cashin/payment_method/square/BL.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "B", "name": "Bradesco", "type": "BANK_DEPOSIT", "status": "OK", "logo": "https://resources.onekeypayments.com/cashin/payment_method/square/B.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "PP", "name": "Picpay", "type": "VOUCHER", "status": "OK", "logo": "https://resources.onekeypayments.com/cashin/payment_method/square/PP.svg", "daily_average": 5, "monthly_average": 5 }, { "country": "BR", "code": "SB", "name": "Santander", "type": "BANK_TRANSFER", "status": "OK", "logo": "https://resources.onekeypayments.com/cashin/payment_method/square/SB.svg", "daily_average": 5, "monthly_average": 5 } ] ``` ### Response Fields The response will return an object different for each payment method. You should be able to iterate though it no matter how many payment methods are returned. | Field | Format | Description | | ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `country` | String | [Country code](/knowledge-base/countries-specifications#countries-and-currencies) | | `code` | String | Payment method code that should be used when creating a [deposit request](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint) | | `name` | String | Payment method name | | `type` | String | Payment method type. Check the [Payment Types](/api-documentation/deposits-api/payment-methods) section for further details | | `status` | String | Status of the payment method. It will be updated in case a payment methods becomes momentaneously unavailable | | `logo` | String | URL containing the payment method logo | | `daily_average` | Number | Daily average time for the approval of the deposits with this payment method in seconds. \*Note that in case the method is new, we may not have daily average information so this field won't be returned | | `monthly_average` | Number | Monthly average time for the approval of the deposits with this payment method in seconds. \*Note that in case the method is new, we may not have monthly average information so this field won't be returned | {% hint style="warning" %} We may add more fields to this response's object in the future. Please develop your integration considering that it will ignore new fields and continue working fine no matter if we add new fields. {% endhint %} ## Payment types | payment\_type | Description | Icon | | ----------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *`BANK_DEPOSIT`* | Bank deposits | [https://resources.onekeypayments.com/cashin/payment\_method\_type/BANK\_DEPOSIT.png](https://resources.directa24.com/cashin/payment_method_type/BANK_DEPOSIT.png) | | *`BANK_TRANSFER`* | Electronic Funds Transfer (TEF) | [https://resources.onekeypayments.com/cashin/payment\_method\_type/BANK\_TRANSFER.png](https://resources.directa24.com/cashin/payment_method_type/BANK_TRANSFER.png) | | *`CREDIT_CARD`* | Credit and Debit card methods | [https://resources.onekeypayments.com/cashin/payment\_method\_type/CREDIT\_CARD.png](https://resources.directa24.com/cashin/payment_method_type/CREDIT_CARD.png) | | *`VOUCHER`* | Cash solutions | [https://resources.onekeypayments.com/cashin/payment\_method\_type/VOUCHER.png](https://resources.directa24.com/cashin/payment_method_type/VOUCHER.png) | ## Payment Methods Check the Payment Methods page for the full list of payment methods. {% content-ref url="/pages/-M7EyIJfwI7M7iTDXAkL" %} [Payment Methods](/api-documentation/deposits-api/payment-methods) {% endcontent-ref %} # Currency Exchange Endpoint The Currency Exchange endpoint allows you to get the exchange of any local currency compared against USD ## Currency Exchange `GET` `api-stg.onekeypayments.com/v3/exchange_rates?country={country}&amount={amount}` The **`exchange_rates`** endpoint allow you to get the exchange of any currency compared against **USD**. #### Query Parameters | Name | Type | Description | | ------- | ------ | ------------------------------------------------------------------------- | | country | string | Country ISO code in whose local currency the amount will be converted to. | | amount | number | Amount to convert in USD. If none is specified, **`1`** will be assumed. | #### Headers | Name | Type | Description | | ------------- | ------ | ----------------------------- | | Authorization | string | "Bearer " + Read-Only API Key | {% tabs %} {% tab title="200 Currency exchange correctly returned." %} ```java { "fx_rate":5.8829, "currency":"BRL", "converted_amount":58.829 } ``` {% endtab %} {% tab title="400 The country specified was incorrect" %} ``` ``` {% endtab %} {% tab title="401 Invalid credentials error" %} ```java { "code": 100, "description": "Invalid credentials" } ``` {% endtab %} {% endtabs %} {% hint style="success" %} Please find all the country codes in the [Countries Specifications](/knowledge-base/countries-specifications#details) section. {% endhint %} ## Description The **currency exchange** endpoint allows you to check the exchange of any currency against USD. ## Request In order to start using the Currency Exchange endpoint, you need to: 1. Send the request with **GET** method. 2. Specify a [valid country code](/knowledge-base/countries-specifications#countries-and-currencies) in the request as **QUERY PARAMS**. 3. Optionally, you can send the **amount in USD** you want to convert. Otherwise we will return the exchange for USD 1. 4. Send the **Authorization** header with your read-only API Key as Bearer as follows: > Authorization: Bearer *your\_read\_only\_key\_here* ### Example request {% tabs %} {% tab title="cURL" %} ```bash curl --location --request GET 'https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10' \ --header 'Authorization: Bearer your_read_only_key_here' ``` {% endtab %} {% tab title="JAVA" %} ```java import java.io.*; import okhttp3.*; public class main { public static void main(String []args) throws IOException{ OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10") .method("GET", null) .addHeader("Authorization", "Bearer your_read_only_key_here") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10"); client.Timeout = -1; var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer your_read_only_key_here"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/exchange_rates?country=BR&amount=10", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Authorization: Bearer your_read_only_key_here" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Example Response ```java { "fx_rate":5.8829, "currency": "BRL", "converted_amount":58.829 } ``` ### ### Response fields | Field name | Format | Description | | ------------------ | ------ | ----------------------------------------------------------------------------------------------------- | | `fx_rate` | Number | Currency exchange | | `currency` | String | [Currency](/knowledge-base/countries-specifications#countries-and-currencies) used for the conversion | | `converted_amount` | Number | Amount resulting from multiplying the `amount` you sent with the `fx_rate` | # Crypto Exchange Endpoint The Crypto Exchange endpoint allows you to get the exchange of any cryptocurrency compared against USD or any other local currency ## Crypto Exchange Endpoint `GET` `https://api-stg.onekeypayments.com/v3/exchange_rates/crypto?currency={currency}&amount={amount}&crypto={crypto}` The Crypto Exchange endpoint allows you to get the exchange of any crypto currency compared against USD or any other local currency. #### Query Parameters | Name | Type | Description | | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | | currency | string | USD or the country's local currency that will be used by the payer | | amount | number | Amount in the previously specified currency. Used to calculate the exchange in the cryptocurrency specified below. Default: 1 | | crypto | string | Cryptocurrency symbol in which the amount will be converted to | #### Headers | Name | Type | Description | | ------------- | ------ | ----------------------------- | | Authorization | string | "Bearer " + Read-Only API Key | {% tabs %} {% tab title="200 Currency exchange correctly returned." %} ```java { "fx_rate": 5.8829, "converted_amount": 58.829, "fee": 0.64 } ``` {% endtab %} {% tab title="401 Invalid credentials error" %} ```java { "code": 100, "description": "Invalid credentials" } ``` {% endtab %} {% endtabs %} {% hint style="success" %} Please find all the country and currencies codes in the [Countries Specifications](/knowledge-base/countries-specifications#details) section. {% endhint %} ## Description The **Crypto Exchange Endpoint** allows you to convert any amount in USD or Local Currency to the specified Cryptocurrency. ## Request In order to start using the Crypto Exchange endpoint, you need to: 1. Send the request with **GET** method. 2. Specify a [valid currency code](/knowledge-base/countries-specifications#countries-and-currencies) in the request as **QUERY PARAMS**. 3. Specify the amount to convert.\* If it's not specified, 1 is assumed. 4. Specify a valid cryptocurrency symbol that will be converted the amount to. 5. Send the **Authorization** header with your read-only API Key as Bearer as follows: > Authorization: Bearer *your\_read\_only\_key\_here* ### Example request {% tabs %} {% tab title="cURL" %} ```bash curl --location --request GET 'https://api-stg.onekeypayments.com/v3/exchange_rates/crypto?currency=BRL&crypto=USDT' \ --header 'Authorization: Bearer your_read_only_key_here' ``` {% endtab %} {% tab title="JAVA" %} ```java import java.io.*; import okhttp3.*; public class main { public static void main(String []args) throws IOException{ OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api-stg.onekeypayments.com/v3/exchange_rates/crypto?currency=BRL&amount=1000&crypto=USDT") .method("GET", null) .addHeader("Authorization", "Bearer your_read_only_key_here") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/exchange_rates/crypto?currency=BRL&amount=1000&crypto=USDT"); client.Timeout = -1; var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer your_read_only_key_here"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/exchange_rates/crypto?currency=BRL&amount=1000&crypto=USDT", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Authorization: Bearer your_read_only_key_here" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Example Response ```java { "fx_rate": 5.8829, "converted_amount": 58.829, "fee": 0.64 } ``` ### ### Response fields | Field name | Format | Description | | ------------------ | ------ | -------------------------------------------------------------- | | `fx_rate` | Number | Exchange rate of the cryptocurrency against the base currency | | `converted_amount` | Number | Amount in the cryptocurrency specified. Default: 1 | | `fee` | Number | Fee for converting the specified amount to the cryptocurrency. | # Country States Codes Endpoint Learn how to use the Country States Codes Endpoint to retrieve the list of States ISO codes in each country ## Country States Codes Endpoint `GET` `https://api-stg.onekeypayments.com/v3/states?country={ISO_CODE}` This API allows you to retrieve the list of ISO codes and the names of the states available in each country, allowing you to dynamically retrieve those on your front-end. #### Query Parameters | Name | Type | Description | | ------- | ------ | ---------------- | | country | string | Country ISO code | #### Headers | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------ | | Authorization | string | Authorization Header. Format: "Bearer your\_read\_only\_key" | {% tabs %} {% tab title="200 Bank list successfully retrieved" %} ```java [ { "iso": "AC", "name": "Acre" }, { "iso": "AL", "name": "Alagoas" }, { "iso": "AM", "name": "Amazonas" }, { "iso": "AP", "name": "Amapá" }, { "iso": "BA", "name": "Bahia" }, { "iso": "CE", "name": "Ceará" }, { "iso": "DF", "name": "Distrito Federal" }, { "iso": "ES", "name": "Espírito Santo" }, { "iso": "GO", "name": "Goiás" }, { "iso": "MA", "name": "Maranhão" }, { "iso": "MG", "name": "Minas Gerais" }, { "iso": "MS", "name": "Mato Grosso do Sul" }, { "iso": "MT", "name": "Mato Grosso" }, { "iso": "PA", "name": "Pará" }, { "iso": "PB", "name": "Paraíba" }, { "iso": "PE", "name": "Pernambuco" }, { "iso": "PI", "name": "Piauí" }, { "iso": "PR", "name": "Paraná" }, { "iso": "RJ", "name": "Rio de Janeiro" }, { "iso": "RN", "name": "Rio Grande do Norte" }, { "iso": "RO", "name": "Rondônia" }, { "iso": "RR", "name": "Roraima" }, { "iso": "RS", "name": "Rio Grande do Sul" }, { "iso": "SC", "name": "Santa Catarina" }, { "iso": "SE", "name": "Sergipe" }, { "iso": "SP", "name": "São Paulo" }, { "iso": "TO", "name": "Tocantins" } ] ``` {% endtab %} {% tab title="401 Invalid credentials error" %} ```java { "code": 100, "description": "Invalid credentials", "type": "INVALID_CREDENTIALS" } ``` {% endtab %} {% endtabs %} ## Introduction This endpoint is used to retrieve and display to your customer the list of States available on their country. In case we add or remove a State, this endpoint will reflect those updates real-time and, therefore, it is a good idea to constantly check this endpoint for the list of banks. Once the user selected their State by its name (For example on a dropdown), you need to send its code to us in the `payer.address.state` field of the deposits requests. The endpoint is read only and so it uses a read only API Key. It can even be used from the front-end without major security concerns. ## Bank Codes Request ### Request Example ```java // URL GET: https://api-stg.onekeypayments.com/v3/states?country=BR // HEADERS Authorization: Bearer EKiFOWiHnI ``` ### Request Fields | Type | Field | Format | Description | | ----------- | --------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | | Query Param | `country` | String (length: 2) | [Country ISO code](/knowledge-base/countries-specifications#countries-and-currencies) | | Header | `Authorization` | String | Bearer Token Authentication. It is a concatenation of the word "Bearer " and your Read Only API Key. | ## Bank Codes Response ### Response Example {% tabs %} {% tab title="Brazil" %} ```java [ { "iso": "AC", "name": "Acre" }, { "iso": "AL", "name": "Alagoas" }, { "iso": "AM", "name": "Amazonas" }, { "iso": "AP", "name": "Amapá" }, { "iso": "BA", "name": "Bahia" }, { "iso": "CE", "name": "Ceará" }, { "iso": "DF", "name": "Distrito Federal" }, { "iso": "ES", "name": "Espírito Santo" }, { "iso": "GO", "name": "Goiás" }, { "iso": "MA", "name": "Maranhão" }, { "iso": "MG", "name": "Minas Gerais" }, { "iso": "MS", "name": "Mato Grosso do Sul" }, { "iso": "MT", "name": "Mato Grosso" }, { "iso": "PA", "name": "Pará" }, { "iso": "PB", "name": "Paraíba" }, { "iso": "PE", "name": "Pernambuco" }, { "iso": "PI", "name": "Piauí" }, { "iso": "PR", "name": "Paraná" }, { "iso": "RJ", "name": "Rio de Janeiro" }, { "iso": "RN", "name": "Rio Grande do Norte" }, { "iso": "RO", "name": "Rondônia" }, { "iso": "RR", "name": "Roraima" }, { "iso": "RS", "name": "Rio Grande do Sul" }, { "iso": "SC", "name": "Santa Catarina" }, { "iso": "SE", "name": "Sergipe" }, { "iso": "SP", "name": "São Paulo" }, { "iso": "TO", "name": "Tocantins" } ] ``` {% endtab %} {% tab title="Colombia" %} ```java [ { "iso": "AMA", "name": "Amazonas" }, { "iso": "ANT", "name": "Antioquia" }, { "iso": "ARA", "name": "Arauca" }, { "iso": "ATL", "name": "Atlántico" }, { "iso": "BOL", "name": "Bolívar" }, { "iso": "BOY", "name": "Boyacá" }, { "iso": "CAL", "name": "Caldas" }, { "iso": "CAQ", "name": "Caquetá" }, { "iso": "CAS", "name": "Casanare" }, { "iso": "CAU", "name": "Cauca" }, { "iso": "CES", "name": "Cesar" }, { "iso": "CHO", "name": "Chocó" }, { "iso": "COR", "name": "Córdoba" }, { "iso": "CUN", "name": "Cundinamarca" }, { "iso": "GUA", "name": "Guainía" }, { "iso": "GUV", "name": "Guaviare" }, { "iso": "HUI", "name": "Huila" }, { "iso": "LAG", "name": "La Guajira" }, { "iso": "MAG", "name": "Magdalena" }, { "iso": "MET", "name": "Meta" }, { "iso": "NAR", "name": "Nariño" }, { "iso": "NSA", "name": "Norte de Santander" }, { "iso": "PUT", "name": "Putumayo" }, { "iso": "QUI", "name": "Quindío" }, { "iso": "RIS", "name": "Risaralda" }, { "iso": "SAN", "name": "Santander" }, { "iso": "SAP", "name": "San Andrés y Providencia" }, { "iso": "SUC", "name": "Sucre" }, { "iso": "TOL", "name": "Tolima" }, { "iso": "VAC", "name": "Valle del Cauca" }, { "iso": "VAU", "name": "Vaupés" }, { "iso": "VID", "name": "Vichada" } ] ``` {% endtab %} {% endtabs %} ### **Response fields** | Field | Format | Description | | ------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iso` | String (length between 1 and 3) | State code in [*ISO 3166-2* format](https://en.wikipedia.org/wiki/ISO_3166-2). It is the value you must send in the `payer.address.state` field of the [Deposits requests](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#payer-address-object) | | `name` | String | Name of the State | # Refund Creation Endpoint Create refunds requests from a completed deposit ## Refund Creation `POST` `https://api-stg.onekeypayments.com/v3/refunds` This endpoint allows you to create a full or a partial refund over a completed deposit. #### 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 | | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ | | deposit\_id | integer | Directa24 `deposit_id`. It is obtained when creating the deposit | | invoice\_id | string | The `invoice_id` you sent while creating the deposit or the `merchant_invoice_id` auto-generated by us | | amount | number | Amount to refund. If none is sent, the full deposit amount is assumed | | bank\_account | object | Object containing the information of the beneficiary. Not needed for credit cards | | comments | string | Commentaries about the refund, if any | | notification\_url | string | HTTPS URL used to send the notifications about refund's change of status | {% tabs %} {% tab title="200 Refund created successfully" %} ```java { "refund_id": 168284 } ``` {% endtab %} {% tab title="400 Error in the request" %} ```java { "code": 802, "description": "Amount to refund not valid", "type": "INVALID_AMOUNT_TO_REFUND" } ``` {% endtab %} {% tab title="404 Deposit not found" %} ```java { "code": 208, "description": "Resource not found", "type": "RESOURCE_NOT_FOUND" } ``` {% endtab %} {% endtabs %} ## Description The **`refunds`** endpoint allows you to create a **full r**efund over a Credit Card deposit in **completed** state or **full/partial** refunds over other payment methods' deposits in **completed** state. In the case of credit cards, since the refund will be processed to the same card, all you need to send are the fields to identify the deposit. In the case of other payment methods where we don't have the account of the payer, you need to send the beneficiary's ID, bank account details and bank code retrieved with the[ Endpoint for Bank Codes.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) You can create as many refunds as needed over a completed deposit, as long as the total amount of those refunds doesn't exceed the original amount deposited. ## Refunds Request In order to start creating refunds, you need to: 1. Send the request with **POST** method. 2. Use the headers described [here](/api-documentation/deposits-api/technical-and-security-aspects#headers). 3. Specify a valid `deposit_id` and `invoice_id` related to the deposit to be refunded. 4. Send the Authorization header calculated in the same way than for deposits, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature). 5. Send the body of the request as JSON. ## Example Request {% tabs %} {% tab title="cURL" %} ```java // CASH Method: curl --location --request POST 'https://api-stg.onekeypayments.com/v3/refunds' \ --header 'X-Login: {{X-Login}}' \ --header 'X-Date: {{X-Date}}' \ --header 'Authorization: {{Authorization}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "deposit_id": 300533646, "invoice_id": "newIUnit45328731", "amount": "100", "bank_account": { "beneficiary": "Carlos Ramirez", "bank_code": 1, "branch": "9283", "account_number": "18293435", "account_type": "SAVING" }, "comments": "Test refund over v3", "notification_url": "https://webhook.site/url" }' // CREDIT CARD method: curl --location --request POST 'https://api-stg.directa24.com/v3/refunds' \ --header 'X-Login: {{X-Login}}' \ --header 'X-Date: {{X-Date}}' \ --header 'Authorization: {{Authorization}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "deposit_id": 300533647, "invoice_id": "newIUnit45328732", "comments": "Test CREDIT CARD refund over v3", "notification_url": "https://webhook.site/url" }' ``` {% endtab %} {% tab title="JAVA" %} ```java 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 \"deposit_id\": 300533646,\n \"invoice_id\": \"newIUnit45328731\",\n \"amount\": \"100\",\n \"bank_account\": {\n \"beneficiary\": \"Carlos Ramirez\",\n \"bank_code\": 1,\n \"branch\": \"9283\",\n \"account_number\": \"18293435\",\n \"account_type\": \"SAVING\"\n },\n \"comments\": \"Test refund over v3\",\n \"notification_url\": \"https://webhook.site/url\"\n}"); Request request = new Request.Builder() .url("https://api-stg.onekeypayments.com/v3/refunds") .method("POST", body) .addHeader("X-Login", "{{X-Login}}") .addHeader("X-Date", "{{X-Date}}") .addHeader("Authorization", "{{Authorization}}") .addHeader("Content-Type", "application/json") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/refunds"); 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("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"deposit_id\": 300533646,\n \"invoice_id\": \"newIUnit45328731\",\n \"amount\": \"100\",\n \"bank_account\": {\n \"beneficiary\": \"Carlos Ramirez\",\n \"bank_code\": 1,\n \"branch\": \"9283\",\n \"account_number\": \"18293435\",\n \"account_type\": \"SAVING\"\n },\n \"comments\": \"Test refund over v3\",\n \"notification_url\": \"https://webhook.site/url\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/refunds", 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 \"deposit_id\": 300533646,\n \"invoice_id\": \"newIUnit45328731\",\n \"amount\": \"100\",\n \"bank_account\": {\n \"beneficiary\": \"Carlos Ramirez\",\n \"bank_code\": 1,\n \"branch\": \"9283\",\n \"account_number\": \"18293435\",\n \"account_type\": \"SAVING\"\n },\n \"comments\": \"Test refund over v3\",\n \"notification_url\": \"https://webhook.site/url\"\n}", CURLOPT_HTTPHEADER => array( "X-Login: {{X-Login}}", "X-Date: {{X-Date}}", "Authorization: {{Authorization}}", "Content-Type: application/json" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ### Request fields description
FieldFormatDescriptionValidations
FieldFormatDescriptionValidations
deposit_idIntegerOKP deposit_id. It is obtained when creating the depositValid deposit_id of a completed deposit
invoice_idString (max length: 128)The invoice_id you sent while creating the deposit or the merchant_invoice_id auto-generated by usValid invoice_id of a completed deposit
amountBig decimal (positive, up to 2 decimals)Amount to refund. Only used in case of partial refunds. If none is sent, a full refund will be assumedPositive. Equal or smaller than the deposit amount
bank_account[]Object[]Object containing the details where the refund should be sent to
commentsString (max length: 200)Commentaries about the refund, if anyString of up to 200 characters
notification_urlString (max length: 2048)Valid HTTPS URL used to send the notifications about refund's change of statusHTTPS URL
### `bank_account` Object | Field name | Format | Description | Validations | | ---------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------: | | `beneficiary` | string (max length: 255) | Beneficiary's name and last name | String of up to 255 characters | | `document_type` | string (max length: 10) | Beneficiary's document type |

Valid document type for the country of the deposit.

See validations here

| | `document` | string (max length: 30) | Beneficiary's document ID |

Valid document for the country of the deposit.

See validations here

| | `bank_code` | string (max length: 5) | Beneficiary's valid `bank_code` for the country. Use the [Bank Codes Endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | [Bank Codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | | `branch` | string (max length: 45) | Beneficiary's bank branch | String of up to 45 characters | | `account_number` | string (max length: 45) | Beneficiary's bank account number | String of up to 45 characters | | `account_type` | string (max length: 45) | Beneficiary's account type | [List of account\_type](/api-documentation/cashouts-api/countries-validations#account-types) | #### Account types
account_typeDescription
account_typeDescription
SAVINGSavings account
CHECKINGCheckings account
VISTASalary account
MASTERMaster account
SAVING_SETJoint savings account
CHECKING_SETJoint checkings
DEFAULTDefault
## Example Response ### CASH Success Response Example ```java { "refund_id": 168284 } ``` ### CASH Success Response Fields | Field | Format | Description | | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `refund_id` | Integer | ID of the refund on OKP end. Store this ID for future [checks of its status](/api-documentation/deposits-api/endpoints/refund-status-endpoint) | ### CREDIT CARD Responses Example {% tabs %} {% tab title="SUCCESS" %} ```java { "refund_id": "80000001", "deposit_id": 300604089, "merchant_invoice_id": "test766106146", "refund_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" } } ``` {% endtab %} {% tab title="IN PROGRESS" %} ```java { "refund_id": "80000001", "deposit_id": 300604089, "merchant_invoice_id": "test766106146", "refund_info": { "type": "CREDIT_CARD", "result": "IN_PROGRESS", "reason": "Check refund status or await its notification", "payment_method": "AE", "payment_method_name": "American Express", "amount": 505.95, "currency": "MXN", "created_at": "2021-02-05 22:10:45" } } ``` {% endtab %} {% tab title="REJECTED" %} ```java { "refund_id": "80000001", "deposit_id": 300604089, "merchant_invoice_id": "test766106146", "refund_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" } } ``` {% endtab %} {% endtabs %} When the refund is made over a CREDIT CARD deposit, it might be (depending upon availability) completed instantaneously, and so all the details of the refund are returned. In case the result is SUCCESS, it means the refund was successfully created and the user should receive the money back into their card soon. In case the result is REJECTED, the response of the API will return two fields called `reason` and `reason_code` providing more information about the rejection reason. In case the result is IN\_PROGRESS, it means the refund will be processed asynchronously and so a notification will be sent to the `notification_url` specified at the time of creating the refund as soon as it gets completed or rejected. [Click here](/api-documentation/deposits-api/endpoints/refund-creation-endpoint/notifications) for more information about the notifications of the refunds. ### Error Responses Example ```java // Invalid amount to refund. The amount is bigger than the deposit or // it has been already refunded { "code": 802, "description": "Amount to refund not valid", "type": "INVALID_AMOUNT_TO_REFUND" } // The object_bank account needs to be sent { "code": 804, "description": "Missing bank account information", "type": "MISSING_BANK_ACCOUNT" } // The deposit_id and/or the merchant_invoice_id didn't belong to a deposit { "code": 208, "description": "Resource not found", "type": "RESOURCE_NOT_FOUND" } ``` ### Error Responses Fields | Field | Format | Description | | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Integer | Error code. [Click here to check all the possible error codes for refund](/api-documentation/deposits-api/api-codes#refund-error-codes) | | `description` | String | Description of the error | | `type` | String | Type of the error. [Click here to check all the possible error types for refund](/api-documentation/deposits-api/api-codes#refund-error-codes) | � # Notifications Learn about how the notifications for refunds works ## Refunds status notifications Every time a refund changes its status, we will send you an asynchronous notification to the `notification_url` you sent in the refund request or the one you have configured under the section "Settings -> API Access" of our Merchant Panel containing the ID of the refund. **Once received the notification, you should check its new status with the**[ ](/api-documentation/deposits-api/endpoints/deposit-status-endpoint)[**Refund Status Endpoint**](/api-documentation/deposits-api/endpoints/refund-status-endpoint) **and update it on your end accordingly.** {% hint style="info" %} Bear in mind we will only connect through ports 80 and 443. Make sure your `notification_url` has one of those ports open accepting connections from us. {% endhint %} ## Notifications fields | Field | Format | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `refund_id` | Number | ID of the refund. Use this ID to [check the status of the refund.](/api-documentation/deposits-api/endpoints/refund-status-endpoint) | ## Notifications example ```java { "refund_id": 168284 } ``` ## Retry logic Every time a refund changes its status, we will send you a notification so you can [check its status](/api-documentation/deposits-api/endpoints/refund-status-endpoint) back. In case that for some reason your server was unable to receive the notification and you returned an HTTP code different than 200, we will retry the notification up to 5 more times or until you respond with HTTP 200, whatever comes first. The time between each of the 5 notifications attempts will be exponential: 5, 25, 125 and 625 minutes accordingly. When the notifications fails to be sent, it will be shown like this in our Merchant Panel: ![](/files/-M9_UqvQBGblaqYL1-oD) If you see the errors from the screenshot above, it means the refund was successfully completed and the money reached the customer's account/card but suddenly we couldn't notify you. Keep reading to know how to resend the notifications. ## Resend Notifications In case your system was unable to receive the notification in any of the 5 attempts, you can always check its status with the [Refund Status Endpoint.](/api-documentation/deposits-api/endpoints/refund-status-endpoint) If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the refund and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent. {% hint style="success" %} It can take up to 1 minute for the notification to be resent in PROD and 3 on STG. {% endhint %} ![](/files/-M9zU27QNwGCCPG-JJEq) # Refund Status Endpoint Retrieve the status of a previously created refund ## Refund Status `GET` `https://api-stg.onekeypayments.com/v3/refunds/{refund_id}` This endpoint allows you to retrieve the status of a refund request. #### Path Parameters | Name | Type | Description | | ---------- | ------- | ------------------------------------------------------------- | | refund\_id | integer | Directa24 refund\_id. It is obtained when creating the refund | #### Headers | Name | Type | Description | | ------------- | ------ | -------------------------------------------------------- | | X-Date | string | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` | | X-Login | string | Merchant X-Login API Key | | Authorization | string | Authentication signature hash | {% tabs %} {% tab title="200 Refund status successfully retrieved." %} ```java { "deposit_id": 300533646, "merchant_invoice_id": "newIUnit45328731", "status": "PENDING" } ``` {% endtab %} {% tab title="404 The refund with the refund\_id specified could not be found." %} ```java { "code": 208, "description": "Resource not found", "type": "RESOURCE_NOT_FOUND" } ``` {% endtab %} {% endtabs %} ## Description You can trigger the check of the status of a refund at any moment you consider pertinent. However, every time a refund changes its status, we will send you a [notification](/api-documentation/deposits-api/endpoints/refund-creation-endpoint/notifications) containing the ID of the refund so that you can check its status back to retrieve the new refund's status. ## Refunds Status Request In order to check the status of the refunds, you need to: 1. Send the request with **GET** method. 2. Use the headers described [here](/api-documentation/deposits-api/technical-and-security-aspects#headers). 3. Specify a valid `refund_id` in the URL of the request as PATH PARAMETERS. 4. Send the Authorization header, as [explained here](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature). Regarding the Authorization value, since the body of the requests will be empty, you should use an empty ("") string or nothing as the `jsonPayload` field. {% tabs %} {% tab title="cURL" %} ```bash curl --location --request GET 'https://api-stg.onekeypayments.com/v3/refunds/1682844' \ --header 'X-Login: {{X-Login}}' \ --header 'X-Date: {{X-Date}}' \ --header 'Authorization: {{Authorization}}' \ --header 'Content-Type: application/json' \ --data-raw '' ``` {% endtab %} {% tab title="JAVA" %} ```java import java.io.*; import okhttp3.*; public class main { public static void main(String []args) throws IOException{ OkHttpClient client = new OkHttpClient().newBuilder() .build(); Request request = new Request.Builder() .url("https://api-stg.onekeypayments.com/v3/refunds/1682844") .method("GET", null) .addHeader("X-Login", "{{X-Login}}") .addHeader("X-Date", "{{X-Date}}") .addHeader("Authorization", "{{Authorization}}") .addHeader("Content-Type", "application/json") .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); } } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using RestSharp; namespace HelloWorldApplication { class HelloWorld { static void Main(string[] args) { var client = new RestClient("https://api-stg.onekeypayments.com/v3/refunds/1682844"); client.Timeout = -1; var request = new RestRequest(Method.GET); request.AddHeader("X-Login", "{{X-Login}}"); request.AddHeader("X-Date", "{{X-Date}}"); request.AddHeader("Authorization", "{{Authorization}}"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "", ParameterType.RequestBody); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); } } } ``` {% endtab %} {% tab title="PHP" %} ```php "https://api-stg.onekeypayments.com/v3/refunds/1682844", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "X-Login: {{X-Login}}", "X-Date: {{X-Date}}", "Authorization: {{Authorization}}", "Content-Type: application/json" ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` {% endtab %} {% endtabs %} ## Example response {% tabs %} {% tab title="COMPLETED" %} ```java { "deposit_id": 300533569, "merchant_invoice_id": "84044", "status": "COMPLETED", "amount": 100.00 } ``` {% endtab %} {% tab title="PENDING" %} ```java { "deposit_id": 300502126, "merchant_invoice_id": "84121", "status": "PENDING" } ``` {% endtab %} {% endtabs %} ### Response fields | Field name | Format | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `deposit_id` | Integer | ID of the deposit refunded | | `merchant_invoice_id` | String | Merchant invoice id of the deposit refunded | | `status` | Enum | Status of the refund. [Click here for the full list of refund codes.](/api-documentation/deposits-api/api-codes#refunds-status-codes) | | `amount` | Number | Amount of the refund | {% hint style="warning" %} In order to make the experience more personalized, we may add more fields to this response's object in the future. Please develop your integration to be able to ignore new fields considering that it will continue working fine no matter if we add new fields. {% endhint %} ## Status Flow [Click here](/api-documentation/deposits-api/api-codes#refunds-status-codes) to see each Refund Status meaning. ### Refund Status Flow ![](/files/-ME_j2yrI--6DukQU-9L) {% hint style="info" %} 1. DECLINED is not a status by itself. It means the refund failed to be created. 2. As soon as the refund request is created, its status will be PENDING. 3. In case we need more information to complete the request or any of the details were incorrect, we will change the status to INCORRECT\_DETAILS and you will need to provide the correct details. Once the details have been provided, its status will be PENDING again. 4. The status CANCELLED means the refund was manually cancelled by you. Only refunds in PENDING or INCORRECT\_DETAILS can be cancelled. Final status. 5. If everything is fine we will send the refund for processing and the status will be marked as DELIVERED. It can't be cancelled at this point. 6. As soon as the processor/bank confirms the refund, it will be marked as COMPLETED or REJECTED (by the bank). 7. There are some **corner cases** in which the receiver's bank tell us that the refund was completed but days after it gets rejected. In those cases the status changes from COMPLETED to REJECTED. {% endhint %} ## Status codes Check all the possible status in the following page: {% content-ref url="/pages/-M8MAwZ0r4Szs2f\_lbbI" %} [API Codes](/api-documentation/deposits-api/api-codes) {% endcontent-ref %} # Payment Methods Learn about our Payment Methods ## Payment Methods {% content-ref url="/pages/-M7EywIJjqpFs68bKk5l" %} [America](/api-documentation/deposits-api/payment-methods/america) {% endcontent-ref %} {% content-ref url="/pages/-M7EzpcNUPkNApVJ8G46" %} [Broken mention](broken://pages/-M7EzpcNUPkNApVJ8G46) {% endcontent-ref %} {% content-ref url="/pages/-M7Ey\_UxoSGYAezpzpst" %} [Broken mention](broken://pages/-M7Ey_UxoSGYAezpzpst) {% endcontent-ref %} {% hint style="info" %} Check with your commercial representative regarding other countries and payment methods not in these lists. {% endhint %} You can retrieve the payment methods your account has enabled by using the [Payment Methods endpoint.](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) On the Merchant Panel you can check what Payment Methods your account has enabled by going to the "Payment Methods" section on the left menu. The Payment Method availability is real time updated on the panel.

Payment Methods Grid

### Considerations 1. Notice that not every payment method is available in Staging. Check on each country's table the available ones. 2. Some methods may not be available within an iframe due to our processor's security requirements. Check on each country's table the available ones. In those cases, we will ask the customer to open the payment page on a new window. 3. The checkouts may differ between STG and PROD in the cases we use different providers. ## Flows Some payment methods allows you to display the payment information directly on your website, without having to redirect the customer to an external website. Those methods are so called "ONE\_SHOT" and are part of our [OneShot Experience: OneShot](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience-response-oneshot). When creating a payment of this kind, we will return you all the fields you need to display to your customer on a [metadata object](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#response-fields-1) and a URL to redirect the customer in case the payment requires so. In case the flow is "REDIRECT", we will generate a link so that you can redirect the customer to the page where they will insert any missing details and see the payment instructions. | Flow | Description | | :--------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ONE_SHOT` | In the `ONE_SHOT` flow, you will receive all the details needed to build a payment page on your own website. For example, the Boleto's number, barcode, expiration, amount, payment link, etc. | | `REDIRECT` | In the `REDIRECT` flow, we will respond you with a link you should use to redirect your customers so they can pay. | {% hint style="warning" %} The `ONE_SHOT` and `REDIRECT` flows depends upon provider's availability. In order for us to provide you with the most efficient service, we may switch between service providers who doesn't support `ONE_SHOT`flows, hence your cashier should be able to adapt to both scenarios. {% endhint %} # America Check the list of Payment Methods available on each American country # Bolivia Check the list of Payment Methods available on Bolivia ## Payment Methods | Icon | payment\_method | Name | Flows | Payment Type | Available for test | Iframe supported | | :------------------------------------------------------------------------------------------------------: | :-------------: | ---------- | :--------: | :----------: | :----------------: | :--------------: | | | `RPD` | RapidPagos | `REDIRECT` | VOUCHER | Yes | Yes | | | PFB | Pago Facil | `REDIRECT` | VOUCHER | Yes | Yes | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' **types**, **logos** and **more** details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | address\[] | phone | | ------------------- | :------: | :---: | :---------: | :--------: | :--------: | :---: | | All | Yes | Yes | Yes | Yes | No | No | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Brazil Check the list of Payment Methods available on Brazil *Effective December 23, the payment method Boleto is no longer available due to updated Brazilian regulations set to take effect on January 1, 2025. We apologize for any inconvenience and appreciate your understanding.* ## Payment Methods | Icon | payment\_method | Name | Flows | Payment Type | Available for test | Iframe supported | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | --------------- | :-------------------------------------------------------: | :------------: | :----------------: | :--------------: | | [](https://resources.directa24.com/cashin/payment_method/square/IX.svg) | `IX` | Pix |

REDIRECT

ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/PP.svg) | `PP` | PicPay |

REDIRECT

ONE\_SHOT

| VOUCHER | | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/BB.svg) | `BB` | Banco do Brasil |

REDIRECT

ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/CA.svg) | `CA` | Caixa |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/I.svg) | `I` | Itaú |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/B.svg) | `B` | Bradesco |

REDIRECT

ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/SB.svg) | `SB` | Santander |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/BZ.svg) | `BZ` | Banco Original |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | Yes | Yes | | | `SF` | Banco Safra |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/UL.svg) | `UL` | Banrisul |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/LC.svg) | `LC` | Loterias Caixa |

REDIRECT

ONE\_SHOT

| VOUCHER | Yes | Yes | | | `VI` | Visa |

REDIRECT
PCI

| CREDIT\_CARD | Yes | Yes | | | `MC` | Mastercard |

REDIRECT
PCI

| CREDIT\_CARD | Yes | Yes | | | `EL` | Elo |

REDIRECT
PCI

| CREDIT\_CARD | Yes | Yes | | | `NU` | Nubank |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | | `ME` | MercadoPago |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | | `C6` | C6 Bank |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | | `INT` | Banco Inter |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | | `PAG` | PagBank |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | | `OIX` | Pix OpenFinance |

REDIRECT
ONE\_SHOT

| BANK\_TRANSFER | Yes | Yes | | | `IXB` | Pix Biometric | `REDIRECT` | BANK\_TRANSFER | No | Yes | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' **types**, **logos** and **more** details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | address\[] | phone | | ------------------- | :------: | :---: | :---------: | :--------: | :--------: | :---: | | Boleto | Yes | Yes | Yes | Yes | Yes | No | | Banco do Brasil | Yes | Yes | Yes | Yes | Yes | No | | Itaú | Yes | Yes | Yes | Yes | Yes | No | | PicPay | Yes | Yes | Yes | Yes | No | Yes | | All | Yes | Yes | Yes | Yes | No | No | ### ### Address object requirements
Payment Method NameRequired for deposits abovestreetcitystatezip_code
BoletoUSD 3000YesYesYesYes
Banco do BrasilUSD 200YesYesYesYes
ItaúUSD 200YesYesYesYes
{% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # PIX Biometric Our groundbreaking solution that enables easier and faster Pix payments, boosting conversion rates and eliminating friction in the checkout process. No manual steps. Just verify and pay. *** ### Learn How the Flow Works: The diagram below illustrates the complete bank registration and payment process.

PIX Biometric Flow

* The user selects Biometric PIX as the payment method. * You submit the enrollment and payment details by simply setting the `payment_method` parameter to `IXB`. * The user is redirected to the provided URL. * One-time registration with their banking institution: * The user registers with the institution. * The institution requests biometric validation for confirmation. * The user validates their biometrics, and the institution stores the data for future payments. * After registration, the user is redirected back to your application to complete the payment. * The payment is authenticated via biometrics, and the user is redirected back to your application.\ \ *That's it! The entire enrollment and payment process requires just one POST call to our API - our PIX Biometric solution takes care of the rest.* *** ### Experience the Full Flow! 🚀 {% hint style="info" %} Try It Out! \ \ 👉 Click the expand symbol at the top right of the demo to enlarge the screen, then interact to simulate a real user experience and explore the full flow. {% endhint %} {% embed url="" %} ### One-Time Bank Registration: Step-by-Step UX Flow:
### Standard Post-Registration: Step-by-Step UX Flow
*** ### PIX Biometric Payment Method Information | Icon | payment\_method | Name | Flows | Payment Type | Available for test | Iframe supported | | :-------------------------------------------------------------: | :-------------: | ------------- | :--------: | :------------: | :----------------: | :--------------: | | | `IXB` | Pix Biometric | `REDIRECT` | BANK\_TRANSFER | No | Yes | {% hint style="warning" %} Pix Biometric does not work using a native checkout (iFrame) you must re-direct the customers to a new window/tab.\ \ Biometric is currently only available for mobile devices. {% endhint %} # Chile Check the list of Payment Methods available on Chile ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------------- | :----------------------------------------------: | :------------: | | | `VI` | VISA |

REDIRECT
PCI

| `CREDIT_CARD` | | | `MC` | Mastercard |

REDIRECT
PCI

| `CREDIT_CARD` | | [](https://resources.directa24.com/cashin/payment_method/square/WP.svg) | `WP` | WebPay | `REDIRECT` | `CREDIT_CARD` | | [](https://resources.directa24.com/cashin/payment_method/square/BE.svg) | `BE` | Banco Estado | `REDIRECT` | `BANK_DEPOSIT` | | [](https://resources.directa24.com/cashin/payment_method/square/BX.svg) | `BX` | Banco de Chile | `REDIRECT` | `BANK_DEPOSIT` | | [](https://resources.directa24.com/cashin/payment_method/square/CI.svg) | `CI` | Banco BCI | `REDIRECT` | `BANK_DEPOSIT` | | [](https://resources.directa24.com/cashin/payment_method/square/LE.svg) | `LE` | Banco CrediChile | `REDIRECT` | `BANK_DEPOSIT` | | [](https://resources.directa24.com/cashin/payment_method/square/LL.svg) | `LL` | Banco Falabella | `REDIRECT` | `BANK_DEPOSIT` | | [](https://resources.directa24.com/cashin/payment_method/square/IA.svg) | `IA` | Itaú | `REDIRECT` | `BANK_DEPOSIT` | | [](https://resources.directa24.com/cashin/payment_method/square/SC.svg) | `SC` | Banco Santander | `REDIRECT` | `BANK_DEPOSIT` | | | `MAC` | Mach | `REDIRECT` | `WALLET` | | | `ST` | Scotiabank | `REDIRECT` | `BANK_DEPOSIT` | | | `TAPP` | Tapp | `REDIRECT` | `WALLET` | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Canada Check the list of Payment Methods available on Canada ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | Available for test | Iframe supported | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ----------------- | :--------: | :------------: | :----------------: | :--------------: | | [](https://resources.directa24.com/cashin/payment_method/square/IF.svg) | `IF` | Interac Etransfer | `REDIRECT` | VOUCHER | | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/IR.svg) | `IR` | Interac Online | `REDIRECT` | BANK\_TRANSFER | | Yes | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Colombia Check the list of Payment Methods available on Colombia ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------------- | :----------------------------------------------------: | :------------: | | | `ME` | MercadoPago | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/VI.svg) | `VI` | VISA |

REDIRECT
PCI

| CREDIT\_CARD | | [](https://resources.directa24.com/cashin/payment_method/square/MC.svg) | `MC` | MasterCard |

REDIRECT
PCI

| CREDIT\_CARD | | [](https://resources.directa24.com/cashin/payment_method/square/AE.svg) | `AE` | American Express |

REDIRECT
PCI

| CREDIT\_CARD | | [](https://resources.directa24.com/cashin/payment_method/square/EY.svg) | `EY` | Efecty |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/PC.svg) | `PC` | PSE |

REDIRECT
ONE\_SHOT

| BANK\_DEPOSIT | | [](https://resources.directa24.com/cashin/payment_method/square/JE.svg) | `JE` | JER | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/CX.svg) | `CX` | Su Chance |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/XU.svg) | `XU` | Con Suerte |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/XC.svg) | `XC` | Coopenessa |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/DQ.svg) | `DQ` | Edeq |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/DX.svg) | `DX` | Dimonex |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/FG.svg) | `FG` | FullCarga |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/MR.svg) | `MR` | Moviired |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `SR` | Su Suerte |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `SZ` | Surti Mayorista |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `RD` | Su Red | `REDIRECT` | VOUCHER | | | `BREB` | Breb | `REDIRECT` | BANK\_TRANSFER | | | `NQ` | Nequi | `REDIRECT` | BANK\_DEPOSIT | | | `TRYA` | TransfiYa | `REDIRECT` | VOUCHER | | | `TP` | TPaga | `REDIRECT` | WALLET | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | address\[] | phone | | ------------------- | :------: | :---: | :---------: | :--------: | :--------: | :---: | | All | Yes | Yes | Yes | Yes | No | No | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} ### Pagos Seguros en Linea (PSE) One shot flow The PSE direct One shot flow send the customer directly to the checkout page, instead of redirecting to an intermediate page to choose the bank.\ \ It is necessary to add the `sub_payment_method` field to the deposit request to use this flow. \ Below it's presented the list of banks accepted:\
| Bank name | Sub\_payment\_method | | --------------------------------------- | -------------------- | | Rappipay | `RPP` | | Bancamia | `BMI` | | Banco de Bogotá | `BDB` | | Banco Popular | `BPC` | | Banco GNB Sudameris | `GNB` | | Banco Caja Social | `BCJ` | | Banco Agrario | `AGR` | | Banco Davivienda | `BDA` | | Bancolombia | `BN` | | Banco AV Villas | `BAV` | | Bancoomeva | `BCM` | | Banco Finandina | `BFB` | | Banco Cooperativo Coopcentral | `BCC` | | Banco Santander Colombia | `SC` | | Banco Serfinanza | `BSF` | | BBVA Colombia | `AV` | | Lulo Bank | `BLU` | | Dale | `DAL` | | CFA Cooperativa Financiera | `CFA` | | Citibank | `CK` | | Cotrafa | `COT` | | Coofinep Cooperativa Financiera | `CCF` | | Confiar Cooperativa Financiera | `CON` | | Banco Union antes giros | `BUG` | | Coltefinanciera | `COL` | | Daviplata | `DVP` | | Falabella | `LL` | | BAN100 (formerly Banco Credifinanciera) | `BCR` | | Itau | `I` | | Iris | `IRS` | | Movii S.A. | `MR` | | Nequi | `NQ` | | Banco de occidente | `OC` | | Pichincha | `IX` | | Scotiabank Colpatria | `ST` | # Costa Rica Check the list of Payment Methods available on Costa Rica ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | Available for test | Iframe supported | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------- | :----------------------------------------------: | :----------: | :----------------: | :--------------: | | [](https://resources.directa24.com/cashin/payment_method/square/VI.svg) | `VI` | Visa |

REDIRECT
PCI

| CREDIT\_CARD | | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/MC.svg) | `MC` | MasterCard |

REDIRECT
PCI

| CREDIT\_CARD | | Yes | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Ecuador Check the list of Payment Methods available on Ecuador ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ------------------- | :----------------------------------------------------: | :-----------: | | [](https://resources.directa24.com/cashin/payment_method/square/FO.svg) | `FO` | Facilito |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/GB.svg) | `GB` | Banco Guayaquil | `REDIRECT` | BANK\_DEPOSIT | | [](https://resources.directa24.com/cashin/payment_method/square/PX.svg) | `PX` | Banco Pichincha | `REDIRECT` | BANK\_DEPOSIT | | [](https://resources.directa24.com/cashin/payment_method/square/MV.svg) | `MV` | Pichincha MiVecino | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/ES.svg) | `ES` | ServiPagos |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `BR` | Banco Del Barrio |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/AW.svg) | `AW` | Activa WesternUnion |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `IE` | Banco Internacional | `REDIRECT` | BANK\_DEPOSIT | | | `WU` | Western Union |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `DU` | De Una |

REDIRECT
ONE\_SHOT

| VOUCHER | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Guatemala Check the list of Payment Methods available on Guatemala ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | Available for test | Iframe supported | | :-------------------------------------------------------------: | :-------------: | ---------- | :--------: | :----------: | :----------------: | :--------------: | | | AH | Akisipuedo | `REDIRECT` | CASH | YES | YES | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the OneShot Experience | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Honduras Check the list of Payment Methods available on Honduras ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | Available for test | Iframe supported | | :-------------------------------------------------------------: | :-------------: | ----------- | :----------------------------------------------: | :----------: | :----------------: | :--------------: | | | `VI` | Visa |

REDIRECT
PCI

| CREDIT\_CARD | YES | YES | | | `MC` | Master Card |

REDIRECT
PCI

| CREDIT\_CARD | YES | YES | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the OneShot Experience | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Mexico Check the list of Payment Methods available on Mexico ## Payment Methods
Iconpayment_methodNameFlowPayment Type
MEMercadoPagoREDIRECTVOUCHER
VIVisaREDIRECT
PCI		CREDIT_CARD
VDVisa DebitREDIRECT
PCI		CREDIT_CARD
MCMasterCardREDIRECT
PCI		CREDIT_CARD
MDMasterCard DebitREDIRECT
PCI		CREDIT_CARD
AEAmerican ExpressREDIRECT
PCI		CREDIT_CARD
OXOXXO

REDIRECT

ONE_SHOT

VOUCHER
OXPOxxo Pay

REDIRECT

ONE_SHOT

VOUCHER
SESpei

REDIRECT

ONE_SHOT

BANK_DEPOSIT
CODCoDi

REDIRECT

ONE_SHOT

BANK_TRANSFER
BVBBVA Bancomer

REDIRECT

ONE_SHOT

VOUCHER
STSSantander SuperNetREDIRECT
ONE_SHOT		BANK_TRANSFER
SMSantanderREDIRECT
ONE_SHOT		BANK_DEPOSIT
AFAfirme online banking

REDIRECT

ONE_SHOT

BANK_TRANSFER
TCToditoREDIRECT
ONE_SHOT		BANK_DEPOSIT
PNPayNet

REDIRECT

ONE_SHOT

VOUCHER
FAFarmacia del Ahorro

REDIRECT

ONE_SHOT

VOUCHER
EAExtraREDIRECT
ONE_SHOT		VOUCHER
CLXClarimaxREDIRECT
ONE_SHOT		VOUCHER
BWBodega Aurrera

REDIRECT

ONE_SHOT

VOUCHER
CUCirculo K

REDIRECT

ONE_SHOT

VOUCHER
EN7 Eleven

REDIRECT

ONE_SHOT

VOUCHER
SSSams Club

REDIRECT

ONE_SHOT

VOUCHER
FLFarmacia la mas barata

REDIRECT

ONE_SHOT

VOUCHER
KLKlinc

REDIRECT

ONE_SHOT

VOUCHER
RORoma

REDIRECT

ONE_SHOT

VOUCHER
SQSoriana

REDIRECT

ONE_SHOT

VOUCHER
WEWalmart Express

REDIRECT

ONE_SHOT

VOUCHER
WAWalmart

REDIRECT

ONE_SHOT

VOUCHER
BQLBanorte online banking

REDIRECT

ONE_SHOT

BANK_TRANSFER
{% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Panama Check the list of Payment Methods available on Panama ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | Available for test | Iframe supported | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ------------- | :----------------------------------------------------: | :----------: | :----------------: | :--------------: | | [](https://resources.directa24.com/cashin/payment_method/square/VI.svg) | `VI` | Visa |

REDIRECT
PCI

| CREDIT\_CARD | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/MC.svg) | `MC` | MasterCard |

REDIRECT
PCI

| CREDIT\_CARD | Yes | Yes | | | `WU` | Western Union |

REDIRECT
ONE\_SHOT

| VOUCHER | Yes | Yes | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Paraguay Check the list of Payment Methods available on Paraguay ## Payment Methods | Icon | payment\_method | Name | Flow | Payment Type | Available for test | Iframe supported | | :------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | ---------- | :--------: | :----------: | :----------------: | :--------------: | | [](https://resources.directa24.com/cashin/payment_method/square/VI.svg) | `VI` | Visa | `REDIRECT` | CREDIT\_CARD | Yes | Yes | | [](https://resources.directa24.com/cashin/payment_method/square/MC.svg) | `MC` | MasterCard | `REDIRECT` | CREDIT\_CARD | Yes | Yes | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Peru Check the list of Payment Methods available on Perú ## Methods | Icon | payment\_method | Name | Flow | Payment Type | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------: | --------------------- | :-------------------------------------------------------: | :-----------: | | | `XA` | Tupay |

REDIRECT
ONE\_SHOT

| N/A | | | `XAQR` | Tupay QR | `REDIRECT` | VOUCHER | | | `XACC` | Credit Cards by Tupay | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/EF.svg) | `EF` | Pago Efectivo | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/VI.svg) | `VI` | Visa |

REDIRECT
PCI

| CREDIT\_CARD | | [](https://resources.directa24.com/cashin/payment_method/square/MC.svg) | `MC` | Mastercard |

REDIRECT
PCI

| CREDIT\_CARD | | [](https://resources.directa24.com/cashin/payment_method/square/YP.svg) | `YP` | Yape |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/IB.svg) | `IB` | Interbank | `REDIRECT` | BANK\_DEPOSIT | | [](https://resources.directa24.com/cashin/payment_method/square/BC.svg) | `BC` | BCP |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | | [](https://resources.directa24.com/cashin/payment_method/square/ST.svg) | `ST` | Scotia | `REDIRECT` | BANK\_DEPOSIT | | | `BAB` | Banbif |

REDIRECT

ONE\_SHOT

| BANK\_DEPOSIT | | | `RY` | Banco Ripley | `REDIRECT` | BANK\_DEPOSIT | | | `NAG` | Niubiz Agents Payment |

REDIRECT
ONE\_SHOT

| VOUCHER | | | `RDP` | Red Digital | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/WU.svg) | `WU` | Western Union | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/BP.svg) | `BP` | BBVA | `REDIRECT` | BANK\_DEPOSIT | | [](https://resources.directa24.com/cashin/payment_method/square/KE.svg) | `KE` | Kasnet |

REDIRECT
ONE\_SHOT

| VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/TM.svg) | `TM` | Tambo | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/HC.svg) | `HC` | Caja Huancayo | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/US.svg) | `US` | Caja Cusco | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/JA.svg) | `JA` | Caja Arequipa | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/JI.svg) | `JI` | Caja ICA | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/JP.svg) | `JP` | Caja Piura | `REDIRECT` | VOUCHER | | [](https://resources.directa24.com/cashin/payment_method/square/JT.svg) | `JT` | Caja Tacna | `REDIRECT` | VOUCHER | | | `XAPL` | Plin | `REDIRECT` | VOUCHER | | | `IL` | Plin | `REDIRECT` | WALLET | {% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos and more details. {% endhint %} ## Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience) | Payment Method Name | country | amount | payer\[] | payment\_method | | ------------------- | :-----: | :----: | :------: | :-------------: | | All | Yes | Yes | Yes | Yes | ### ### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # API Codes Learn about the API Codes returned by our APIs ## Deposits Status Codes The `status` of the deposits are separated into different and very specific categories for you to better handle and know the behavior of your customers. | Status | Description | | :-----------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The deposit is created but the customer hasn't opened the link yet. | | | The deposit is created and the customer has opened the link but he/she didn't complete the payment flow (select payment method, complete personal details, confirm details) or the provider was unable to process the request. | | | The deposit is created with all the information required and it is awaiting on customer's payment. It has been marked by you to release it earlier. Please note that the customer hasn't paid yet and the money won't be credited to your balance until the customer's payment is detected. | | | The deposit is created with all the information required and it is awaiting on customer's payment. | | | The deposit didn't pass our anti-fraud systems and will be retained until manual review. | | | The deposit has reached its expiration time and the user didn't pay. | | | The deposit has been cancelled by the customer or it has been 7 days after the expiration. | | | The deposit was paid by the customer but it still hasn't arrived the payer's crypto wallet. Only used for [crypto payments](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#crypto-payments). | | | The deposit has been completed and the money was credited to your account or to the payer's crypto wallet. | {% hint style="success" %} Use the [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) to retrieve the status of a refund. {% endhint %} ## Refunds Status Codes | Status | Description | | :-----------------------------------------------------------------: | ------------------------------------------------------------------------------------- | | | The refund is created and is pending to be processed. It can still be cancelled. | | | The refund is pending for you to provide more information. It can still be cancelled. | | | The refund has been sent to the bank for processing. It can't be cancelled anymore. | | | The refund has been manually cancelled. Final status. | | | The refund has been rejected by the bank. Final status. | | | The refund has been completed. Final status. | {% hint style="success" %} Use the [Refund Status Endpoint](/api-documentation/deposits-api/endpoints/refund-status-endpoint) to retrieve the status of a refund. {% endhint %} ## API Error Codes ### Categories We group the error codes into different categories for better understanding. * `1xx` - Header errors * `2xx` - Merchant/request validations errors * `3xx` - User errors * `4xx` - Create deposit errors * `5xx` - Other errors * `7xx` - Internal errors * `8xx` - [Refund errors](/api-documentation/deposits-api/api-codes#refund-error-codes) * `9xx` - [Credit Card errors](/api-documentation/deposits-api/api-codes#credit-card-error-codes) ### ### Deposit API Error Codes
API CodeHTTP CodeTypeMessageDescription
100401INVALID_CREDENTIALSInvalid CredentialsThe X-Login you sent is incorrect or it is not yet active
101400MISSING_REQUIRED_HEADERMissing or invalid format for required header {headerName}Make sure all the headers are correct. Click here for details
102400INVALID_SIGNATUREInvalid signatureInvalid Authorization signature. Click here for instructions
103400INVALID_DATE_RANGEX-Date header value out of valid rangeThe X-Date value you sent in the header is outside the allowed time-frame. Click here for details
104400IDEMPOTENCY_KEY_ALREADY_USEDIdempotency key {key} has been already usedThe X-Idempotency-Key you sent has already been used
105400EMPTY_HEADER_VALUEOptional header {headerName} must not be blankIf an optional header is sent, it can't be blank
200405METHOD_NOT_ALLOWEDMethod not allowedThe request method used is not allowed. Click here for endpoints instructions
201400BEAN_VALIDATION_ERRORField validation error. Check detailsOne or more fields sent were incorrect
202401INVALID_IPUnregistered IP addressYou must whitelist your IP Address. Click here for instructions
203429VELOCITY_CHECKToo many consecutive attempts for user (Velocity Check)The user has created many deposits in a short period of time
204400INVALID_MEDIA_TYPEInvalid media typeThe payload format is in an unsupported format. Make sure the header Content-Type is application/json
205400MISSING_REQUEST_PARAMETERMissing request parameterThe request is missing an important parameter
206400MISSING_PATH_VARIABLEMissing path variableThe request is missing an important path variable
207400INVALID_REQUEST_PARAMETER_TYPEInvalid request parameter typeA parameter type sent was incorrect
208404RESOURCE_NOT_FOUNDResource not foundThe deposit_id being used doesn't exist
209400INVALID_REQUEST_BODYInvalid request body: {details}There is a syntax error in the JSON payload
217403FORBIDDEN_MERCHANTMerchant has no authorization to use this APIYour Merchant Account is not enabled to use this API. Contact your Account Manager for more information
218400CRYPTO_NOT_ALLOWED_FOR_MERCHANTWrong merchant routing type for crypto paymentsYour Merchant Account is not enabled to use the Crypto functionality. Contact your Account Manager for more information
300400USER_BLACKLISTEDUser blacklistedThe user is known for committing fraud
301400USER_GREYLISTEDUser greylistedThe user is banned because we detected suspicious behavior
302400USER_UNAUTHORIZEDUser unauthorizedThe user is blocked. For further information go to the "Clients" section on the Merchant Panel
303400USER_UNAUTHORIZED_REG_STATUSUser unauthorized due to cadastral situationCheck the user's cadastral situation
304400USER_LIMIT_EXCEEDEDThe user limit has been exceeded: {TRANSACTION|DAILY|WEEKLY|MONTHLY}Check the user's limit on the Merchant Panel under the "Clients" section
305400PAYMENT_METHOD_RESTRICTEDRestricted payment method typeThe payment type is disallowed for the payer
306400FINANCIAL_CAPACITYThe transaction cannot be processed as the user has reached their financial capacity, please provide proof of fundsThe transaction cannot be processed as the user has reached their financial capacity, please provide proof of funds
400400INVALID_AMOUNTInvalid amount. The minimum is USD 2 or equivalent in local currencyThe amount does not reach the minimum limit of USD 2
401400PAYMENT_METHOD_NOT_FOUNDPayment method not foundThe payment_method_code sent isn't correct, or the Payment Method isn't enabled for your Merchant account. Use the payment_methods API to diagnose this error
402400INVOICE_ALREADY_USEDInvoice already usedThe invoice_id sent has already been used
403400INVALID_BANK_CODEInvalid bank code: {code}The bank_code sent is invalid
404400ERROR_CREATING_PAYMENTPayment method provider unavailableOur provider is temporarily unavailable. Use a different payment method or try again
406400INVALID_ADDRESSInvalid addressThe address sent is invalid
407400INVALID_CITYInvalid cityThe city sent is invalid
408400PAYMENT_METHOD_LIMIT_EXCEEDEDPayment method limit exceededThe amount sent exceeds the provider's payment method limit. Try with a smaller amount
410400PAYMENT_METHOD_MINIMUM_REQUIREDPayment method minimum requiredThe amount sent is smaller than the provider's payment method minimum limit. Try with a bigger amount
411400INVALID_USER_DOCUMENTInvalid user document IDThe document_id specified was rejected by the provider itself. Check it is valid
412400PAYMENT_METHOD_UNAVAILABLEPayment Method UnavailableThe payment method is temporarily unavailable, please try again later
413400INVALID_REPORTED_INFO_BANK_BENEFICIARYInvalid reportedInfo.bankBeneficiary valueThe value sent in the field reported_info.bank_beneficiary is invalid. Check validations
414400MISSING_REPORTED_INFOMissing reportedInfo attributeThere are missing values for the reported_info object. Check requirements
415400INVALID_REPORTED_INFO_BANK_BRANCHInvalid reportedInfo.bankBranch valueThe value sent in the field reported_info.bankBranch is invalid. Check validations
416400INVALID_REPORTED_INFO_BANK_ACCOUNT_NUMBERInvalid reportedInfo.bankAccountNumber valueThe value sent in the field reported_info.bankAccountNumber is invalid. Check validations
417400INVALID_REPORTED_INFO_ACCOUNT_TYPEInvalid reportedInfo.bankAccountType valueThe value sent in the field reported_info.bankAccountType is invalid. Check validations
418400MISSING_REQUIRED_FIELDSMissing required fields in order to generate DepositThe request is missing a required field. Please check here.
419400MISSING_PAYER_ID_OR_DOCUMENTpayer.id or payer.document field is missingThe request is missing the payer.id or payer.document field and at least one of them is mandatory to create the deposit
500500GENERIC_ERROROh no! Something has gone wrong. Please contact a system administratorInternal error, please contact support
511400NO_PAYMENT_METHODS_AVAILABLENo payment methods availablePlease contact your AM regarding payment methods’ availability
720400MISSING_CONFIGURATIONMissing configuration for merchant accountPlease contact your AM/TAM
429400BANK_ACCOUNT_REQUIREDBank account details are required for Invoice {invoiceId}, Merchant {merchantId}.The request is missing the bank_accountfield.
### ### Refund API Error Codes
API CodeHTTP CodeTypeMessageDescription
800400REFUND_NOT_ENABLEDRefund is not enabledYour Merchant account doesn't have the refund capability enabled. Check with your Account Manager
801400DEPOSIT_NOT_COMPLETEDRefund cannot be applied since deposit is not in status completedThe refunds can only be applied over COMPLETED deposits
802400INVALID_AMOUNT_TO_REFUNDAmount to refund not validThe amount to refund is not valid. Check if the amount is negative or bigger than the deposit itself.
803400INSUFFICIENT_FUNDSInsufficient fundsYour Merchant account doesn't have enough funds to cover for the refund amount
804400MISSING_BANK_ACCOUNTMissing bank account informationThe bank account information is missing
805400ERROR_IN_REFUNDError, the refund was not processed. {details}The refund could not be completed. Flag it for review on our Merchant Panel for further information
### PCI Deposit API Error codes
API CodeHTTP CodeTypeMessageDescription
421400INSTALLMENTS_NOT_ENABLEDMerchant {MID} does not support installments for country {iso}.Your merchant account is not allowed to create deposits with installments in that country.
422400INSTALLMENTS_QUANTITY_INVALIDMerchant {MID} installments quantity is invalid for country {iso code}. Requested {number}, allowed [{quantity of installments allowed}].The amount of installments requested is not allowed for your merchant account in that country.
Please check the allowed quantity.
900400CREDIT_CARD_BIN_NOT_FOUNDInvalid credit card binWe were unable to find a valid issuer with the first 6 digits of the card
### Fraud Reason Codes for KYC Errors {% hint style="info" %} The reasons below are shown whenever the deposit is declined with `type` `USER_REJECTED_KYC_CHECK` or `DEPOSIT_REJECTED_FRAUD_CHECK` {% endhint %}
HTTP CodeReason CodeReasonDescription
400101Transaction related to blacklisted user.The transaction was rejected because one of its attributes was related to a blacklisted user
400102Email riskHigh risk detected by our fraud prevention engine related to the user's email address
400103Credit card riskHigh risk detected by our fraud prevention engine related to the credit card used
400104User rejected after KYC checkUser rejected by our KYC controls
400105Underage user detectedUser does not meet the minimum age requirement
400106Mismatch between user name and document nameThe user's name does not match the name associated with the document provided
400107Document status is not OKSome irregularities have been detected while validating the document information
400108PEP user detectedThe user is a Politically Exposed Person (PEP)
400109High risk detectedHigh risk detected by our fraud prevention engine
400110Failed biometric checkSomething went wrong while performing the biometric check on the user
400111Failed OTP verificationSomething went wrong while performing the OTP check on the user
4001123DS Authentication failedTransaction rejected due to failed 3DS
400113Document does not existInvalid Document
400114User rejected after CNPJ validationsInvalid/Irregular CNPJ (Brasil Only)
400115Invalid document formatDocument format rejections
400116Sportsman UserSportsman User
400117Related to Sportsman UserRelated to Sportsman User
400118National Sanction ListsUser has been identified on national sanction lists
400119International Sanction ListsUser has been identified on international sanction lists
400120Regulatory reasonsRejected due to regulatory reasons
400121Velocity checkRejected due to velocity check
# Cashouts API Cashouts API v3 Introduction ### V3 Cashouts API Integration #### Cashout Flow Find below the description of a cashout flow using the OKP cashouts integration: **1 -** Upon your customer's request, you submit a cashout request through the Cashout-Request API or through the Merchants panel (Transactions -> Withdrawals -> Request Cashout). **2 -** Initial validations are performed by the API, such as: * Merchant account balance enough to cover the cashout * Merchant account Transaction/Daily/Monthly limits permit the cashout * Destination Bank Account details are correct. * Customer's details are correct. Eg. Document ID **3 -** If the previous step is correct, the cashout is created and remains on **PENDING** status, otherwise, it's **DECLINED**. If Pending, it will be then sent to the bank for processing, when that happens, the status is set to **DELIVERED**. **4 -** Once the transaction comes back from the bank, it can be either **COMPLETED** or **REJECTED** (by the bank). There are some cases in which the bank could Confirm the Cashout and then Reject it because the destinatary's bank account was, for any reason, unable to receive the funds. This is a corner case but should be considered when integrating. ## Postman collection In order for you to start testing our Cashouts APIs right away, we have prepared a Postman Collection you can use to test and validate your integration along with the functionalities we offer {% embed url="" %} Click here to download the Postman Collection. {% endembed %} {% hint style="success" %} We provide you with test credentials to our test environment, but make sure sure you replace the vars `apiKey`, `apiPassphrase` and `apiSignature` in the Pre-req. Scripts" section of all the requests with your own [API credentials for cashouts](/api-documentation/cashouts-api/technical-and-security-aspects#api-keys) {% endhint %} # Technical and Security Aspects Technical and Security Aspects of our V3 Cashout endpoints ## Security Considerations * All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. * API requests without [Payload-Signature](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) will also fail. * You will be able to hit our APIs only from the IPs you have [previously whitelisted](#ip-whitelisting) on the Merchant Panel. ## Environments All the integration must be performed on our **STG environment**, where you can perform your tests freely without risks of any kind. When you sign up, we will generate you an account on our STG environment where you will be able to: * See the transactions created * Approve and cancel transactions * Retrieve your API Keys * Whitelist your IPs, and more ### Endpoint domains Each environment has its own domain. The path of the [endpoints](/api-documentation/cashouts-api/endpoints) do not change. | Environment | Domain | | ----------- | -------------------------------------- | | Staging | `https://api-stg.onekeypayments.com/` | | Production | Provided once you complete the testing | {% hint style="info" %} Notes: * You will use the STG endpoints to integrate. * The STG and PROD environments are not communicated in any way. * No transaction created on the STG environment will be reflected on the PROD environment or vice versa. * The API Keys and configurations between environments are also different. * In case of seeing the error "Insufficient Funds" on STG, you can create and approve a deposit or reach out to to add funds to your account. {% endhint %} ## API Keys In order to authenticate, our Cashouts APIs uses API Keys in all of the requests to authenticate. Your API Keys can be retrieved from the Merchant Panel by going to Settings -> API Access -> Cashouts Credentials. {% hint style="info" %} * The API Keys between the STG and PROD environments are different. {% endhint %} These are the three credentials you will need: * Your user: `API Key` * Your password: `API Passphrase` * Your secret key to generate the signatures: `API Signature` Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). You must provide your API Keys in all requests as the basic auth username and password. Your user and password keys must be sent in all the API calls using the `API Key` and `API Passphrase` fields on the body of the request. Your API Keys, along with your [IP Addresses](#ip-whitelisting) are your way to authenticate yourself, therefore, do not share your credentials in publicly accessible areas such as GitHub, client-side code and so forth. ## Headers All requests sent through Cashouts v3 API must have the following headers. | Header | Format | Mandatory | Description | | ----------------- | :----: | :-------: | ---------------------------------------------------------- | | Payload-Signature | String | Yes | HMAC256 of the whole JSON Payload using your API Signature | | Content-Type | String | Yes | `application/json` | | User-Agent | String | Yes | Server client user agent | ## IP Whitelisting For security purposes, you need to whitelist the IPs from where you will call our API. In order to whitelist your IPs and make the process as smoother as possible, you should go to **Settings -> API Access** and add the list of IPs you will possibly use under the **Cashouts IP Address** section. Reach out to if you need to whitelist **our servers IPs** on your firewall. ## Best Practices We recommend you follow this list of technical and security practices to maximize the security of the information end-to-end. 1. Always ensure to verify the Signatures control string sent in the notifications to validate its veracity. 2. We convert all the data we receive to UTF-8. Make sure you are also converting it into UTF-8 to make sure both parties have the same details. Go to the next page to learn how to generate the Payload-Signature control string to verify the requests' you send and receive integrity. # Calculating the Payload-Signature Learn how to correctly calculate the Signature Control String to authenticate with the V3 Cashout endpoints ## Calculating the Signature All calls to our Cashouts APIs must contain a `Payload-Signature` field on the header used to ensure request integrity and to authenticate yourself since you will use your own API Signature (secret key) to generate and encrypt a hash. It has to be created using **HMAC-SHA-256 (RFC 2104)** encoding and the payload is made of the entire JSON Payload sent in the body of the requests and notifications. {% hint style="success" %} Use your API Signature to create the HASH {% endhint %} The `Payload-Signature` field on the header of the requests will contain the hash generated from hashing the entire JSON Payload: > Payload-Signature: HMAC256(jsonPayload) Example: > Payload-Signature: 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf ​ ​ ### Notes The `Payload-Signature` value is case sensitive and must be sent in lower case. In case the `jsonPayload` value is empty, use an empty string instead. The `jsonPayload` should be converted to UTF-8 before hashing it to prevent `Invalid Signature` error when sending characters with different encodings. ​ ## Examples Check the examples below on how to calculate the `Payload-Signature`. {% tabs %} {% tab title="Java" %} ```java import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.net.util.Base64; String json_payload = "{ \"login\": \"cashout_API_Key\", \"pass\": \"cashout_API_Passphrase\", \"external_id\": \"123456789\", \"document_id\": \"1234567899\", \"document_type\": \"\", \"cashout_type\": \"BANK\", \"beneficiary_name\": \"Test User\", \"beneficiary_lastname\": \"Test User\", \"country\": \"MX\", \"amount\": 2000, \"currency\": \"MXN\", \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/onekeypayments.com\\/notification\", \"bank_code\": \"072\",\"bank_branch\": \"\", \"bank_account\": \"1234567890\", \"account_type\": \"C\", \"address\": \"\"}"; String secretKey = "cashout_secret_key"; Mac hasher = Mac.getInstance("HmacSHA256"); hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256")); String payload_signature = Base64.encodeBase64String(hasher.doFinal(json_payload.getBytes())).toLowerCase(); ``` {% endtab %} {% tab title="PHP" %} ```csharp ``` {% endtab %} {% tab title="C#" %} ```php using System; using System.Text; using System.Security.Cryptography; string jsonPayload = "{ \"login\": \"cashout_API_Key\", \"pass\": \"cashout_API_Passphrase\", \"external_id\": \"123456789\", \"document_id\": \"1234567899\", \"document_type\": \"\", \"cashout_type\": \"BANK\", \"beneficiary_name\": \"Test User\", \"beneficiary_lastname\": \"Test User\", \"country\": \"MX\", \"amount\": 2000, \"currency\": \"MXN\", \"email\": \"test@test.com\", \"notification_url\": \"http:\\/\\/www.onekeypayments.com\\/notification\", \"bank_code\": \"072\",\"bank_branch\": \"\", \"bank_account\": \"1234567890\", \"account_type\": \"C\", \"address\": \"\"}"; string secretKey = "cashout_secret_key"; byte[] keyByte = new ASCIIEncoding().GetBytes(secretKey); byte[] jsonPayloadBytes = new ASCIIEncoding().GetBytes(jsonPayload); byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(jsonPayloadBytes); string payloadSignature = BitConverter.ToString(hashmessage).Replace("-", "").ToLower(); ``` {% endtab %} {% endtabs %} # Endpoints Learn how to integrate all of our Cashouts endpoints # Cashout Creation Endpoint Learn how to generate cashouts request by using our Cashout API v3 directly from your website ## Cashout Request `POST` `https://api-stg.onekeypayments.com/v3/cashout` This endpoint allows you to generate cashout requests #### Headers | Name | Type | Description | | --------------------------------------------------- | ------ | ------------------ | | Content-Type\* | string | `application/json` | | Payload-Signature\* | string | Control signature | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | login\* | string | Your D24 CASHOUTS API login key | | pass\* | string | Your D24 CASHOUTS API pass key | | external\_id\* | string | Unique cashout ID on the merchant end | | country\* | string | Country of the cashout | | amount\* | number | Amount of the cashout | | currency | string | Currency in which the amount was specified | | document\_id\* | string | Document ID of the beneficiary | | document\_type | string | Document type of the ID specified | | beneficiary\_name\* | string | Beneficiary's name | | beneficiary\_lastname | string | Beneficiary's last name | | email | string | Beneficiary's email address | | phone | string | Beneficiary's phone number | | bank\_code | number | Beneficiary's bank code or ISPB | | bank\_account | string | Beneficiary's bank account | | bank\_branch | string | Beneficiary's branch of their bank account | | account\_type | string | Beneficiary's account type | | registered\_bank\_accounts | object | Allows to send details of the registred accounts of the client, [example here](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#registred-bank-accounts) | | registered\_bank\_accounts.account\_number | string | Beneficiary's registred account | | registered\_bank\_accounts.ispb\_code | number | Beneficiary's bank ISPB code | | registered\_bank\_accounts.bank\_code | number | Beneficiary's [bank code](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#bank-codes) | | registered\_bank\_accounts.bank\_branch | number | Beneficiary's bank branch | | address | string | Beneficiary's address | | city | string | Beneficiary's city | | postal\_code | string | Beneficiary's postal code | | beneficiary\_birthdate | string | Beneficiary's birthdate | | notification\_url\* | string | URL where the notifications will be sent | | comments | string | Commentaries about the cashout | | on\_hold | boolean | Used to mark a cashout as on hold and not process it until manually changed to pending by you | {% tabs %} {% tab title="200 Cashout request successfully created." %} ```bash { "cashout_id": "8405147" } ``` {% endtab %} {% tab title="401 The credentials specified are incorrect." %} ```bash { "code": 401, "message": "Invalid credentials." } ``` {% endtab %} {% tab title="412 Error in the data validation." %} ```bash { "code": 303, "message": "Invalid bank code" } { "code": 300, "message": "bank_account: must not be null; Invalid Bank account" } ``` {% endtab %} {% endtabs %} ## Request Fields Description | Field | Format | Description | Validations | | ------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------: | | login | string (max length: 32) | Your OKP **CASHOUTS** API Key, found on the Merchant Panel by going to: Settings -> API Access. Notice there are specific Cashout credentials | | | pass | string (max length: 32) | Your OKP **CASHOUTS** API Passphrase, found on the Merchant Panel by going to: Settings -> API Access. Notice there are specific Cashout credentials | | | external\_id | string (max length: 100) | Unique cashout ID on the merchant end | | | country | string (length: 2) | Country code for the cashout in *ISO 3166-1 alpha-2 code* format | [See country codes](/knowledge-base/countries-specifications#currencies) | | amount | Big Decimal (up to 2 decimals) | Cashout amount on the currency specified | Valid number | | currency | string (length: 3) | Currency code of the amount in *ISO 4217* format | [See valid currencies](/knowledge-base/countries-specifications#currencies) | | document\_id | string (max length: 40) | Beneficiary’s personal identification number | [See document validations](/knowledge-base/countries-specifications#documents) | | document\_type | string (maxLength: 15) | Beneficiary’s personal identification number type | [See document types validations](/knowledge-base/countries-specifications#documents) | | beneficiary\_name | string (max length: 100) | Beneficiary's name | String of up to 100 characters | | beneficiary\_lastname | string (max length: 100) | Beneficiary's last name | String of up to 100 characters | | email | string (maxLength: 100) | Beneficiary's valid email address | [Valid email address](/knowledge-base/countries-specifications#emails-validations) | | phone | string (maxLength: 20) | Beneficiary's phone number | [See phone number validations](/knowledge-base/countries-specifications#mobile-numbers-validations) | | bank\_code | Integer (max length: 8) | Beneficiary's bank code or ISPB – Identificador do Sistema de Pagamentos Brasileiro | [See bank codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | | bank\_account | string (max length: 30) | Beneficiary's bank account number | [See bank\_account validations](/api-documentation/cashouts-api/countries-validations#bank-account) | | bank\_branch | string (max length: 15) | Beneficiary's bank branch number | [See bank\_branch validations](/api-documentation/cashouts-api/countries-validations#bank-branch) | | account\_type | string (max length: 1) | Type of account | [See bank\_account types](/api-documentation/cashouts-api/countries-validations#account-types) | | registered\_bank\_accounts | object | Optional field to send registred accounts | [See registred bank accounts example](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#registred-bank-accounts) | | registered\_bank\_accounts.account\_number | string (max length: 30) | Beneficiary's registred account number | [See bank\_account validations](/api-documentation/cashouts-api/countries-validations#bank-account) | | registered\_bank\_accounts.ispb\_code | Integer (max length: 8) | Beneficiary's ISPB code from the registred account | Integer up to 8 numbers | | registered\_bank\_accounts.bank\_code | string (max length: 15) | Beneficiary's bank code from the registred account | [See bank codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | | registered\_bank\_accounts.bank\_branch | Integer (max length: 8) | Beneficiary's bank branch from the registred account | [See bank codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | | address | string (max length: 255) | Beneficiary's address | String of up to 200 characters | | city | string (max length: 100) | Beneficiary's city | String of up to 100 characters | | postal\_code | string (max length: 20) | Beneficiary's postal code | [See postal\_code validations](/knowledge-base/countries-specifications#postal-code-validations) | | beneficiary\_birthdate | string (pattern: 'YYYYMMDD') | Beneficiary's birthdate | | | notification\_url | string (max length: 300) | To be provided if the notification URL is different from the notification URL defined on the Merchant Panel | Valid URL over HTTPS | | comments | string (max length: 200) | A commentary for this cashout | String of up to 200 characters | | on\_hold | boolean | If the merchant wants to hold the cashout and set it to process later through the merchants panel. Default: false | `[true, false]` | ## Fields required Each country has different requirements and therefore we ask for different fields you need to send on the requests. Go to the[ Countries Validations ](/api-documentation/cashouts-api/countries-validations)page to check each country requirements and validations. ## Cashouts to debit cards In Mexico, we accept cashouts sent directly to debit cards. When that happens, you need to send the request through a different endpoint, otherwise your request will be declined with `Invalid bank account, it shouldn't be a credit card`. **PROD endpoint for Debit Cards:** Email with your cashout API Key **STG endpoint for Debit Cards:** `https://cc-api-stg.onekeypayments.com/v3/cashout` The bank accounts in Mexico are in [CLABE](https://en.wikipedia.org/wiki/CLABE) format (numeric) and have 18 digits (without dashes). Therefore one way to detect that a bank account specified by the customer is a debit card is by checking with the[ luhn algorithm ](https://www.geeksforgeeks.org/luhn-algorithm/)if it is a valid card number and/or with a regex for each brand, like the example below. ```java public static final String SENSIBLE_DATA_PATTERN = new StringBuilder("(?:(?4[0-9]{12}(?:[0-9]{3})?)") .append("|(?5[1-5][0-9]{14})") .append("|(?6(?:011|5[0-9]{2})[0-9]{12})") .append("|(?3[47][0-9]{13})") .append("|(?3(?:0[0-5]|[68][0-9])?[0-9]{11})") .append("|(?(?:2131|1800|35[0-9]{3})[0-9]{11}))") .toString(); private boolean validateCreditCard(CashoutRequestDto request) { final String bankAccount = request.getBank_account(); if (StringUtils.isEmpty(bankAccount) || !LuhnCheckDigit.LUHN_CHECK_DIGIT.isValid(bankAccount) || bankAccount.matches(Constants.SENSIBLE_DATA_PATTERN)) { return false; } return true; } ``` If true, send the request through the `cc-api` endpoint, if false send it through the normal endpoint. The integration and requirements remains exactly the same, only changing the error message returned in case of invalid bank account and that we validate the `bank_account` sent to be a valid credit card number using the [Luhn Algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm). Sending a debit card number through the non-cc endpoint will make the request to fail with the following error: ```java { "code": 300, "message": "bank_account: Invalid bank account, it shouldn't be a credit card" } ``` Invalid bank\_account error on the cc-api endpoint: ```java { "code": 300, "message": "bankAccount: invalid credit card number" } ``` # Notifications Learn about how the notifications of the Cashout API v3 work ## Notifications A notification will be sent every time the status of a cashout changes. For security reasons we don't send the status of the cashout on the notification itself. Once you have received the notification, you will need to use the [Cashout Status Endpoint](/api-documentation/cashouts-api/endpoints/cashout-status-endpoint) to retrieve its new status. The notifications will be sent to the `notification_url` specified in the request or to the default Withdrawals URL you have configured on the Merchant Panel by **POST** protocol in **x-www-form-urlencoded** format and will have the following fields: | Field | Format | Description | | ------------------- | --------------------------------------- | ----------------------------------------------------- | | date | Date. Format: YYYY-MM-DD HH:MM:SS (GMT) | Date the cashout changed its status | | bank\_reference\_id | String (max. 50 chars) | Reference ID of the bank if any | | comments | String (max. 200 chars) | Comments of the cashout if any | | external\_id | String (max. 100 chars) | ID of the cashout you sent while creating the request | | control | String | Control signature of the notification | | cashout\_id | Number | ID of the cashout on our end | | status\_reason | String | Reason of the status if any | ### STG Testing In the STG environment you can force a notification to be sent to your `notification_url` from the [STG Merchant Panel](https://merchants-stg.directa24.com/login) by going to the `Transactions -> Withdrawals` page, opening the cashout transaction and clicking on one of the options that will appear when clicking in the three dots button on the top right of the screen. Those options will change the status of the cashout therefore **sending the respective notification after a few minutes**. {% hint style="info" %} On STG, the notifications could take up to 5 minutes in being sent. {% endhint %} ![](/files/-M9v7i6l28PPXX9ssThc) ## Example Notifications ``` date=2020-03-12%2020%3A26%3A11 &bank_reference_id= &comments= &external_id=cashoutV35381 &control=A4CFF64E78C4BD01F8BFCA4AFF04632EC4A33CC61BD6BBD156BA1289897892EB &cashout_id=60067 &status_reason= ``` ## Control String The control string for the notifications is made up of some random characters at the beginning and the end of the request and the `external_id` received in the middle. {% hint style="info" %} The control string should be generated using your own secret key (API Signature) and must be in upper case. Make sure you convert the message to hash to UTF-8 to prevent errors. {% endhint %} Check the examples below on how to calculate the control string for the notifications: {% tabs %} {% tab title="JAVA" %} ```java public static void main(String[] args) throws IOException, NoSuchAlgorithmException, InvalidKeyException { String external_id = "cashoutID1234"; String message = "Be4" + external_id + "Bo7"; String apiSignature = "your_deposits_api_signature"; Mac hasher = Mac.getInstance("HmacSHA256"); hasher.init(new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); byte[] result = hasher.doFinal(message.getBytes(StandardCharsets.UTF_8)); System.out.println(StringUtils.upperCase(DatatypeConverter.printHexBinary(result))); } ``` {% endtab %} {% tab title="PHP" %} ```php $external_id = 'cashoutID1234'; $message = 'Be4' . $external_id . 'Bo7'; $api_signature = 'cashout_api_signature'; $hash = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $api_signature))); ``` {% endtab %} {% tab title="C#" %} ```csharp string external_id = "cashoutID1234"; string message = "Be4" + external_id + "Bo7"; string apiSignature = "your_cashouts_api_signature"; byte[] keyByte = new System.Text.Encoding.UTF8.GetBytes(apiSignature); byte[] messageBytes = new System.Text.Encoding.UTF8.GetBytes(message); byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes); string control = BitConverter.ToString(hashmessage).Replace("-", "").ToUpper(); ``` {% endtab %} {% endtabs %} ## Retry logic Every time a cashout changes its status, we will send you a notification so you can [check its status](/api-documentation/cashouts-api/endpoints/cashout-status-endpoint) back. In case that for some reason your server was unable to receive the notification and you returned an HTTP code different than 2XX, we will retry the notification up to 5 more times or until you respond with HTTP 2XX, whatever comes first. {% hint style="success" %} In case of errors while handling the notification, make sure you will answer with an HTTP code distinct than 2XX, that way we will retry the notification. {% endhint %} The time between the 5 notifications attempts will be of 5 minutes each. When the notification failed to be sent, it will be shown like this in our Merchant Panel: ![](/files/-MkIVGqDDe8OYIKHdJ0O) If you see the errors from the screenshot above, it means the cashout was successfully completed but suddenly we couldn't notify you. Keep reading to know how to resend the notifications. ## Resend Notifications In case your system was unable to receive the notification in any of the 5 attempts, you can always check its status with the [Cashout Status Endpoint.](/api-documentation/cashouts-api/endpoints/cashout-status-endpoint) If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the cashout (Transactions -> Withdrawals) and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent. {% hint style="success" %} It can take up to 2 minute for the notification to be resent. {% endhint %} ![](/files/-MkIVm1exkvCAAucF04N) # Cashout Status Endpoint Learn how to use the Endpoint to retrieve the status of a cashout ## Cashout Status Endpoint `POST` `https://api-stg.onekeypayments.com/v3/cashout/status` This API allows you to retrieve the status of a cashout #### Headers | Name | Type | Description | | --------------------------------------------------- | ------ | ------------------ | | Content-Type\* | string | `application/json` | | Payload-Signature\* | string | Control Signature | #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | | login\* | String | Your D24 CASHOUTS API login key | | pass\* | string | Your D24 CASHOUTS API pass key | | cashout\_id\* | number | The ID of the cashout to check status of. It is the one generated by D24 when the cashout was created | | external\_id\* | string | The ID of the cashout to check status of. It is the one you sent when the cashout was created | {% tabs %} {% tab title="200 The status of the cashout was successfully retrieved" %} ```java { "cashout_status": 1, "cashout_status_description": "Completed" } { "cashout_status": 3, "cashout_status_description": "Rejected", "rejection_code": 0, "rejection_reason": "Test" } ``` {% endtab %} {% tab title="401 Invalid credentials error" %} ```java { "code": 401, "message": "Invalid credentials." } ``` {% endtab %} {% tab title="412 The cashout ID was not found" %} ```java { "code": 509, "message": "Cashout not found with this ID" } ``` {% endtab %} {% endtabs %} ## Cashout Status Request ### Request Example ```java // HEADERS Content-Type: application/json Payload-Signature: 2e5023770760ea0a02230bff1a6dab934fe3b47a5e3d43854b58676600ee3868 // BODY { "login": "cashout_login", "pass": "cashout_pass", "cashout_id": 11954 } ``` ### Request Fields Description | Field | Format | Description | | ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `login` | String. Length 32 max | Your OKP **CASHOUTS** API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials | | `pass` | String. Length 32 max | Your OKP **CASHOUTS** API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials | | `cashout_id` | Number | Identifier of the cashout on OKP end. It is the one returned by the [Create Cashout Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint) | | `external_id` | String | Identifier of the cashout on the Merchant end. It is the one you sent while [Creating the Cashout request](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint). You can opt to send this field or `cashout_id` | ### Request Payload Signature The Payload-Signature of the Cashout Status Endpoint is calculated by hashing the whole JSON payload of the request using HMAC256 and your secret key (API Signature) to encrypt it. [Click here](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) for further instructions. ## Cashout Status Response ### Completed Response Example ```java { "cashout_status": 1, "cashout_status_description": "Completed", "provider_external_reference": "E352104102024101612486eH2eXXXXXX", "bank": { "ispb": "90400888" "code": "336", "name": "BANCO SANTANDER BRASIL S.A.", } } { "cashout_status": 3, "cashout_status_description": "Rejected", "rejection_code": 808, "rejection_reason": "ERROR_OTHER" } ``` ### Rejected Response Example ```json { "cashout_status": 3, "cashout_status_description": "Rejected", "rejection_code": 808, "rejection_reason": "ERROR_OTHER" "bank": { "ispb": "90400888" "code": "336", "name": "BANCO SANTANDER BRASIL S.A.", } } ``` {% hint style="info" %} For rejected cashouts that are related to an invalid pix key, or due to invalid bank account details, not banking information will be shown here. {% endhint %} ### Response Fields Description | Field | Format | Description | | ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `cashout_status` | Number | Status code of the cashout. [See list of status](/api-documentation/cashouts-api/api-codes#cashout-status-codes) | | `cashout_status_description` | String | Description of the status | | `rejection_code` | Number | Rejection code if sent by the bank. [See list of rejection codes](/api-documentation/cashouts-api/api-codes#cashout-rejection-error-codes) | | `rejection_reason` | String | Reason of the rejection if sent by the bank | ## Status Flow [Click here](/api-documentation/cashouts-api/api-codes#cashout-status-codes) to see each Cashout Status meaning. ### Cashout Status Flow ![Cashout Status Flow Diagram](/files/-MEhM7tjzaYE5_JN6TKA) {% hint style="info" %} 1. DECLINED: The DECLINED status is not a status by itself. It means the transaction couldn't be created because of an error with the data, the customer or the merchant configuration. No transaction will change its status from DECLINED. 2. PENDING: Once the cashout is in PENDING status, it means it was successfully created and that it will be send for processing soon, changing to DELIVERED. It can also be manually changed to ON\_HOLD or CANCELLED. 3. ON\_HOLD: A cashout will be created with ON\_HOLD status only if specified while creating the cashout with *on\_hold: true.* Otherwise, it can be manually set to ON\_HOLD from the Merchant Panel. If a cashout is ON\_HOLD, it won't be send for processing until you manually go and set it to PENDING from the Merchant Panel. It can still be CANCELLED. 4. CANCELLED: It means you didn't want to proceed with the cashout and it was CANCELLED through the Merchant Panel or through the Cancel Cashout Endpoint. Final status. 5. DELIVERED: As soon as the cashout is sent to the bank for processing, its status will change to DELIVERED. At which point it can't be cancelled anymore. 6. COMPLETED: If the cashout was successfully completed, its status will be set to COMPLETED. Final status\*. 7. REJECTED: If the cashout was rejected by the bank, its status will be set to REJECTED. Final status. {% endhint %} * There are cases in which the bank confirms us that a payout was successful and after a few days, it gets rejected by the beneficiary's bank therefore the status on our platform will change to REJECTED as well. Those are very corner cases but should be considered. ## Status codes Check all the possible status codes in the following page: {% content-ref url="/pages/-M9uqleE2Ysi\_e8bMH3B" %} [API Codes](/api-documentation/cashouts-api/api-codes) {% endcontent-ref %} # Cashout Update Status Endpoint Learn how to use the endpoint to update the status of a cashout ## Cashout Update Status Endpoint `PUT` `https://api-stg.onekeypayments.com/v3/cashout/status` This API allows you to change the status of a cashout #### Headers | Name | Type | Description | | --------------------------------------------------- | ------ | ------------------ | | Content-Type\* | string | `application/json` | | Payload-Signature\* | string | Control Signature | #### Request Body | Name | Type | Description | | --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | | login\* | String | Your D24 CASHOUTS API login key | | pass\* | string | Your D24 CASHOUTS API pass key | | cashout\_id\* | number | The ID of the cashout to asign status to. It is the one generated by D24 when the cashout was created | | status\* | string | The status to be assigned to the cashout | {% tabs %} {% tab title="200 The status of the cashout was successfully retrieved" %} ```java { "cashout_status": 1, "cashout_status_description": "Completed" } { "cashout_status": 3, "cashout_status_description": "Rejected", "rejection_code": 0, "rejection_reason": "Test" } ``` {% endtab %} {% tab title="401 Invalid credentials error" %} ```java { "code": 401, "message": "Invalid credentials." } ``` {% endtab %} {% tab title="412 The cashout ID was not found" %} ```java { "code": 509, "message": "Cashout not found with this ID" } ``` {% endtab %} {% endtabs %} ## Introduction This API is used to update a cashout from PENDING to ON\_HOLD or from ON\_HOLD to PENDING. A cashout in ON\_HOLD won't be processed until you set it back to PENDING. This is useful in cases where you need to perform some form of KYC over the beneficiary before proceeding with the request. You can create a cashout in ON\_HOLD by specifying the flag `on_hold: true` on the [cashout creation request](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint). {% hint style="info" %} Only cashouts in PENDING status can be updated to ON\_HOLD. Once the cashout was sent to the bank, it will change to DELIVERED at which point it can't be cancelled anylonger {% endhint %} If a cashout is ON\_HOLD and you would like to definitely cancel it, please see the [Cashout Cancellation Endpoint](/api-documentation/cashouts-api/endpoints/cashout-cancel-endpoint) {% hint style="warning" %} Cashouts in ON\_HOLD retain the amounts from your balance, so be careful to not accumulate cashouts in this status for long time. {% endhint %} ## Cashout Update Status Request ### Request Example ```java // HEADERS Content-Type: application/json Payload-Signature: 2e5023770760ea0a02230bff1a6dab934fe3b47a5e3d43854b58676600ee3868 // BODY { "login": "cashout_login", "pass": "cashout_pass", "cashout id": "97875" "status": "ON_HOLD" } ``` ### Request Fields Description | Field | Format | Description | | ------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `login` | String. Length 32 max | Your OKP **CASHOUTS** API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials | | `pass` | String. Length 32 max | Your OKP **CASHOUTS** API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials | | `cashout_id` | Number | Identifier of the cashout on OKP end. It is the one returned by the [Create Cashout Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint) | | `status` | String | Status to be assigned to the cashout. Valid values: `PENDING`, `ON_HOLD` | ### ### Request Payload Signature The Payload-Signature of the Cashout Update Status Endpoint is calculated by hashing the whole JSON payload of the request using HMAC256 and your secret key (API Signature) to encrypt it. [Click here](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) for further instructions. ## Cashout Update Status Response ### Error Response Example ```java { "code": 510, "message": "Invalid status transition" } ``` | `code` | Number | Error code | | --------- | ------ | ------------------------ | | `message` | String | Description of the error | ## Status Flow [Click here](/api-documentation/cashouts-api/api-codes#cashout-status-codes) to see each Cashout Status meaning. ### Cashout Status Flow ![Cashout Status Flow Diagram](/files/-MEhM7tjzaYE5_JN6TKA) {% hint style="info" %} 1. DECLINED: The DECLINED status is not a status by itself. It means the transaction couldn't be created because of an error with the data, the customer or the merchant configuration. No transaction will change its status from DECLINED. 2. PENDING: Once the cashout is in PENDING status, it means it was successfully created and that it will be send for processing soon, changing to DELIVERED. It can also be manually changed to ON\_HOLD or CANCELLED. 3. ON\_HOLD: A cashout will be created with ON\_HOLD status only if specified while creating the cashout with *on\_hold: true.* Otherwise, it can be manually set to ON\_HOLD from the Merchant Panel. If a cashout is ON\_HOLD, it won't be send for processing until you manually go and set it to PENDING from the Merchant Panel. It can still be CANCELLED. 4. CANCELLED: It means you didn't want to proceed with the cashout and it was CANCELLED through the Merchant Panel or through the Cancel Cashout Endpoint. Final status. 5. DELIVERED: As soon as the cashout is sent to the bank for processing, its status will change to DELIVERED. At which point it can't be cancelled anymore. 6. COMPLETED: If the cashout was successfully completed, its status will be set to COMPLETED. Final status\*. 7. REJECTED: If the cashout was rejected by the bank, its status will be set to REJECTED. Final status. {% endhint %} * There are cases in which the bank confirms us that a payout was successful and after a few days, it gets rejected by the beneficiary's bank therefore the status on our platform will change to REJECTED as well. Those are very corner cases but should be considered. ## Status codes Check all the possible status codes in the following page: {% content-ref url="/pages/-M9uqleE2Ysi\_e8bMH3B" %} [API Codes](/api-documentation/cashouts-api/api-codes) {% endcontent-ref %} # Cashout Cancellation Endpoint Learn how to use the Cashout Cancellation Endpoint to cancel cashouts when needed ## Cashout Cancellation Endpoint `DELETE` `https://api-stg.onekeypayments.com/v3/cashout/cancel` This API allows you to cancel a cashout request. Only for cashouts in **PENDING** state. #### Headers | Name | Type | Description | | --------------------------------------------------- | ------ | ------------------ | | Content-Type\* | string | `application/json` | | Payload-Signature\* | string | Control Signature | #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- | | login\* | string | Your D24 CASHOUTS API login key | | pass\* | string | Your D24 CASHOUTS API pass key | | cashout\_id\* | number | The ID of the cashout to cancel. It is the one generated by D24 when the cashout was created | | external\_id\* | string | The external ID of the cashout to cancel. It is the one you sent when generating the cashout | {% tabs %} {% tab title="200 Cashout cancelled" %} ```java { "cashout_status": 2, "cashout_status_description": "Canceled" } ``` {% endtab %} {% tab title="412 Error while cancelling the cashout. It can be cancelled only if its status is Pending" %} ```java { "code": 510, "message": "Invalid status transition" } ``` {% endtab %} {% endtabs %} ## Cancel Cashout Request The Cancel Cashout Request endpoint is only to cancel a cashout while it is still in PENDING state (it hasn't been sent for processing). To do that, you will need to provide both the cashout ID on our end and the external ID you sent while creating the cashout. {% hint style="info" %} The method to use this endpoint has to be **DELETE**. {% endhint %} ### ### Request Example ```java // HEADERS Content-Type: application/json Payload-Signature: 2e5023770760ea0a02230bff1a6dab934fe3b47a5e3d43854b58676600ee3868 // BODY { "login": "cashout_login", "pass": "cashout_pass", "cashout_id": 11954, "external_id": "cashoutID2134" } ``` ### Request Fields | Field | Format | Description | | ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `login` | String. Length 32 max | Your OKP **CASHOUTS** API Key, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials | | `pass` | String. Length 32 max | Your OKP **CASHOUTS** API Passphrase, it can be found on the Merchant Panel: Settings -> API Access. Notice there are specific Cashout credentials | | `cashout_id` | Number | Identifier of the cashout in the OKP end. Returned by the [Create Cashout Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint) | | `external_id` | String | The external ID of the cashout to cancel. It is the one you sent when [generating the cashout](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint) | ### Request Payload Signature The Payload-Signature of the Cashout Status Endpoint is calculated by hashing the JSON payload of the request using HMAC256 and your secret key (API Signature) to encrypt it. [Click here](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) for further instructions. ## Cancel Cashout Response ### Response Example ```java // Cashout cancelled successfully { "cashout_status": 2, "cashout_status_description": "Canceled" } // Cashout not found { "code": 509, "message": "Cashout not found with this ID" } // The cashout can't be cancelled because its status is not Pending { "code": 510, "message": "Invalid status transition" } ``` **Response fields** | Field | Format | Type | Description | | ---------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------- | | `cashout_status` | Number | Success | If shown, it is the new[ status code](/api-documentation/cashouts-api/api-codes#cashout-status-codes) of the cashout. | | `cashout_status_description` | String | Success | If shown, it described the new status of the cashout. | | `code` | Number | Error | Error code | | `message` | String | Error | Error description | # Cashout Bank Codes Learn how to use the Cashout Bank Codes Endpoint to retrieve the list of bank codes accepted for cashouts in each country ## Cashout Bank List `GET``https://api-stg.onekeypayments.com/v1/country/BR/authorized-banks` This API allows you to retrieve the list of banks available in each country #### Query Parameters | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------ | | country\* | string | Country ISO code, "BR" is for Brasil | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------ | | Authorization\* | string | Authorization Header. Format: "Bearer your\_read\_only\_key" | ## Introduction This endpoint is used to retrieve a list of all the current available banks in Brazil, In case we add or remove a bank, this endpoint will reflect those updates in real-time and therefore it is a good idea to constantly check this endpoint for the list of banks. Each bank includes information about our internal bank code, the ISPB code of the bank, name of the bank, and a check to see if the bank is licensed or not. The endpoint is read-only and so it uses a read-only key. It can be used from the front end without major security concerns. ## Bank Codes Request ### Request Example ```java // URL GET: https://api-stg.onekeypayments.com/v1/country/BR/authorized-banks // HEADERS Authorization: Bearer EKiFOWiHnI ``` ### Request Fields | Type | Field | Format | Description | | ----------- | --------------- | ------------------ | --------------------------------------------------------------------------------------------------- | | Query Param | `country` | String (length: 2) | [Country ISO code](/knowledge-base/countries-specifications#countries-and-currencies) | | Header | `Authorization` | String | Bearer Token Authentication. It is a concatenation of the word "Bearer" and your Read Only API Key. | ### Response Example ```json { "bank_code": xxx, "ispb_code": xxxxxxxx, "bank_name" : "XXXXXX", "bank_licensed": true|false } { "bank_code": xxx, "ispb_code": xxxxxxxx, "bank_name" : "XXXXXX", "bank_licensed": true|false } ``` ### **Response fields** | Field | Format | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `bank_code` | Number | Bank code. It is our internal code to identify a bank institution within our system. | | `ispb_code` | Number | "Identificador do Sistema de Pagamentos Brasileiro" - Unique 8 digit code that identifies a banking instituion in Brasil | | `bank_name` | String | Name of the bank | | `bank_licensed` | Boolean | `TRUE` or `FALSE` | ## Retrieve information for a specific bank `GET`` ``https://api-stg.onekeypayments.com/v1/country/{iso_code}/authorized-banks/{bank_code|ispb_code}` In case you need to retrieve the information for a specific bank, you can utilize this endpoint with either the bank's ISPB code or our internal bank code, [which is provided here](/api-documentation/cashouts-api/countries-validations/american-countries/brazil).\ \ **Example:** `GET`` ``https://api-stg.onekeypayments.com/v1/country/BR/authorized-banks/33`\
In this example, we would be utilizing the ISO code BR to indicate Brasil, and the "33" to indicate the internal bank code.\ \ Otherwise, if you would like to use the ISPB code, the endpoint would look like this:\ \ `https://api-stg.onekeypayments.com/country/BR/authorize-banks/90400888`\ \ **Response** ```json { "bank_code": 33, "ispb_code": 90400888, "bank_name" : "BANCO SANTANDER BRASIL S.A.", "bank_licensed": true } ``` # Countries Validations Learn about the cashouts requirements and validations made over each country in which we operate on. ## Introduction Check the cashouts requirements and validations made over each country in which we operate on. ### American Countries * [Bolivia](/api-documentation/cashouts-api/countries-validations/american-countries/bolivia) * [Brazil](/api-documentation/cashouts-api/countries-validations/american-countries/brazil) * [Canada](/api-documentation/cashouts-api/countries-validations/american-countries/canada) * [Chile](/api-documentation/cashouts-api/countries-validations/american-countries/chile) * [Colombia](/api-documentation/cashouts-api/countries-validations/american-countries/colombia) * [Dominican Republic](broken://pages/-MT2yOLLOaPeqH-OQUzH) * [Ecuador](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador) * [Mexico](/api-documentation/cashouts-api/countries-validations/american-countries/mexico) * [Panama](broken://pages/-MFSUZyrivnEZ_BfgUZS) * [Peru](/api-documentation/cashouts-api/countries-validations/american-countries/peru) * [Venezuela](broken://pages/M0h1smtnQBHUUBilhjYl) ### African Countries * [Cameroon](broken://pages/-MCdJzGnzjFV3Ubq2WtV) * [Ivory Coast](broken://pages/-MD6yuOVqwSrnrvz1LSo) * [Ghana](broken://pages/-MD6yuIYcZG339Rp0PHg) * [Kenya](broken://pages/-MD6yt16f4LmnEwUJmhY) * [Nigeria](broken://pages/-MD6yspLjImjDFiGGRH5) * [Tanzania](broken://pages/-MD6yshcibqRizu8dqak) * [Uganda](broken://pages/-MD6ysRSxEa8M_TQyP0L) ### Asian Countries * [India](broken://pages/-MD70wsOav-zReUGlOsm) * [Indonesia](broken://pages/-MD78N9p4_uAvNqbVMeD) * [Japan](broken://pages/-MVrmyj40HT8ybYwkDRi) * [Malaysia](broken://pages/-MD78NFXnQKELpB78535) * [Philippines](broken://pages/-MD78NP6fQcPaXStfYKh) * [Thailand](broken://pages/-MD78TlVNdXMQeMtuE6L) * [Vietnam](broken://pages/-MD78Memr7OP2LzaCIMc) # American Countries Learn about the cashouts validations of the American countries # Bolivia Check the requirements and validations made over the cashouts on Bolivia ## Required fields
FieldFormatDescription
FieldFormatDescription
loginStringCashouts login
passStringCashouts pass
external_idString (max length: 100)Transaction's ID on your end
document_typeSee document validationsBeneficiary's document type.
document_idSee document validationsBeneficiary's document ID.
countryBOSee country codes
currencyBOB / USDSee currency codes
amountNumber with up to 2 decimalsCashout amount
bank_codeSee bank codesCode specifying the beneficiary's bank
bank_accountSee validations belowBeneficiary's bank account
account_typeSee account type codesBeneficiary's bank account type
beneficiary_nameString (max length: 100)Beneficiary's name
## Bank Account Validations | Bank name | Bank code | Format | Example | | --------- | :-------: | ------------------------------------- | ---------- | | All | - | Numeric. Between 4 and 30 characters. | 1234567890 | ## Account Types The `account_type` is specified with only one character described below. | `account_type` | Description | | :------------: | ----------------- | | **`C`** | Checkings account | | **`S`** | Savings account | ## Example Request {% tabs %} {% tab title="Banks" %} ```java { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BO", "currency": "BOB", "amount": 100, "document_type": "PASS", "document_id": "B225255", "beneficiary_name": "User", "bank_account": "1234567890", "bank_code": "001", "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% endtabs %} ## Bank Codes | Bank | Code | | ---------------------------------------------------- | ---- | | Banco Nacional de Bolivia S.A. | 001 | | Banco PYME Ecofuturo S.A. | 002 | | Banco Mercantil Santa Cruz S.A. | 003 | | Almacenes Internacionales S.A. | 004 | | Banco de Crédito de Bolivia S.A. | 005 | | Warrant Mercantil Santa Cruz S.A. | 006 | | Banco de la Nación Argentina S. A. | 007 | | Banco Do Brasil S.A.- Sucursal Bolivia | 008 | | Banco BISA S.A. | 009 | | E-fectivo ESPM S.A. | 010 | | Banco Unión S.A. | 014 | | Banco Económico S.A. | 016 | | Banco Solidario S.A. | 017 | | Banco Ganadero S.A. | 018 | | Banco PYME de la Comunidad S.A. | 032 | | Banco para el Fomento a Iniciativas Económicas S.A. | 033 | | Banco Fortaleza S.A. | 034 | | Banco Fassil S.A. | 035 | | Banco Prodem S.A. | 036 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Brazil Check the requirements and validations made over the cashouts on Brazil ## Required fields | Field | Format | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's CPF. | | `country` | `BR` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `BRL` / `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_code` | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#bank-codes) | Code specifying the beneficiary's bank | | `bank_account` | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#bank-account-validations) | Beneficiary's bank account | | `bank_branch` | See [validations below](#bank-branch-validations) | Beneficiary's bank branch | | `account_type` | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/brazil#account-types) | Beneficiary's bank account type | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | ## Bank Account Validations | Bank name | Bank code | Format | Example | | ---------------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Banco do Brasil | 001 | Format: DDDDDDDDD-X or DDDDDDDDDX where D are digits and X is a digit or the letter 'X'. The number of digits may change, but can't exceed 10 digits | 1234567890, 123456789-0, 123456789-X, 123456789X | | Santander | 033 | Format: DDDDDDDDD, DDDDDDDDDD, DDDDDDDDD-D, DDDDDDDDD-D where D are digits. The number of digits may change, but will range from 9 to 10 digits. | 12345678, 12345678-9 | | Banrisul | 041 | Format: DDDDDDDDD-D or DDDDDDDDDD where D are digits. The number of digits has to be 10 | 1234567890, 123456789-0 | | Caixa | 104 | Format: DDDDDDDDD-D or DDDDDDDDDDDDDD-D where D are digits. The number of digits has to be between 1 and 20 |

1234567890,

123456789-0, 12345678901234-5

| | Bradesco | 237 | Format: DDDDDDD-D or DDDDDDDD where D are digits. The number of digits may change, but can't exceed 8 digits | 12345678, 1234567-8 | | Mercado Pago | 323 | Format: DDDDDDDDDD-D or DDDDDDDDDDD where D are digits. The number of digits may change, but can't exceed 11 digits | 12345678910, 1234567891-0 | | Itaú | 341 | Format: DDDDDD-D or DDDDDDD where D are digits. The number of digits may change, but will range from 6 to 7 | 123456, 12345-6 | | Pix Key Document | 10002 | Empty string | "" | | Pix Key Phone | 10000 | Empty string | | | Pix Key Email | 10001 | Empty string | | | Pix Key Random | 10003 | Empty string | | | Others | - | Format: DDDDDDDDDD-D or DDDDDDDDDDD where D are digits. The number of digits may change, but can't exceed 20 digits |

123456789, 123456789-0,
123456789012345689

| ## Bank Branch Validations
Bank nameBank codeFormatExceptions
Bank nameBank codeFormatExampleExceptions
Banco do Brasil001Format: DDDD-X or DDDDX where D are digits and X is a digit or the letter 'X'. The number of digits may change, but can't exceed 5 digits1234-1, 12341, 1234-X

Can't have 4 zeros and a digit.

^0{0,4}(-)?[\dxX]$

Santander033Format: DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234, 12345

Can't be 033

^033$

Banrisul041Format: DDDD or DDDD-D The number of digits may change, but can't exceed 5 digits1234-1, 12341N/A
Banco Inter077Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341

Can't start with zeros followed by 77

^0{0,3}77$

Caixa104Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341

Can't be: 001/013/023/104

^001$|^013$|^023$|^104$

Banco Original212Format: DDDDD-D or DDDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341

Can't start with zeros followed by 212

^0{0,2}212$

Bradesco237Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341

Can't be 237

^237$

Banco Nu Pagamento260Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341

Can't start with zeros followed by 260

^0{0,2}260$

PagSeguro290Format: DDD-D or DDDD where D are digits. The number of digits may change, but can't exceed 4 digits123-4, 1234

Can't start with zeros followed by 290

^0{0,2}290$

Mercado Pago323N/A0001N/A
Itau341Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341

Can't be 314

^341$

Pix Key Phone10000Format: "+55 012 92345-1234"+55 66 666666666N/A
Pix Key Email10001N/Atestuser@gmail.comN/A
Pix Key Document10002N/AN/AN/A
Others-Format: DDDD-D or DDDDD where D are digits. The number of digits may change, but can't exceed 5 digits1234-1, 12341N/A
## Account Types The `account_type` is specified with only one character described below. | `account_type` | Description | | :------------: | ----------------- | | **`C`** | Checkings account | | **`S`** | Savings account | | **`P`** | Payments account | [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Example Request {% tabs %} {% tab title="Banks" %} ```java { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BR", "currency": "BRL", "amount": 100, "document_id": "01716001340", "beneficiary_name": "User", "bank_account": "3423422-7", "bank_code": "001", "bank_branch": "1234", "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% tab title="Pix Keys" %} ### Type of keys | Bank | Bank Code | Details | | ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | Pix Key Document | 10002 | `bank_account` and `bank_branch` must be empty. The field `acount_type` can have any value. The field `document_id` must be sent | If a payout is created without `document_id` , it will get REJECTED. ### Example Requests {% code title="Pix Key Document" %} ```java { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BR", "currency": "BRL", "amount": 100, "document_id": "01716001340", "beneficiary_name": "User", "bank_code": "10002", "bank_account": "", "bank_branch": "", "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endcode %} {% endtab %} {% endtabs %} ## Types of Keys | Bank | Bank Code | Bank Details | | ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pix Key Phone | 10000 | `bank_account` and `bank_branch` must be empty. The field `acount_type` can have any value. The field phone must be sent | | Pix Key Email | 10001 | `bank_account` and `bank_branch` must be empty. The field `acount_type` can have any value. The field email must be sent | | Pix Key Document | 10002 | `bank_account` and `bank_branch` must be empty. The field `acount_type` can have any value. The field `document_id` must be sent | | Pix Key Random | 10003 | `bank_branch` must be empty. The field `account_type` can have any value. The field `bank_account` must be sent - this indicates the customer's PIX random key | If a payout is created without the mandatory fields, it will be rejected.
{% tabs %} {% tab title="Pix Key Phone" %} ```json { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BR", "currency": "BRL", "amount": 100, "document_id": "01716001340", "beneficiary_name": "User", "phone": "+5511666666666" "bank_code": "10000", "bank_account": "", "bank_branch": "", "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% tab title="Pix Key Email" %} ```json { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BR", "currency": "BRL", "amount": 100, "document_id": "01716001340", "email": "testuser@gmail.com", "beneficiary_name": "User", "bank_code": "10001", "bank_account": "", "bank_branch": "", "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% tab title="Pix Key Document" %} ```json { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BR", "currency": "BRL", "amount": 100, "document_id": "01716001340", "beneficiary_name": "User", "bank_code": "10002", "bank_account": "", "bank_branch": "", "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% endtabs %} ### Registred bank accounts For withdrawals, it is possible to send the registered accounts of a customer, before creating a cashout, you can find all the information [about the fields here](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#request-fields-description), under the registered\_bank\_accounts object.\ \ You can have up to 3 bank accounts registered under this object.\ \ **Example** ```json { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "BR", "currency": "BRL", "amount": 100, "document_id": "01716001340", "beneficiary_name": "User", "bank_account": "3423422-7", "bank_code": "001", "bank_branch": "1234", "registered_bank_accounts": [ { "account_number": "3423422-7", "ispb_code": "00000000", "bank_code": "001", "bank_branch": "1234" }, { "account_number": "1234567", "ispb_code": "90400888", "bank_code": "33", "bank_branch": "0199" } ], "account_type": "C", "notification_url": "https://webhook.site/url", "type": "json" } ``` ## Bank Codes | Bank | Code | | ------------------------------------------------------- | ----- | | BANCO DO BRASIL S.A. | 001 | | BANCO DA AMAZONIA S.A. | 003 | | BANCO DO NORDESTE DO BRASIL S.A. | 004 | | BANESTES S.A. BANCO DO ESTADO DO ESPIRITO SANTO | 021 | | Banco Alfa S.A. | 025 | | BANCO SANTANDER BRASIL S.A. | 033 | | BANCO ABN AMRO S.A | 033 | | BANCO DO ESTADO DO PARA S.A. - BANPARA | 037 | | BANCO DO ESTADO DO RIO GRANDE DO SUL S.A. - BANRISUL | 041 | | BANCO DO ESTADO DE SERGIPE S.A. - BANESE | 047 | | BANCO DE BRASILIA S.A. - BRB | 070 | | BANCO INTER | 077 | | Banco Original do Agronegócio S.A. | 079 | | Cooperativa Central de Crédito (VIACREDI) | 085 | | POLOCRED SCMEPP | 093 | | Credisis - Central de Cooperativas de Crédito Ltdav | 097 | | XP INVESTIMENTOS S.A | 102 | | CAIXA ECONOMICA FEDERAL - CEF | 104 | | Banco BOCOM BBM S.A. | 107 | | BANCO AGIPLAN S.A. | 121 | | Confederação Nacional das Cooperativas Centrais Unicred | 136 | | Stone Pagamentos S.A | 197 | | Banco BTG Pactual S.A. | 208 | | BANCO ORIGINAL | 212 | | BANCO BONSUCESSO S.A. | 218 | | Banco Fibra S.A. | 224 | | BANCO BRADESCO S.A. | 237 | | NU PAGAMENTOS | 260 | | Will Financeira S.A. | 280 | | PagSeguro Internet S.A | 290 | | Banco BPP Instituição de Pagamento S/A | 301 | | BANCO BMG S.A | 318 | | China Construction Bank Banco Múltiplo S.A. | 320 | | MERCADOPAGO.COM REPRESENTACOES LTDA. | 323 | | BANCO BARI DE INVESTIMENTOS E FINANCIAMENTOS S.A | 330 | | BAcesso Soluções de Pagamento S.A | 332 | | Banco Digio S.A | 335 | | BANCO C6 S.A | 336 | | ITAU UNIBANCO S.A. | 341 | | GERENCIANET S.A | 364 | | Banco Société Générale Brasil S.A. | 366 | | PICPAY SERVICOS S.A | 380 | | BANCO MERCANTIL DO BRASIL S.A. | 389 | | Banco Hub pagamentos SA | 396 | | HSBC BANK BRASIL S.A. - BANCO MULTIPLO | 399 | | CORA SCD S.A | 403 | | BANCO SAFRA S.A. | 422 | | CITIBANK N.A. | 477 | | Deutsche Bank S.A. – Banco Alemão | 487 | | JPMorgan Chase Bank, National Association | 488 | | ING Bank N.V. | 492 | | Banco Credit Suisse S.A. | 505 | | Banco PAN S.A. | 623 | | BANCO SOFISA | 637 | | Banco Votorantim S.A. | 655 | | BANCO DAYCOVAL S.A. | 707 | | BANCO OURINVEST S.A | 712 | | BANCO CITIBANK | 745 | | BANCO MODAL S.A. | 746 | | Banco Rabobank International Brasil S.A. | 747 | | BANCO COOPERATIVO SICREDI S.A. | 748 | | Banco BNP Paribas Brasil S.A. | 752 | | BANCO COOPERATIVO DO BRASIL S/A - BANCOOB | 756 | | Pix Key Document | 10002 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Canada Check the requirements and validations made over the cashouts on Canada ## Required fields | Field | Format | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID | | `country` | `CA` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `CAD` / `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_code` | [Valid](/api-documentation/cashouts-api/countries-validations/american-countries/canada#bank-codes) bank code | Code specifying the beneficiary's bank | | `bank_account` | [Valid](/api-documentation/cashouts-api/countries-validations/american-countries/canada#bank-account-validations) bank account | Beneficiary's bank account | | `bank_branch` | [Valid](/api-documentation/cashouts-api/countries-validations/american-countries/canada#bank-branch-validations) institute number | Beneficiary's institute number | | `email` | [Valid](/knowledge-base/countries-specifications#emails-validations) email address | Beneficiary's email address | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | | `beneficiary_lastname` | String (max length: 100) | Beneficiary's last name | ## Bank Account Validations
Bank nameBank codeFormatExampleRegex
Bank nameBank codeFormatExampleRegex
Etransfer10000For Etransfer, the bank_account must come empty: "" (Not null)^$
Others-Numeric between 3 and 16 digits.738746356473^\d{3,16}$
## Bank Branch Validations
Bank nameBank codeFormatExampleRegex
Bank nameBank codeFormatExampleRegex
Etransfer10000For Etransfer, the bank_branch must come empty: ""(Not null)^$
Others-String of 5 characters12345^[\s\S]{5}$
## Email validations | Bank name | Bank code | Required | Example | | --------- | :-------: | :------: | ---------------------- | | Etransfer | 10000 | Yes | | | Others | - | No | - | ## Document Validations [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Example Request {% tabs %} {% tab title="Etransfer" %} ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "CA", "currency": "CAD", "amount": 100, "document_id": "5676586998", "bank_account": "", "bank_code": "10000", "bank_branch": "", "email": "johnSmith@gmail.com", "beneficiary_name": "John", "beneficiary_lastname": "Smith", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% tab title="Banks" %} ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "CA", "currency": "CAD", "amount": 100, "document_id": "5676586998", "bank_account": "38749027362", "bank_code": "001", "bank_branch": "12345", "email": "johnSmith@gmail.com", "beneficiary_name": "John", "beneficiary_lastname": "Smith", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% endtabs %} ## Bank Codes {% hint style="success" %} * **Etransfer approval time:** Up to one business day * **Banks approval time:** Up to four business days {% endhint %} | Bank Name | Code | | ----------------------------------------------------------------------- | ----- | | Etransfer | 10000 | | BANK OF MONTREAL | 001 | | THE BANK OF NOVA SCOTIA | 002 | | ROYAL BANK OF CANADA | 003 | | THE TORONTO-DOMINION BANK | 004 | | BANQUE NATIONALE DU CANADA | 006 | | CANADIAN IMPERIAL BANK OF COMMERCE | 010 | | HSBC BANK CANADA | 016 | | CANADIAN WESTERN BANK | 030 | | BANQUE LAURENTIENNE DU CANADA | 039 | | BANK OF CANADA | 177 | | CANADA SAVINGS BOND REDEMPTION CERTIFICATE | 187 | | ATB FINANCIAL | 219 | | BANK OF AMERICA NATIONAL ASSOCIATION | 241 | | THE BANK OF NEW YORK MELLON | 242 | | THE BANK OF TOKYO-MITSUBISHI UFJ LTD | 245 | | BARCLAYS BANK OF CANADA | 248 | | BNP PARIBAS | 250 | | CITIBANK CANADA | 260 | | DEUTSCHE BANK AG | 265 | | MEGA INTERNATIONAL COMMERCIAL BANK (CANADA) | 269 | | JPMORGAN CHASE BANK, NATIONAL ASSOCIATION | 270 | | KEB HANA BANK CANADA | 275 | | MIZUHO CORPORATE BANK LTD CANADA BRANCH | 277 | | NATIONAL BANK OF GREECE (CANADA) | 286 | | UBS BANK (CANADA) | 290 | | SBI CANADA BANK | 294 | | SUMITOMO MITSUI BANKING CORPORATION CAN. | 301 | | AMEX BANK OF CANADA | 303 | | INDUSTRIAL AND COMMERCIAL BANK OF CHINA | 307 | | BANK OF CHINA (CANADA) | 308 | | CITIZENS BANK OF CANADA | 309 | | FIRST NATIONS BANK OF CANADA | 310 | | BOFA CANADA BANK | 311 | | JP MORGAN BANK CANADA | 314 | | CTBC BANK CORP. (CANADA) | 315 | | HABIB CANADIAN BANK | 321 | | CAPITAL ONE BANK (CANADA BRANCH) | 323 | | STATE STREET | 327 | | CITIBANK, NA | 328 | | COMERICA BANK | 330 | | FIRST COMMERCIAL BANK | 332 | | VERSABANK | 334 | | UNITED OVERSEAS BANK LIMITED | 335 | | CANADIAN TIRE BANK | 338 | | ICICI BANK CANADA | 340 | | ZAG BANK | 342 | | HOLLIS CANADIAN BANK | 343 | | SOCIETE GENERALE (CANADA BRANCH) | 346 | | DIRECTCASH BANK | 352 | | SHINHAN BANK CANADA | 355 | | HOME BANK | 361 | | WELLS FARGO BANK NA CANADIAN BRANCH | 362 | | CHINA CONTRUCTION BANK (TORONTO BRANCH) | 366 | | WEALTH ONE BANK OF CANADA | 370 | | BANK OF CHINA (TORONTO BRANCH) | 372 | | TRUST GENERAL INC | 506 | | COMMUNITY TRUST COMPANY LTD | 507 | | THE CANADA TRUST COMPANY | 509 | | TRUST LA LAURENTIENNE | 522 | | THE EFFORT TRUST COMPANY | 532 | | HOME SAVINGS AND LOAN CORPORATION | 535 | | INVESTORS GROUP TRUST COMPANY LTD | 536 | | MANULIFE BANK OF CANADA | 540 | | MONTREAL TRUST COMPANY | 544 | | MENNONITE TRUST LIMITED | 547 | | CIBC TRUST CORPORATION | 548 | | MONTREAL TRUST COMPANY OF CANADA | 550 | | SUN LIFE FINANCIAL TRUST INC. | 551 | | PEACE HILLS TRUST COMPANY | 568 | | ROYAL TRUST COMPANY (THE) | 570 | | ROYAL TRUST COMPANY (THE) | 580 | | NATIONAL TRUST COMPANY | 590 | | CS ALTERNA BANK | 608 | | TANGERINE BANK | 614 | | B2B BANK | 618 | | PEOPLES TRUST COMPANY | 621 | | EQUITABLE BANK | 623 | | MANULIFE TRUST COMPANY | 626 | | THE TORONTO-DOMINION BANK | 715 | | LATVIAN CREDIT UNION LTD | 803 | | DUCA FINANCIAL SERVICES CREDIT UNION LTD | 806 | | CENTRAL 1 CREDIT UNION | 809 | | ALL TRANS FINANCIAL SERVICES CREDIT UNION LTD | 810 | | AAA GROUP CLEARER NOT UNIQUE | 815 | | CAISSE FINANCIAL GROUP | 819 | | CREDIT UNIONS IN NOVA SCOTIA | 821 | | CENTRAL 1 CREDIT UNION | 828 | | FEDERATION DES CAISSES POPULAIRES DE L'ONTARIO | 829 | | CREDIT UNIONS IN NEW BRUNSWICK | 831 | | COMMUNITY FIRST - A DIVISION OF YOUR NEIGHBOURHOOD CREDIT UNION LIMITED | 834 | | CAISSE POPULAIRE DE KAPUSKASING LIMITEE | 836 | | MERIDIAN CREDIT UNION LIMITED | 837 | | CREDIT UNION CENTRAL OF NOVA SCOTIA | 839 | | DUNDALK DISTRICT CREDIT UNION LTD | 840 | | CREDIT UNIONS IN QUEBEC | 841 | | ALTERNA SAVINGS AND CREDIT UNION LTD | 842 | | RAPPORT CREDIT UNION | 846 | | BRUNSWICK CREDIT UNION FEDERATION LTD | 849 | | CREDIT UNIONS IN ONTARIO | 851 | | CONCENTRA BANK | 853 | | GOLDEN HORSESHOE CREDIT UNION LTD | 854 | | FEDERATION DES CAISSES POPULAIRES ACADIENNES | 865 | | CREDIT UNION CENTRAL OF MANITOBA | 879 | | CREDIT UNION CENTRAL OF SASKATCHEWAN | 889 | | L'ALLIANCE DES CAISSES POPULAIRES DE L'ONTARIO | 890 | | CENTRAL 1 CREDIT UNION ALBERTA | 899 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Chile Check the requirements and validations made over the cashouts on Chile ## Required fields | Field | Format | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID | | `country` | `CL` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `CLP` / `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_code` | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/chile#bank-codes) | Code specifying the beneficiary's bank | | `bank_account` | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/chile#bank-account-validations) | Beneficiary's bank account | | `account_type` | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/chile#account-types) | Beneficiary's bank account type | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | ## Bank Account Validations | Bank name | Bank code | Format | Regex | Example | | --------- | :-------: | ------- | ------------ | ---------- | | All | - | Numeric | `^\d{6,16}$` | 1234567890 | ## Account Types The `account_type` is specified with only one character as described below. | `account_type` | Description | | :------------: | ----------------- | | **`C`** | Checkings account | | **`S`** | Savings account | | **`V`** | Salary account | ## Document Validations [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Example Request ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "CL", "currency": "CLP", "amount": 100, "document_id": "56765869", "bank_account": "56687456", "bank_code": "001", "account_type": "C", "beneficiary_name": "User", "notification_url": "https://webhook.site/url", "type": "json" } ``` ## Bank Codes | Bank | Code | | --------------------------- | ---- | | Banco de Chile | 001 | | Banco Edwards | 001 | | Citi | 001 | | Banco Internacional | 009 | | Banco del Estado de Chile | 012 | | Scotiabank Sud Americano | 014 | | Banco Crédito e Inversiones | 016 | | Corpbanca Bank | 027 | | Banco Bice | 028 | | HSBC Bank | 031 | | Banco Santander- Santiago | 037 | | Banco Itaú | 039 | | ABN Amor Bank Chile | 046 | | Banco Security | 049 | | Banco Falabella | 051 | | Deutsche Bank | 052 | | Banco Ripley | 053 | | Radobank Chile | 054 | | Consorcio | 055 | | Banco Penta | 056 | | Banco Paris | 057 | | BCI (Mach) | 116 | | BBVA Banco Bhif | 504 | | Banco del Desarrollo | 507 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Colombia Check the requirements and validations made over the cashouts on Colombia ## Required fields | Field | Format | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#document-validations) | Beneficiary's document ID | | `document_type` | See [document validations](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#document-validations) | Beneficiary's document type | | `country` | `CO` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `COP` / `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_code` | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#bank-codes) | Code specifying the beneficiary's bank | | `bank_account` | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#bank-account-validations) | Beneficiary's bank account | | `account_type` | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#account-types) | Beneficiary's bank account type | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | | `beneficiary_lastname` | String (max length: 100) | Beneficiary's last name | | `address` | String (max length: 255) | Beneficiary's address | | `phone` | String (max length: 20). [See validations](/api-documentation/cashouts-api/countries-validations/american-countries/colombia#phone-validations) | Beneficiary's phone number | ## Bank Account Validations
Bank nameBank codeFormatExampleRegex
Bank nameBank codeFormatExampleRegex
Nequi1507Customer's mobile phone5715551234^[\s\S]{1,20}$
Daviplata1551Customer's mobile phone5715551234^[\s\S]{1,20}$
D24 Card10001Empty string""^$
Su Red10002Empty string""^$
Efecty10003Empty string^$
Others-Numeric1234567890123^\d{8,19}$
## Account Types The `account_type` is specified with only one character as described below. | `account_type` | Description | | :------------: | ----------------- | | **`C`** | Checkings account | | **`S`** | Savings account | ## Document Validations [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Phone validations | Bank name | Bank code | Format | Required | Example | | --------- | :-------: | ------------------------------------------------------------------------------------------------------ | :------: | ------- | | Su Red | 10002 | [Valid phone number for Colombia.](/knowledge-base/countries-specifications#phone-numbers-validations) | Yes | | | Others | - | - | No | - | ## Example Request {% tabs %} {% tab title="Generic" %} ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "CO", "currency": "COP", "amount": 100, "document_id": "848392783", "document_type": "CC", "bank_account": "56687456", "bank_code": "001", "account_type": "C", "beneficiary_name": "User", "beneficiary_lastname": "Test", "address": "Calle 18, Colombia", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% tab title="Baloto / Su Red " %} ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "CO", "currency": "COP", "amount": 100, "document_id": "848392783", "document_type": "CC", "bank_account": "", "bank_code": "10000", // 10000 for Baloto, 10002 for Su Red "account_type": "S", "phone": "+5715551234", "beneficiary_name": "User", "beneficiary_lastname": "Test", "address": "Calle 18, Colombia", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% tab title="D24 Card" %} ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000002", "country": "CO", "currency": "COP", "amount": 100, "document_id": "848392783", "document_type": "CC", "bank_account": "", "bank_code": "10001", "account_type": "S", "beneficiary_name": "User", "beneficiary_lastname": "Test", "address": "Calle 18, Colombia", "notification_url": "https://webhook.site/url", "type": "json" } ``` {% endtab %} {% endtabs %} ## Bank Codes | Bank | Code | | ----------------------------------- | ----- | | BANCO DE BOGOTÁ | 001 | | BANCO POPULAR | 002 | | ITAÚ - Antes CORPBANCA | 006 | | BANCOLOMBIA | 007 | | CITIBANK | 009 | | HSBC | 010 | | BANCO SUDAMERIS | 012 | | BBVA | 013 | | ITAÚ (HELM) | 014 | | BANCO COLPATRIA | 019 | | BANCO DE OCCIDENTE | 023 | | BANCO CAJA SOCIAL BCSC | 032 | | BANCO AGRARIO | 040 | | BANCO DAVIVIENDA | 051 | | BANCO AV VILLAS | 052 | | BANCO PROCREDIT | 058 | | BANCO PICHINCHA | 060 | | BANCOOMEVA | 061 | | BANCO FALABELLA S.A | 062 | | SANTANDER | 065 | | COOPCENTRAL S.A | 076 | | Directa24 | 100 | | COOPERATIVA FINANCIERA DE ANTIOQUIA | 283 | | COTRAFA COOPERATIVA FINANCIERA | 289 | | CONFIAR | 292 | | NEQUI | 1507 | | DAVIPLATA | 1551 | | Su Red | 10002 | | Efecty | 10003 | | TPAGA Wallet | 10005 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Ecuador Check the requirements and validations made over the cashouts on Ecuador ## Required fields | Field | Format | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID | | `country` | `EC` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_code` | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador#bank-codes) | Code specifying the beneficiary's bank | | `bank_account` | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador#bank-account-validations) | Beneficiary's bank account | | `account_type` | See [account type codes](/api-documentation/cashouts-api/countries-validations/american-countries/ecuador#account-types) | Beneficiary's bank account type | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | | `beneficiary_lastname` | String (max length: 100) | Beneficiary's last name | ## Bank Account Validations
Bank nameBank codeFormatExampleRegex
Bank nameBank codeFormatExampleRegex
All-Numeric between 5 and 20 digits1234567890^\d{5,20}$
## Account Types The `account_type` is specified with only one character as described below. | `account_type` | Description | | :------------: | ----------------- | | **`C`** | Checkings account | | **`S`** | Savings account | ## Document Validations [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Example Request ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "EC", "currency": "USD", "amount": 100, "document_id": "0809283023", "bank_account": "56687456387234", "bank_code": "001", "account_type": "C", "beneficiary_name": "John", "beneficiary_lastname": "Smith", "notification_url": "https://webhook.site/url", "type": "json" } ``` ## Bank Codes | Bank | Code | | ------------------------------------ | ---- | | Banco Central del Ecuador | 001 | | Banco Pichincha C.A. | 010 | | Banco de Guayaquil S.A | 017 | | Banco City Bank | 024 | | Banco Machala | 025 | | Banco de Loja | 029 | | Banco del Pacifico | 030 | | Banco Internacional | 032 | | Banco Amazonas | 034 | | Banco del Austro | 035 | | Produbanco / Promerica | 036 | | Banco Bolivariano | 037 | | Comercial de Manabi | 039 | | Banco General Ruminahui S.A. | 042 | | Banco del Litoral S.A. | 043 | | Banco Solidario | 059 | | Banco Procredit S.A. | 060 | | Banco Capital | 061 | | Banco Desarrollo de Los Pueblos S.A. | 065 | | Banecuador B.P. | 066 | | Banco Delbank S.A. | 201 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Mexico Check the requirements and validations made over the cashouts on Mexico ## Required fields | Field | Format | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID | | `country` | `MX` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `MXN` / `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_code` | See [bank codes](/api-documentation/cashouts-api/countries-validations/american-countries/mexico#bank-codes) | Code specifying the beneficiary's bank. **Only mandatory if the bank\_account is a debit card** | | `bank_account` | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/mexico#bank-account-validations) | Beneficiary's bank account | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | | `beneficiary_lastname` | String (max length: 100) | Beneficiary's last name | ## Bank Account Validations | Bank name | Bank code | Format | Example | | --------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | All | - | [CLABE](https://en.wikipedia.org/wiki/CLABE): 18 digits long, applies verifier algorithm. | 021790064060296642 | | All | - | [DEBIT CARD](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#cashouts-to-debit-cards): 15-16 digits long, applies verifier algorithm. Can only be sent through [the Cashout to Debit Cards Endpoint](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#cashouts-to-debit-cards). | 5344867217683750 | | Todito | 10000 | 10 digits long. | 2682883311 | ### CLABE validation algorithm [Click here](https://en.wikipedia.org/wiki/CLABE) for more information about CLABE format. Since the first three digits of the CLABE are the bank code, it is not mandatory to send the `bank_code` field. {% tabs %} {% tab title="Java" %} {% code title="Mexico CLABE validation algorithm in Java" %} ```java public final class Validations { static int CLABE_LENGTH = 18; private static boolean validateClabeLength(String bankAcount) { return bankAcount.length() == CLABE_LENGTH; } private static boolean validateClabe(String clabe) { if (!validateClabeLength(clabe)) { return false; } else { int sum = 0; String clabeWithoutCd = clabe.substring(0, 17); Integer[] array = new Integer[]{3, 7, 1}; int checkDigitToVerify; for(checkDigitToVerify = 0; checkDigitToVerify < clabeWithoutCd.length(); ++checkDigitToVerify) { int digit = clabeWithoutCd.charAt(checkDigitToVerify); sum += digit * array[checkDigitToVerify % 3] % 10; } checkDigitToVerify = (10 - sum % 10) % 10; int checkDigit = Integer.parseInt(clabe.substring(17)); return checkDigitToVerify == checkDigit; } } } ``` {% endcode %} {% endtab %} {% endtabs %} ## Document Validations [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Example Request ```java { "login": "xxxxxxxx", "pass": "xxxxxxxx", "external_id": "30000000001", "country": "MX", "currency": "MXN", "amount": 100, "document_id": "848392783", "bank_account": "021790064060296642", "beneficiary_name": "User", "beneficiary_lastname": "Test", "notification_url": "https://webhook.site/url", "type": "json" } ``` ## Bank codes {% hint style="info" %} Notice that the bank\_code for Mexico is only mandatory if the bank\_account length is between 15 and 16 (Debit Card). In that case, [use the Credit Cards endpoint: https://cc-api-stg.directa24.com/v3/cashout](/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint#cashouts-to-debit-cards) {% endhint %} | Bank | Code | | ----------------------------------- | ----- | | BANAMEX | 002 | | BANCOMEXT | 006 | | BANOBRAS | 009 | | BBVA BANCOMER | 012 | | SANTANDER | 014 | | BANJERCITO | 019 | | HSBC | 021 | | BAJIO | 030 | | IXE | 032 | | INBURSA | 036 | | INTERACCIONES | 037 | | MIFEL | 042 | | SCOTIABANK | 044 | | BANREGIO | 058 | | INVEX | 059 | | BANSI | 060 | | AFIRME | 062 | | BANORTE | 072 | | THE ROYAL BANK | 102 | | AMERICAN EXPRESS | 103 | | BAMSA | 106 | | TOKYO | 108 | | JP MORGAN | 110 | | BMONEX | 112 | | VE POR MAS | 113 | | ING | 116 | | DEUTSCHE | 124 | | CREDIT SUISSE | 126 | | AZTECA | 127 | | AUTOFIN | 128 | | BARCLAYS | 129 | | COMPARTAMOS | 130 | | BANCO FAMSA | 131 | | BMULTIVA | 132 | | ACTINVER | 133 | | WALMART | 134 | | NAFIN | 135 | | INTERBANCO | 136 | | BANCOPPEL | 137 | | ABC CAPITAL | 138 | | UBS BANK | 139 | | CONSUBANCO | 140 | | VOLKSWAGEN | 141 | | CIBANCO | 143 | | BBASE | 145 | | BANSEFI | 166 | | HIPOTECARIA FEDERAL | 168 | | MONEXCB | 600 | | GBM | 601 | | MASARI | 602 | | VALUE | 605 | | ESTRUCTURADORES | 606 | | TIBER | 607 | | VECTOR | 608 | | B\&B | 610 | | MERRILL LYNCH | 615 | | FINAMEX | 616 | | VALMEX | 617 | | UNICA | 618 | | MAPFRE | 619 | | PROFUTURO | 620 | | CB ACTINVER | 621 | | OACTIN | 622 | | SKANDIA VIDA | 623 | | CBDEUTSCHE | 626 | | ZURICH | 627 | | ZURICHVI | 628 | | SU CASITA | 629 | | CB INTERCAM | 630 | | CI BOLSA | 631 | | BULLTICK CB | 632 | | STERLING | 633 | | FINCOMUN | 634 | | HDI SEGUROS | 636 | | ORDER | 637 | | NUBANK | 638 | | CB JPMORGAN | 640 | | REFORMA | 642 | | STP | 646 | | TELECOMM | 647 | | EVERCORE | 648 | | SKANDIA OPERADORA | 649 | | SEGMTY | 651 | | ASEA | 652 | | KUSPIT | 653 | | SOFIEXPRESS | 655 | | UNAGRA | 656 | | OPCIONES EMPRESARIALES DEL NOROESTE | 659 | | LIBERTAD | 670 | | CLS | 901 | | INDEVAL | 902 | | Todito | 10000 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # Paraguay Check the list of Payment Methods available on Paraguay ### Payment Methods
Iconpayment_methodNameFlowPayment TypeAvailable for testIframe supported
TRBank TransferREDIRECT
ONE_SHOT		BANK_TRANSFERYesYes
{% hint style="success" %} Use the [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to retrieve the Payment Methods' types, logos, and more details. {% endhint %} ### Fields required for the [OneShot Experience](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#oneshot-experience)
Payment Method Namecountryamountpayer[]payment_method
AllYesYesYesYes
### Payer object requirements | Payment Method Name | document | email | first\_name | last\_name | | ------------------- | :------: | :---: | :---------: | :--------: | | All | Yes | Yes | Yes | Yes | {% hint style="success" %} Other fields not in these lists are optional. {% endhint %} # Peru Check the requirements and validations made over the cashouts on Peru ## Required fields | Field | Format | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `login` | String | Cashouts login | | `pass` | String | Cashouts pass | | `external_id` | String (max length: 100) | Transaction's ID on your end | | `document_id` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document ID | | `document_type` | See [document validations](/knowledge-base/countries-specifications#documents-validations) | Beneficiary's document type | | `country` | `PE` | See [country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `currency` | `PEN` / `USD` | See [currency codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `amount` | Number with up to 2 decimals | Cashout amount | | `bank_account` | See [validations below](/api-documentation/cashouts-api/countries-validations/american-countries/peru#bank-account-validations) | Beneficiary's bank account | | `account_type` | See[ account types](/api-documentation/cashouts-api/countries-validations/american-countries/peru#account-types) | Beneficiary's bank account type | | `beneficiary_name` | String (max length: 100) | Beneficiary's name | | `beneficiary_lastname` | String (max length: 100) | Beneficiary's last name | ## Bank Account Validations | Bank name | Bank code | Description | Format | Example | | --------- | :-------: | ------------------------------------ | ---------------------------------------------------------------------------- | -------------------- | | All | - | CCI - Código de Cuenta Interbancaria | Length 20 (with verifying digits - a validation algorithm is ran over these) | 00219300153895206813 | ### CCI validation algorithm Since the first three digits of the CCI are the bank code, it is not mandatory to send the `bank_code` field. However, we validate those 3 first digits to be a valid `bank_code`. {% tabs %} {% tab title="Java" %} {% code title="Peru CCI validation algorithm in Java" %} ```java public final class Validations { static Integer CCI_LENGTH_ST = 18; static Integer CCI_LENGTH_FST = 20; static String EMPTY_CHECK_DIGITS = "00"; public static boolean validateBankAccount(String bankAccount) { if (!ValidationsUtils.validateOnlyNumbers(bankAccount)) { return false; } else { int accountLength = bankAccount.length(); String lastDigits = bankAccount.substring(bankAccount.length() - 2); if (accountLength == CCI_LENGTH_ST && lastDigits.equals(EMPTY_CHECK_DIGITS)) { return true; } return validateCCI(bankAccount); } } //Validate CCI bank account public static boolean validateCCI(String cci) { if (validateCCILength(cci)) { String cciWithoutCheck = cci.substring(0, cci.length() - 2); String checkDigits = cci.substring(cci.length() - 2); String calculatedCheckDigits = getCciCheckDigits(cciWithoutCheck); return checkDigits.equals(calculatedCheckDigits); } return false; } public static boolean validateCCILength(String cci) { return cci.length() == CCI_LENGTH_FST; } public static String getCciCheckDigits(String cci) { int firstControlNumber = calculateCheckDigit(cci.substring(0, 6)); int secondControlNumber = calculateCheckDigit(cci.substring(6, 18)); return String.valueOf(firstControlNumber) + String.valueOf(secondControlNumber); } private static int calculateCheckDigit(String cci) { int total = 0; int factor = 1; for (int i = 0; i < cci.length(); i++) { String[] cciArray = cci.split(""); int num = Integer.parseInt(cciArray[i]); if (num * factor < 10) { total += (num * factor); } else { int product = (num * factor); String product_str = Integer.toString(product); int firstDigit = Integer.parseInt(product_str.substring(0, 1)); int lastDigit = product % 10; total += firstDigit + lastDigit; } factor = factor == 1 ? 2 : 1; } return (total % 10) > 0 ? 10 - (total % 10) : 0; } } ``` {% endcode %} {% endtab %} {% endtabs %} ## Account Types The `account_type` is specified with only one character as described below. | `account_type` | Description | | :------------: | ----------------- | | **`C`** | Checkings account | | **`S`** | Savings account | | **`M`** | Master account | ## Document Validations [Click here](/knowledge-base/countries-specifications#documents-validations) to check document types and validations. ## Example Request ```java { "login": "xxxxxxx", "pass": "xxxxxxx", "external_id": "30000000001", "country": "PE", "currency": "PEN", "amount": 100, "document_id": "848392783", "document_type": "CE", "bank_account": "00219300153895206813", "account_type": "C", "beneficiary_name": "User", "beneficiary_lastname": "Test", "notification_url": "https://webhook.site/url", "type": "json" } ``` ## Bank Codes | Bank | Code | | -------------------------------------------- | ---- | | Banco de Crédito del Peru | 002 | | Interbank | 003 | | Citibank | 007 | | Scotiabank | 009 | | BBVA Continental | 011 | | Banco de la Nación | 018 | | Banco de Comercio | 023 | | Banco Financiero | 035 | | Banco Interamericano de Finanzas (BIF) | 038 | | Crediscotia Financiera | 043 | | Mi Banco | 049 | | Banco GNB Peru S.A | 053 | | Banco Falabella | 054 | | Santander | 056 | | Caja Metropolitana de Lima | 800 | | Caja Municipal de Ahorro y Credito Piura SAC | 801 | | Caja Municipal de Ahorro y Crédito Trujillo | 802 | | Caja Municipal de Ahorro y Crédito Arequipa | 803 | | Caja Municipal de Ahorro y Crédito Sullana | 805 | | Caja Municipal de Ahorro y Crédito Cuzco | 806 | | Caja Municipal de Ahorro y Crédito Huancayo | 808 | {% hint style="info" %} For the full and most up-to-date list of banks and its codes, please check the [Cashout Bank Code endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) {% endhint %} # API Codes Learn about the API Codes returned by our Cashouts APIs ## **Cashout Status Codes** | Code | Meaning | Description | | :--: | :-----------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | | The cashout was accepted by OKP but it wasn't sent to the bank yet. It can still be Canceled. See [Cancel Cashout](/api-documentation/cashouts-api/endpoints/cashout-cancel-endpoint) | | 1 | | The money reached the customer's account | | 2 | | The cashout was cancelled by you | | 3 | | The cashout was rejected **by the bank** due to invalid bank account, account closed, etc. | | 4 | | The cashout was sent to the bank for processing. At this point it can't be cancelled anymore | | 5 | ![](/files/MUsyplC1BSBUM2PyZDm0) | Cashout set to on hold by you. It won't be processed until manually changed again to Pending status | ## **Cashout Rejection Error Codes** The error information is the one (if) provided by the Bank. | Code | Name | Description | | ---- | --------------------------------------- | -------------------------------------------------------------------- | | 800 | `ERROR_ACCOUNT_INCORRECT` | Invalid bank account | | 801 | `ERROR_ACCOUNT_CLOSED` | Bank account is closed | | 802 | `ERROR_AMOUNT_INCORRECT` | Invalid amount | | 803 | `ERROR_BANK_INVALID` | Invalid bank code | | 804 | `ERROR_BANK_BRANCH_INCORRECT` | Invalid bank branch | | 805 | `ERROR_BENEFICIARY_DOCUMENT_ID_INVALID` | Invalid beneficiary document | | 806 | `ERROR_BENEFICIARY_NAME_INCORRECT` | Beneficiary name doesn't match bank details | | 807 | `ERROR_REJECTED_BY_BANK` | Rejected by bank | | 808 | `ERROR_OTHER` | Other error | | 809 | `WITHDRAWAL_EXPIRED` | Withdrawal expired | | 810 | `LIMIT_EXCEEDED` | Beneficiary limit exceeded | | 811 | `RISK_POLICY` | Violates bank risk policy | | 812 | `BLOCKED_FROZEN_ACCOUNT` | Bank account blocked/frozen | | 813 | `DOCUMENT_ACCOUNT_MISMATCH` | Beneficiary document doesn't match bank details | | 814 | `INVALID_PIX_KEY` | Invalid Pix Key | | 815 | `INVALID_IFSC_CODE` | Invalid IFSC code | | 816 | `INVALID_ACCOUNT_OR_IFSC_CODE` | Invalid bank account or IFSC code | | 817 | `INVALID_NBIN` | Invalid NBIN | | 818 | `ACCOUNT_UNABLE` | The bank account is unable to receive transfers | | 819 | `INVALID_ACCOUNT_TYPE` | Invalid bank account type | | 820 | `REJECTED_BY_MERCHANT_REQUEST` | Rejected by merchant's request | | 823 | `REJECTED_BY_MERCHANT_REQUEST` | Email field cannot be empty | | 827 | `BANK_NOT_REGULATED` | The bank is not licensed to process this transaction | | 828 | `UNMATCHED_BANK_ACCOUNT` | The PIX key details do not match any of the registered bank accounts | ## **Cashout Internal Error Codes** | Code | Description | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 300 | Invalid params + \[param name] + \[reason] | | 302 | Invalid control string. [Click here for instructions](/api-documentation/cashouts-api/technical-and-security-aspects/calculating-the-payload-signature) | | 303 | Invalid bank code | | 401 | Invalid credentials | | 402 | Unregistered IP address (Go to API Access to whitelist the IP in the Merchant Panel) | | 502 | Invalid request body - Please check that the JSON is well formatted | | 503 | The transaction cannot be processed as the user has reached their financial capacity, please provide proof of winnings | | 504 | User unauthorized due to cadastral situation. | | 508 | Limit exceeded: {TRANSACTION\|DAILY\|MONTHLY\|USER MONTHLY QUANTITY} | | 509 | Cashout not found with this ID | | 510 | Invalid status: cashout is not Pending | | 511 | External ID already used | | 514 | Insufficient funds | | 515 | Invalid user status: {BLACKLISTED\|BLOCKED\|SUSPENDED} | | 518 | Country not available | | 519 | Merchant not enabled. Contact your Account Manager | | 524 | Invalid Credentials. Contact | | 525 | Close loop rejection | | 526 | Invalid currency | | 533 | Invalid Amount. The minimum amount is {currency} {amount} or equivalent in USD | | 537 | Could not make the cashout. Contact | | 538 | Invalid account status: {BLACKLISTED} | | 539 | Payout method unavailable. The country and/or bank selected is not available. Please check with your Account Manager | | 540 | Beneficiary email or phone is required | | 541 | email already used by another beneficiary | | 542 | phone already used by another beneficiary | | 543 | must be a[ valid phone number](/knowledge-base/countries-specifications#phone-numbers-validations) | | 565 | The bank is not licensed to process this transaction | | 566 | Bank Code disabled | | 702 | Could not cancel cashout | | 703 | Could not make the cashout. Contact | ## **Cashout Status Rejection Error Codes** The error information is the one (if) provided by the Bank. | Code | Name | Description | | ---- | --------------------------------------------------- | ------------------------------------------------------- | | 510 | `Invalid status transition` | Status transition does not meet cashout status workflow | | 509 | `Cashout not found with this ID` | There is no cashout under provided ID | | 521 | `Status ... not supported for this type of request` | Provided Status does not exist | ### Fraud Reason Codes for KYC Errors
Reason CodeHTTP CodeTypeMessageDescription
101400USER_REJECTED_KYC_CHECKTransaction related to blacklisted user.The transaction was rejected because one of its attributes was related to a blacklisted user
102400USER_REJECTED_KYC_CHECKEmail riskHigh risk detected by our fraud prevention engine related to the user's email address
103400USER_REJECTED_KYC_CHECKCredit card riskHigh risk detected by our fraud prevention engine related to the credit card used
104400USER_REJECTED_KYC_CHECKUser rejected after KYC checkUser rejected by our KYC controls
105400USER_REJECTED_KYC_CHECKUnderage user detectedUser does not meet the minimum age requirement
106400USER_REJECTED_KYC_CHECKMismatch between user name and document nameThe user's name does not match the name associated with the document provided
107400USER_REJECTED_KYC_CHECKDocument status is not OKSome irregularities have been detected while validating the document information
108400USER_REJECTED_KYC_CHECKPEP user detectedThe user is a Politically Exposed Person (PEP)
109400USER_REJECTED_KYC_CHECKHigh risk detectedHigh risk detected by our fraud prevention engine
110400USER_REJECTED_KYC_CHECKFailed biometric checkSomething went wrong while performing the biometric check on the user
111400USER_REJECTED_KYC_CHECKFailed OTP verificationSomething went wrong while performing the OTP check on the user
112400USER_REJECTED_KYC_CHECK3DS Authentication failedTransaction rejected due to failed 3DS
113400USER_REJECTED_KYC_CHECKDocument does not existInvalid Document
114400USER_REJECTED_KYC_CHECKUser rejected after CNPJ validationsInvalid/Irregular CNPJ (Brasil Only)
115400USER_REJECTED_KYC_CHECKInvalid document formatFormat of the provided document is invalid. (Mexico Only)
116400USER_REJECTED_KYC_CHECKSportsman UserSportsman User
117400USER_REJECTED_KYC_CHECKRelated to Sportsman UserRelated to Sportsman User
118400USER_REJECTED_KYC_CHECKNational Sanction ListUser has been identified on national sanction lists
119400USER_REJECTED_KYC_CHECKInternational Sanction ListsUser has been identified on international sanction lists
120400USER_REJECTED_KYC_CHECKRegulatory reasonsRejected due to regulatory reasons
121400USER_REJECTED_KYC_CHECKVelocity checkRejected due to velocity check
# Subscriptions API ## Overview The Subscriptions API provides a complete solution for managing the entire subscription lifecycle, from initial creation to status monitoring and cancellation.\ The following operations are included in our API 1. **Subscription Creation** -Create new subscriptions with predetermined billing frequencies 2. **Subscription Cancellation** - Terminate existing subscriptions when needed. 3. **Subscription Status** - Retrieve detailed information about existing subscriptions ## Key Features * **Multiple Integration Options**: Choose between OneShot Flow (redirect-based) or PCI Flow (direct card processing) based on your compliance status * **Flexible Billing Frequencies**: Support for DAILY, WEEKLY, MONTHLY, and ANNUALLY billing cycles * **Automatic Renewals**: Configure subscriptions to automatically renew or expire after a set period * **Webhook Notifications**: Receive real-time updates about payment and subscription status changes * **Comprehensive Reporting**: Access detailed information about subscription status and payment history ## Integration Flow A typical integration with the Subscriptions API follows this sequence: 1. **Create Subscription** (**`POST`** /v3/subscriptions) * Submit customer and billing information * For non-PCI flow: Redirect customer to payment page * For PCI flow: Submit payment details directly 2. **Monitor Status** (**`GET`** /v3/subscriptions/{id}) * Verify subscription activation * Check payment processing status 3. **Manage Lifecycle** (as needed) * Cancel subscription (**`DELETE`** /v3/subscriptions/{id}) * Check status changes (**`GET`** /v3/subscriptions/{id}) {% hint style="success" %} **Integration Requirements** To receive full integration approval and move to production, merchants must successfully implement **all core endpoints**. Our certification process requires demonstration of: 1. Successful [**subscription creation**](broken://pages/VNDXhgu3fIZthn1ebWG8) (either via OneShot or PCI flow) 2. Proper payment verification using the [**deposits status**](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) endpoint 3. Proper [**subscription status**](broken://pages/nwkAnRTCuFMTdnDCxd05) verification 4. Correct [**subscription cancellation**](broken://pages/rmzQFp0CXZpC0CTH7Hou) handling Only after all endpoints have been verified in the staging environment will merchants receive clearance to use the Subscriptions API in production. This ensures a complete integration that can properly manage the entire subscription lifecycle from creation to termination, including payment verification. {% endhint %} ### Subscription Creation Endpoints The API offers two distinct flows for creating subscriptions, catering to merchants with different PCI compliance levels: #### OneShot Flow (Non-PCI) For merchants without PCI certification, [this](broken://pages/oyb1RBbx84VBVE83WXha) flow allows subscription creation without handling sensitive payment data directly. **POST** `https://api-stg.onekeypayments.com/v3/subscriptions` The standard flow requires redirection to our secure payment page where customers can safely enter their payment details. All payment information is processed on our PCI-compliant servers. #### PCI Flow For PCI-certified merchants, [this](broken://pages/5WAIhpY6nhRwxkpRsoRJ) flow allows subscription creation with direct credit card submission. **POST** `https://cc-api-stg.onekeypayments.com/v3/subscriptions` The PCI flow enables merchants to collect and transmit credit card details directly within the API request, facilitating a seamless checkout experience without redirections. {% hint style="success" %} **Note:** To access the PCI flow, merchants must provide valid PCI AOC documentation and use the designated PCI endpoint. {% endhint %} ### Subscription Cancellation Endpoint [This](broken://pages/rmzQFp0CXZpC0CTH7Hou) endpoint enables merchants to cancel active subscriptions. **DELETE** `https://api-stg.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`** When a subscription is cancelled: * No further charges will be processed * The subscription status will change to `CANCELLED` * Existing transactions will remain unaffected. ### Deposit Status Endpoint [This](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) endpoint enables merchants to retrieve detailed information about a payment deposit associated with a subscription. **Note that those deposits will be generated automatically by the Subscription API.** **GET** `https://api-stg.onekeypayments.com/v3/deposits/`**`{deposit_id}`** The response includes comprehensive details about the deposit, including: * Payment status * Transaction amount * Payment method used * **Associated subscription ID** * Processing date and time * More information ### Subscription Status Endpoint [This](broken://pages/nwkAnRTCuFMTdnDCxd05) endpoint enables merchants to retrieve detailed information about a subscription. **GET** `https://api-stg.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`** The response includes comprehensive details about the subscription, including: * Current status * Payment history * Upcoming billing dates * Subscription terms ## Payment Notification Flow When a payment event occurs for a subscription, our system notifies you through this process: 1. **Payment Processing**: The system processes a payment (initial or recurring) 2. **Webhook Notification**: A notification is sent to your configured URL with a `deposit_id` 3. **Deposit Status Endpoint**: Query **GET** `v3/deposits/`**`{deposit_id}`** to get payment details.\ You can find details of the endpoint [here](/api-documentation/deposits-api/endpoints/deposit-status-endpoint). 4. **Subscription Identification**: The deposit response includes the related `subscription_id` 5. **Subscription Status Check**: Query **GET** `v3/subscriptions/`**`{subscription_id}`** to verify current status ## Subscription Lifecycle A typical subscription follows this lifecycle: 1. **Creation**: A subscription is created with customer, payment, and billing details 2. **Activation**: The initial payment is processed and the subscription becomes active 3. **Recurring Billing**: Payments are automatically processed according to the billing frequency 4. **Updates**: Subscription details may be modified (*coming soon*). 5. **Cancellation**: The subscription is terminated, stopping future payments. 6. **Completion**: The subscription reaches its natural end date (if not set to auto-renew) ## Authentication Requirements All Subscriptions API endpoints require the following [authentication](broken://pages/vFdXgiAjIGSHF4sv2ch5#headers) headers: * **X-Login**: Your merchant API key * **X-Date**: Current timestamp in ISO 8601 format * **Authorization**: Authentication hash * **Content-Type**: application/json ## Response Codes The API uses standard HTTP response codes and includes detailed information in the response body: * **2xx**: Success * **4xx**: Client errors (invalid input, authentication issues) * **5xx**: Server errors Each error response includes a code, description, and type field to help with troubleshooting. *** ## Getting Started To begin integrating with the Subscriptions API: 1. Review our [Technical and Security Aspects documentation](broken://pages/vFdXgiAjIGSHF4sv2ch5) 2. Implement the [Subscription Creation Endpoints](broken://pages/VNDXhgu3fIZthn1ebWG8) 1. Choose your integration method: OneShot or PCI! 3. Set up status monitoring and notifications. 4. Implement the [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) and [Subscription Status Endpoint](broken://pages/nwkAnRTCuFMTdnDCxd05). 5. Implement [Subscription Cancellation](broken://pages/rmzQFp0CXZpC0CTH7Hou) functionality 6. Configure webhook handling for real-time notifications # Technical and Security Aspects Learn about the technical and security aspects of our Deposits APIs ## Security Considerations * All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. * API requests without [Authentication](/api-documentation/deposits-api/technical-and-security-aspects/calculating-the-signature) will also fail. * You will be able to hit our APIs only from the IPs you have [previously whitelisted](/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting) on the Merchant Panel. ## Environments All the integration must be performed on our **TEST environment**, where you can perform your tests freely without risks of any kind. When you sign up with us, we will generate you an account on our STG environment where you will be able to: * See the transactions created * Approve and cancel transactions * Retrieve your API Keys * Whitelist your IPs, and more ### Endpoint domains Each environment has its own domain. The path of the [endpoints ](/api-documentation/deposits-api/endpoints)doesn't change. | Environment | Domain | | ----------- | -------------------------------------- | | Testing | `https://api-stg.onekeypayments.com/` | | Production | Provided once you complete the testing | {% hint style="info" %} Notes: * You will use the STG endpoints to integrate. * The STG and PROD environments are not communicated in any way. * No transaction created on the STG environment will be reflected on the PROD environment or vice versa. * The API Keys and configurations between environments are also different. {% endhint %} ## API Keys Our Deposits APIs uses API Keys in all of the requests to authenticate. Your API Keys can be retrieved from the Merchant Panel by going to Settings -> API Access. {% hint style="info" %} * The API Keys on the STG and PROD environments are different. {% endhint %} There are basically two set of credentials: * One API Key and one API Signature for POST operations. * One API Key key for read-only endpoints. Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). You must provide your API Key in all the requests as the basic auth username value. You do not need to provide a password. Your API Key must be sent in all the API calls using the X-Login field on the header of the request. Your API Keys, along with your [IP Addresses](/api-documentation/deposits-api/technical-and-security-aspects#ip-whitelisting) are your way to authenticate yourself, therefore, do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth. ## Headers All the requests sent through the API of Deposits v3 must have the following headers.
HeaderFormatMandatoryDescription
AuthorizationStringYes"D24 " plus a hash HMAC256 to verify request integrity
X-LoginStringYesMerchant API Key
X-DateStringYes ISO8601 Datetime: yyyy-MM-dd'T'HH:mm:ssZ. E.g.: 2020-06-21T12:33:20Z
Content-TypeStringYesapplication/json
X-Idempotency-KeyStringNoUnique value generated by the client which the server uses to recognize subsequent retries of the same request
### Authorization Signature All the requests you send must contain the `Authorization` header with an HMAC256 control string signature using your own API Signature. This is used to verify the request integrity as we will calculate the same Signature and compare it with the one you send. In case of mismatch we will decline the request. In the case of the notifications given by our APIs, those will also contain an `Authorization` value which you should calculate and compare to make sure the content was not altered by a Man in the Middle attack. Check the following page for instructions on how to calculate the Control Signature. {% content-ref url="/pages/yaWOlB2lmE8cUz4WKPyW" %} [Broken mention](broken://pages/yaWOlB2lmE8cUz4WKPyW) {% endcontent-ref %} ### X-Login All the requests you send must contain the header `X-Login` with your own API Key value used to authenticate yourself. Check [API Keys](/api-documentation/deposits-api/technical-and-security-aspects#api-keys). ### X-Date All the requests you send must contain the header `X-Date` with the time in which the request was created. The format is in ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. {% hint style="warning" %} Make sure you use UTC as the timezone specified and not your client's local timezone. {% endhint %} If the date you send differs in **more than 5 seconds** with the time in our servers, we will block the request for security reasons. #### Example of how to generate the correct X-Date value {% tabs %} {% tab title="Java" %} {% code title="source: JAVA SDK > src/main/java/com/directa24/client/util/ClientUtils.java" %} ```java import java.time.LocalDateTime; import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; public class ClientUtils { private static final String DATE_PATTERN = "yyyy-MM-dd'T'HH:mm:ss'Z'"; private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern(DATE_PATTERN); public static String now() { return LocalDateTime.now(ZoneOffset.UTC).format(DATE_TIME_FORMATTER); } } ``` {% endcode %} {% endtab %} {% tab title="PHP" %} {% code title="source: PHP SDK > src/util/Helpers.php" %} ```php ` header with a random and unique string. Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including `500` errors. An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. All `POST` requests accept idempotency keys. Sending idempotency keys in `GET` and `DELETE` requests has no effect and should be avoided as these requests are idempotent by definition. ### Content-Type All of our Deposits APIs are designed to receive and respond the information in JSON format. This header won't change across the requests, and shall always be: `application/json` ## IP Whitelisting For security purposes, you need to whitelist the IPs from where you will call our API. In order to whitelist your IPs and make the process as smoother as possible, you should go to **Settings -> API Access** and add the list of IPs you will possibly use under the **Deposit IP Address** section. Reach out to if you need to whitelist **our servers IPs** on your firewall. ## Best Practices We recommend you follow this list of technical and security practices to maximize the security of the information end-to-end. 1. Always ensure to verify the Signatures control string sent in the notifications to validate its veracity. 2. We convert all the data we receive to UTF-8. Make sure you are also converting it into UTF-8 to make sure both parties have the same details. 3. Always validate that a deposit is not released more than once based on the `deposit_id` (The notifications can be sent multiple times). Go to the next page to learn how to generate the requests signatures control string to verify the requests' you send and receive integrity. # Calculating the Signature Learn how to calculate and send the Signature header value to verify requests integrity ## Calculating the Signature All the calls to our Deposits APIs will contain an `Authorization` field on the header used to ensure request integrity and to authenticate yourself since you will use your own secret key (API Signature) to generate and encrypt a hash. It has to be created using **HMAC-SHA-256 (RFC 2104)** encoding and the payload must include the following details: > [X-Date](/api-documentation/deposits-api/technical-and-security-aspects#x-date) + [X-Login](/api-documentation/deposits-api/technical-and-security-aspects#x-login) + `JSONPayload` {% hint style="success" %} Use your API Signature to generate the Authorization value {% endhint %} The `Authorization` field on the header of the requests will contain the string "D24 " plus the hash generated, in the following format: > Authorization: "D24 " + HMAC256(X-Date + X-Login + JSONPayload) Example: > Authorization: D24 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf ### Notes The [`X-Login`](/api-documentation/deposits-api/technical-and-security-aspects#x-login) is your login API Key, it can be retrieved from the Merchant Panel by going to Settings -> API Access -> Deposit credentials -> API Key. The [`X-Date`](/api-documentation/deposits-api/technical-and-security-aspects#x-date) is the date in ISO8601 Datetime with Timezone. Format expected: ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. The `Authorization` value is case sensitive and must include all the above mentioned values. The `JSONPayload` is the exact same JSON you sent in the body of the request. In case the `JSONPayload` value is empty (for example in the status or payment methods endpoints), use an empty string ("") instead. The `JSONPayload` should be converted to UTF-8 before hashing it to prevent *Invalid Signature* error when sending characters with different encodings. ## Examples Check the examples in the different languages on how to properly calculate the Signature. You can also check the code of our SDKs in [Java](/deposits-tools/java-sdk) and [PHP](/deposits-tools/php-sdk) to see how it is calculated. {% tabs %} {% tab title="Java" %} ```java import java.io.ByteArrayOutputStream; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Formatter; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public static final String D24_AUTHORIZATION_SCHEME = "D24 "; private static final String HMAC_SHA256 = "HmacSHA256"; public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String JSONPayload) throws NoSuchAlgorithmException, InvalidKeyException, IOException { byte[] hmacSha256 = null; Mac mac = Mac.getInstance(HMAC_SHA256); SecretKeySpec secretKeySpec = new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), HMAC_SHA256); mac.init(secretKeySpec); hmacSha256 = mac.doFinal(buildByteArray(xDate, apiKey, JSONPayload)); return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256); } private static byte[] buildByteArray(String xDate, String apiKey, String JSONPayload) throws IOException { ByteArrayOutputStream bos = new ByteArrayOutputStream(); bos.write(xDate.getBytes(StandardCharsets.UTF_8)); bos.write(apiKey.getBytes(StandardCharsets.UTF_8)); if (JSONPayload != null) { bos.write(JSONPayload.getBytes(StandardCharsets.UTF_8)); } return bos.toByteArray(); } private static String toHexString(byte[] bytes) { Formatter formatter = new Formatter(); for (byte b : bytes) { formatter.format("%02x", b); } return formatter.toString(); } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using System.Text; using System.IO; using System.Security.Cryptography; namespace Application { class Directa24Example { public readonly static string D24_AUTHORIZATION_SCHEME = "D24 "; private readonly static string HMAC_SHA256 = "HmacSHA256"; public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String jsonPayload) { byte[] hmacSha256 = null; var apiSignatureEncod = Encoding.UTF8.GetBytes(apiSignature); var hash = new HMACSHA256(apiSignatureEncod); hmacSha256 = hash.ComputeHash(buildByteArray(xDate, depositKey, jsonPayload)); return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256).ToLower(); } private static byte[] buildByteArray(String xDate, String apiKey, String jsonPayload) { try { MemoryStream stream = new MemoryStream(); var xDateEncod = Encoding.UTF8.GetBytes(xDate); var apiKeyEncod = Encoding.UTF8.GetBytes(apiKey); stream.Write(xDateEncod, 0, xDateEncod.Length); stream.Write(apiKeyEncod, 0, apiKeyEncod.Length); if (!string.IsNullOrWhiteSpace(jsonPayload)) { var jsonPayloadEncod = Encoding.UTF8.GetBytes(jsonPayload); stream.Write(jsonPayloadEncod, 0, jsonPayloadEncod.Length); } return stream.ToArray(); } catch (Exception ex) { throw ex; } } private static string toHexString(byte[] bytes) { return BitConverter.ToString(bytes).Replace("-", string.Empty); } } } ``` {% endtab %} {% tab title="PHP" %} ```php **POST** `https://api-stg.onekeypayments.com/v3/subscriptions` ### Process 1. Merchant submits subscription request with customer and billing information 2. API returns a redirect URL to our secure payment page 3. Customer completes payment on our PCI-compliant page 4. System creates subscription and notifies merchant via webhook 5. Customer is redirected to merchant's success/error URL
Request Example 
{
  "invoice_id": "INV123456",
  "amount": 70.00,
  "currency": "BRL",
  "country": "BR",
  "payer": {
    "id": "PAYER123",
    "document": "123456789",
    "document_type": "CPF",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "description": "Premium Subscription",
  "subscription": {
    "start_date": "2025-01-01",
    "plan": "MONTHLY",
    "plan_unit": 1,
    "auto_renewal": false
  },
  "client_ip": "192.168.1.1",
  "back_url": "https://example.com/back",
  "success_url": "https://example.com/success",
  "error_url": "https://example.com/error",
  "notification_url": "https://example.com/notify"
}
{% openapi src="/files/ks4AhUAUNTfDaWAM9JUw" path="/v3/subscriptions" method="post" %} [okpsubs-creation-v4.yml](https://1595349702-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7aIgg5dys0yN8otrASQq%2Fuploads%2FOpdo17wIZu49H12a5agC%2Fokpsubs-creation-v4.yml?alt=media\&token=4678aef6-1c07-4d01-a777-50dfa63b068d) {% endopenapi %} ### Successful Response fields | Field | Type | Description | Example | | ----------------- | ------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | `subscription_id` | Integer | Unique identifier of the created subscription | 1234 | | `redirect_url` | String (URI) | URL to redirect the user to complete the subscription process | "" | | `expiration_date` | String (Date-time) | Expiration date and time for the subscription checkout process | "2025-03-06 15:58:02" | | `payment_amount` | Number (Double) | Amount to be charged for the subscription | 70.00 | | `redirect` | Boolean | Indicates if the user should be redirected to complete the process | true | #### **Response Example** ```json { "subscription_id": 1234, "redirect_url": "https://checkout.cc-dev.onekeypayments.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513", "expiration_date": "2025-03-06 15:58:02", "payment_amount": 70.00, "redirect": true } ``` ### Error Response Structure
FieldTypeDescriptionExample
codeIntegerError code indicating the type of error400
descriptionStringHuman-readable description of the error"Invalid input data"
typeStringMachine-readable error type identifier"VALIDATION_ERROR"
#### Bad Request - Invalid input data ```json { "code": 400, "description": "Invalid input data", "type": "VALIDATION_ERROR" } ``` #### Unprocessable Entity - Validation error ```json { "code": 422, "description": "Validation error", "type": "VALIDATION_ERROR" } ``` #### Service Unavailable - Error creating subscription ```json { "code": 503, "description": "Error creating subscription", "type": "SERVICE_ERROR" } ``` ### Subscription Plans The following subscription frequencies are supported: | Plan | Description | | ---------- | ----------------------------- | | `DAILY` | Recurring billing every day | | `WEEKLY` | Recurring billing every week | | `MONTHLY` | Recurring billing every month | | `ANNUALLY` | Recurring billing every year | {% hint style="success" %} #### Tests in STG Environment. To test the Subscriptions API in the staging environment, use the parameter `plan` with the value `TEST` inside the `subscription[]` object when calling either the OneShot or PCI endpoints. This triggers simulated deposits **every minute**, along with the corresponding webhook events, so you can quickly verify the full subscription lifecycle.\ The number of deposits generated depends on the value of the `plan_unit` parameter, making it easy to observe the expected behavior in just a few minutes. {% endhint %} # PCI Subscription Creation Endpoint {% hint style="success" %} The PCI flow is available only to merchants who have achieved PCI compliance and can securely handle credit card information. {% endhint %} #### Endpoint **POST** `https://cc-api-stg.onekeypayments.com/v3/subscriptions` #### Process 1. Merchant collects payment details directly from customer 2. Merchant submits complete subscription request including credit card data 3. System processes payment and creates subscription immediately 4. API returns subscription confirmation directly in the response
Request Example ```json { "invoice_id": "INV123456", "amount": 70.00, "currency": "BRL", "country": "BR", "payer": { "id": "PAYER123", "document": "123456789", "document_type": "CPF", "email": "customer@example.com", "first_name": "John", "last_name": "Doe" }, "description": "Premium Subscription", "subscription": { "start_date": "2025-01-01", "plan": "MONTHLY", "plan_unit": 1, "auto_renewal": false }, "credit_card": { "cvv": "123", "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "25", "holder_name": "John Doe" }, "client_ip": "192.168.1.1", "back_url": "https://example.com/back", "success_url": "https://example.com/success", "error_url": "https://example.com/error", "notification_url": "https://example.com/notify" } ```
{% openapi src="/files/MdrQmDINBJcOIrLrGWSe" path="/v3/subscriptions" method="post" %} [okppci-subs-creation-v3.yml](https://1595349702-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7aIgg5dys0yN8otrASQq%2Fuploads%2FFXkQKhxCReDypgOe2fef%2Fokppci-subs-creation-v3.yml?alt=media\&token=669f3aa9-2fb0-4e88-be63-cb08a6faaaa3) {% endopenapi %} ### ### Successful Response Structure
FieldTypeDescriptionExample
subscription_idIntegerUnique identifier of the created subscription1234
**Example response** ```json { "subscription_id": 358 } ``` ### Error Response Structure
FieldTypeDescriptionExample
codeIntegerError code indicating the type of error400
descriptionStringHuman-readable description of the error"Invalid input data"
typeStringMachine-readable error type identifier"VALIDATION_ERROR"
#### Bad Request - Invalid input data ```json { "code": 400, "description": "Invalid input data", "type": "VALIDATION_ERROR" } ``` #### Unprocessable Entity - Validation error ```json { "code": 422, "description": "Validation error", "type": "VALIDATION_ERROR" } ``` #### Service Unavailable - Error creating subscription ```json { "code": 503, "description": "Error creating subscription", "type": "SERVICE_ERROR" } ``` ### Subscription Plans The following subscription frequencies are supported: | Plan | Description | | ---------- | ----------------------------- | | `DAILY` | Recurring billing every day | | `WEEKLY` | Recurring billing every week | | `MONTHLY` | Recurring billing every month | | `ANNUALLY` | Recurring billing every year | {% hint style="success" %} #### Tests in STG Environment. To test the Subscriptions API in the staging environment, use the parameter `plan` with the value `TEST` inside the `subscription[]` object when calling either the OneShot or PCI endpoints. This triggers simulated deposits **every minute**, along with the corresponding webhook events, so you can quickly verify the full subscription lifecycle.\ The number of deposits generated depends on the value of the `plan_unit` parameter, making it easy to observe the expected behavior in just a few minutes. {% endhint %} # Notifications Learn about how the notifications for deposits works ## Deposit status notifications Every time a deposit changes its status, we will send you an asynchronous notification to the `notification_url` you sent in the request or the one you have configured under the section "Settings -> API Access -> Confirm URL" containing the ID of the deposit. **Once received the notification, you should check its new status with the**[ **Deposit Status Endpoint**](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) **and update it on your end accordingly.** {% hint style="info" %} Bear in mind we will only connect through ports 80 and 443. Make sure your `notification_url` has one of those ports open accepting connections from us. {% endhint %} ## Notifications fields | Field | Format | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `deposit_id` | Number | ID of the deposit. Use this ID to [check the status of the deposit.](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) | ## Notifications example ```javascript { "deposit_id": 3000000001 } ``` ## Retry logic Every time a deposit changes its status, we will send you a notification so you can [check its status](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) back. In case that for some reason your server was unable to handle our notification and you returned an HTTP code different than 2XX, we will retry the notification up to 5 more times or until you respond with HTTP 2XX, whatever comes first. {% hint style="success" %} In case of errors while handling the notification, make sure you will answer with an HTTP code distinct than 2XX, that way we will retry the notification. {% endhint %} The time between each of the 5 notifications attempts will be exponential: 5, 25, 125 and 625 minutes accordingly. When a notification failed to be sent, it will be shown like this in our Merchant Panel: ![](/files/-M9_UqvQBGblaqYL1-oD) If you see the errors from the screenshot above, it means the payment was successfully completed and the money was credited to your account but suddenly we couldn't notify you. Keep reading to know how to resend the notifications. ## Resend Notifications In case your system was unable to handle the notification in any of the 5 attempts, you can always check its status with the [Deposit Status Endpoint.](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) If you need to trigger the check status by receiving our notification, once the issue preventing you from receiving our notifications was fixed, you can go to the Merchant Panel, locate the deposit (Transactions -> Deposits) and click on the three dots button under the "Status History" section and then "Resend notification" to force a new notification to be sent. {% hint style="success" %} It can take up to 1 minute for the notification to be resent. {% endhint %} ![](/files/-M9zU27QNwGCCPG-JJEq) # Subscription Cancellation Endpoint ## Overview The Subscription Cancellation API allows merchants to terminate an active subscription before its scheduled end date. Once cancelled, no further charges will be processed for that subscription. ## Endpoint **DELETE** `https://api-stg.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`** Where `{subscription_id}` is the unique numeric identifier of the subscription you wish to cancel. {% openapi src="/files/3zhzWquiE0wIxCLaX2pK" path="/v3/subscriptions/{subscription\_id}" method="delete" %} [okpsubs-delete-v3.yml](https://1595349702-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7aIgg5dys0yN8otrASQq%2Fuploads%2FtjURgHfp9kR0tlIYvOR5%2Fokpsubs-delete-v3.yml?alt=media\&token=0c04b4f7-7f40-4b58-8ab1-052caca84e59) {% endopenapi %} ### Request Parameters This endpoint uses only a path parameter to identify the subscription:
ParameterTypeRequiredDescription
idintegerYesUnique numeric identifier of the subscription to cancel.
### Request Body The request body should be empty for this endpoint. ``` {} ``` ### Response #### Success Response A successful cancellation returns an **HTTP 200** status code :white\_check\_mark:. ### Error Responses The API may return the following errors: #### **Subscription Already Cancelled (421)** Returned when attempting to cancel a subscription that has already been cancelled: ```json { "code": 421, "description": "Subscription was already cancelled.", "type": "SUBSCRIPTION_ALREADY_CANCELLED" } ``` #### **Subscription Not Found (420)** Returned when the specified subscription ID does not exist: ```json { "code": 420, "description": "Subscription does not exist.", "type": "SUBSCRIPTION_NOT_FOUND" } ``` #### **Subscription Terminated (426)** Returned when attempting to cancel a subscription that has already been terminated (completed its lifecycle): ```json { "code": 426, "description": "Subscription is terminated and cannot be cancelled.", "type": "SUBSCRIPTION_IS_TERMINATED" } ``` #### **Generic Error (501)** Returned when an unexpected error occurs: ```json { "code": 501, "description": "Generic Error", "type": "GENERIC_ERROR" } ``` ### Cancellation Effects When a subscription is cancelled: 1. The subscription status is immediately changed to `CANCELLED` 2. All scheduled future charges are removed 3. The cancellation is recorded in the subscription history ### Important Notes 1. **Cancellation vs. Refund**: Cancelling a subscription only prevents future charges. It does not refund any previous charges. To process refunds for previous transactions, use the separate Refund API. 2. **Reactivation**: Once a subscription is cancelled, it cannot be reactivated. A new subscription must be created if the customer wishes to resume the service. 3. **Timing**: Cancellation takes effect immediately, regardless of the subscription's billing cycle. # Subscription Status Endpoint This documentation details the endpoint used to retrieve the current status and information of existing subscriptions in our system. ## Overview The Subscription Status API allows merchants to retrieve comprehensive information about a subscription, including its current status, billing details, dates, and configuration. ### Endpoint **GET** `https://api-stg.onekeypayments.com/v3/subscriptions/`**`{subscription_id}`** Where `{subscription_id}` is the unique numeric identifier of the subscription you wish to retrieve. {% openapi src="/files/s8qNmPXfCwoB5A9bkJb6" path="/v3/subscriptions/{subscription\_id}" method="get" %} [okpsubs-get-v2.yml](https://1595349702-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7aIgg5dys0yN8otrASQq%2Fuploads%2Fs6JaHPIhCEIhf6JWfhYE%2Fokpsubs-get-v2.yml?alt=media\&token=7ab890d9-b31c-4409-9f31-c16b3c3d6264) {% endopenapi %} ### Request Parameters This endpoint uses only a path parameter to identify the subscription:
ParameterTypeRequiredDescription
idintegerYesUnique numeric identifier of the subscription to retrieve.
### Response #### Success Response A successful request returns an HTTP 200 status code with the subscription details: ```json { "id": 219, "status": "PENDING", "start_date": "2020-10-10", "end_date": "2020-10-17", "creation_date": "2025-02-18T17:18:21.67708163", "subscription_plan": "WEEKLY", "amount": 10.90, "auto_renewal": true, "last_modified_date": "2025-02-18T13:49:16" } ``` #### Response Fields
FieldTypeDescription
idintegerUnique identifier of the subscription
statusstringCurrent status of the subscription (PENDING, ACTIVE, CANCELLED, TERMINATED)
start_datestringDate when the subscription started or will start (YYYY-MM-DD)
end_datestringDate when the subscription will end if not renewed (YYYY-MM-DD)
creation_datestringTimestamp when the subscription was created
subscription_planstringFrequency of the subscription (DAILY, WEEKLY, MONTHLY, ANNUALLY)
amountnumberAmount charged for each billing cycle
auto_renewalbooleanWhether the subscription will automatically renew
last_modified_datestringTimestamp when the subscription was last modified
#### Error Responses The API may return the following errors: **Subscription Not Found** Returned when the specified subscription ID does not exist: ```json { "code": 420, "description": "Subscription does not exist.", "type": "SUBSCRIPTION_NOT_FOUND" } ``` **Generic Error** Returned when an unexpected error occurs: ```json { "code": 500, "description": "Subscription not found id 218 for merchantId 127,885", "type": "GENERIC_ERROR" } ``` ### Subscription Statuses A subscription can have one of the following statuses: | Status | Description | | ------------ | ------------------------------------------------------------------------------------ | | `PENDING` | Subscription has been created but payment has not been confirmed | | `ACTIVE` | Subscription is active and billing cycles are in progress. | | `CANCELLED` | Subscription was cancelled before completion. | | `TERMINATED` | Subscription was terminated successfully, and all payments were charged accordingly. | ## Webhook Notifications and Payment Flow When a payment related to a subscription is processed, our system will send notification updates to your configured notification URL. This notification includes a `deposit_id` which is crucial for tracking the payment status. {% hint style="success" %} It is important that you integrate the [**Deposit Status Endpoint**](broken://pages/G4LyvijzUWxyN6nXI2Tn). {% endhint %} ### Complete Notification Flow 1. **Payment Processing**: The system processes a payment (initial or recurring) 2. **Webhook Notification**: A notification is sent to your configured URL with a `deposit_id` 3. **Deposit Status Endpoint**: Query **GET** `v3/deposits/`**`{deposit_id}`** to get payment details.\ You can find details of the endpoint [here](/api-documentation/deposits-api/endpoints/deposit-status-endpoint). 4. **Subscription Identification**: The deposit response includes the related `subscription_id` 5. **Subscription Status Check**: Query **GET** `v3/subscriptions/`**`{subscription_id}`** to verify current status #### Example Flow ``` Payment processed ↓ Notification received with deposit_id=12345 ↓ GET v3/deposits/12345 ↓ Response contains subscription_id=219 ↓ GET v3/subscriptions/219 ↓ Verify and update subscription records ``` This complete flow ensures that you have full visibility into both payment status and subscription details. # Automatic PIX API ## Overview Our Automatic PIX API creates subscription-style payments, generating QR Codes that customers scan to pay within a set period, including built-in logic for retries and cancellations to manage and track recurring customer payments automatically.\ \ This includes: * **Initial Enrollment** - Create first-time deposit and/or determine start of an automatic PIX charge. * **Recurring Payments** - A new QR Code is generated on a fixed time basis for each payment cycle. * **Retry Logic** - Multiple instances to complete the transaction if any of the recurring attempts fail. * **Status** - Obtain detailed information about each enrollment. * **Cancellation** - Cancel any enrollment previously created. ### Basic Overview The included endpoints are:\ \ **Start Enrollment** (**`POST`** /v1/enrollments): * Initial deposit information is sent, with all the customer's information, the amount to be charged & other API info. * Within this initial request, the time frequency that which this should be charged & if it has a first instant payment or not, is included. **Recurring Payments** (**`POST`** /v3/deposits): * A POST request containing the enrollment\_id and the exclusive IXA payment\_method is automatically submitted to the Deposits API at the end of each recurring period to process the next payment. **Retry Logic** (**`POST`** /v3/deposits/retry/{depositId}): * If any of the recurring payments failed/expired, you can use this endpoint in order to generate a new QR code tied to an existing attempt. **Status Endpoint** (**`GET`** /v1/enrollments/{id}): * Provides you with all the information related to an enrollment ID. **Cancellation Endpoint** (**`POST`** /v1/enrollments/{enrollmentId}/cancel): * Allows you to cancel a previously created enrollment. ## Authentication Requirements * **X-Login**: Your deposits merchant API key. * **X-Date**: Current timestamp in ISO 8601 format. * **Authorization**: Authentication hash. * **Content-Type**: application/json. All Automatic PIX API endpoints require and follow the same security aspects & headers used for deposits, [which can be found here.](/api-documentation/deposits-api/technical-and-security-aspects)
# Enrollment Creation Endpoint ## Enrollment creation `POST` `https://api-stg.onekeypayments.com/v3/enrollments` This endpoint will allow you to start an enrollment. #### 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 | **This API utilizes the same security rules & technical aspects as our deposits API, which can be found** [**here.**](/api-documentation/deposits-api/technical-and-security-aspects) #### 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 | #### Enrollment Specific Fields | Name | Type | Description | | ----------------------- | ------- | --------------------------------------------------------------------------------------------- | | start\_date | date | Date that the enrollment starts. Format `YYYY-MM-DD` | | frequency | string | `DAILY`, `WEEKLY`, `MONTHLY` or `ANNUALLY` | | amount\_type | string | `FIXED` | | include\_first\_payment | boolean | `true` or `false,` indicates if a payment will be done as soon as the enrollment is created | | first\_payment\_amount | number | Only used if include\_first\_payment is true. | | automatic\_billing | boolean | `true` or `false,`Indicates if recurring transactions will be generated automatically or not. | {% hint style="warning" %} All of these fields are mandatory in order to create a new enrollment. {% endhint %} #### Example Request ```json { "invoice_id": "invoiceid10000", "country": "BR", "currency": "BRL", "payer": { "first_name": "Ricardo", "last_name": "Carlos", "document": "01234567890", "document_type": "CPF", "email": "ricardo.carlos@example.com", "phone": "+5511999999999" }, "start_date": "2025-10-22", "frequency": "MONTHLY", "amount": 1, "amount_type": "FIXED", "include_first_payment": true, "first_payment_amount":"50", "success_url": "https://merchant.com/payment/success", "notification_url": "https://merchant.com/payment/notification" } ``` {% hint style="success" %} With the provided request above, this would create a payment of 1 BRL, which needs to be paid once per month. {% endhint %} ### Successful response example ```json { "enrollment_id": 36, "invoice_id": "invoiceid10000", "currency": "BRL", "country": "BR", "amount": 1, "status": "PENDING", "redirect_url": "https://link.depositcheckout.com/enrollment/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiIzNiIsImlhdCI6MTc2MTMyNDk4NCwiZXhwIjoxNzYyNjIwOTg0LCJsYW5ndWFnZSI6InB0In0.odWD9R6Mh9br53fynu3n2vVBIXCvkOTk74-V4gAaNhurk217WaWUHOrK4CWobz1a", "metadata": { "qr_code": "data:image/png;base64,iVBORw0KGgoAANNNSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACbElEQVR4XmP4jwp+MIwKjAqgCTCu9+JUi09hhwvUsnClXdih+h0u4HpeoPSVvqs4QkCbffPldaFIAs/3BJTP70UI1KpFqxfU30WYwRgKAiEIW/5/lGSPCcoHsSACLFW3ElxeBa2HC7yKb5H8J57bj1DhdPFfRzIzwtDusHaZz3Wy5XCBmO5pzxPOJVxHqLi4xsus31IeLsDAvqjo5Fv253CBQ48vVmQzvXgPF1h5fN4zo50l2+ECn7pOi5Rdy0AYKqD6+uAEW9bjcIEmu17N9V5c9XCBvyuYdot0iEyHCzxbvYfD3E9DHy4g+X/5hwu72RG2iJ9/FnMneI86XKD3kHay2P5AJFt07giVib1BBJDv1pfTZ+RNRjjsF/Nvj/1GvghbCqImLXA+ZRAOF2j37QjXkv8eDxe4Gpz3NX5TKyJezA09nms7Pa+HC1xg6nogeDMBYeiiy95y3y8jBfJHJWffAE0GRJi+d/SreJfwaz9coOeL0APzTndEeNyf/1Pq27Q1CO+bvL2wTtDiwHK4QLWinOM79xBEeKheu/Xi2Tt1hLVN3a3i6W4FiJiL+T81QeKxACJ9qH1PZNnxPD0dLnDhgvia5T9UzOECTqong1YdVp0PFzhaO0U3cG0rwox084Zlq1guI0KdZ+6cl4IzdcThAtw93WKbjqshIurg17PpEgtVEQJiWr0xr07vRriUp4vtgfhKBX+4wP/oveJlYcsRDmO03FRauD0UKVeeyWCXNXVHhIdr2aoHTq+QzHA1vMtZ1vYQEciuSrk8Aqs5EH6ptbvbZDrdECHAqDJ959FXnohQRwKjAqMCyAIAB4fJmMX3JNsAAAAASUVORK5CYII=", "digitable_line": "00020101021226990014br.gov.bcb.pix2577pix.onekeypayments.com/qrs1/v2/01zVHEoEXMAE9s5IICqar4t2ly1vHNPURJbZRqPXlz6TFt52040000530398654041.005802*80980014br.gov.bcb.pix2576pix.onekeypayments.com/public/v1/rec/1ZEpF4g8eOa9s6Lc9g1LzCklGR4fVe9OaxDf2W2630425BF" } } ``` ### Response fields | Name | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------------------------------- | | `enrollment_id` | number | Indicates the ID of the enrollment. This is important to create reucrring payments. | | `invoice_id` | string | ID of the deposit on the merchant end. | | `country` | string | `BR` | | `currency` | string | `BRL` | | `amount` | string | Amount of the enrollment created. | | `status` | string | Status of the enrollment | | `redirect_url` | URL | URL used to redirect the customer where they can see the details to pay | | `qr_code` | string | PNG image encoded in base64 of the QR code used to display the Pix QR natively on your site | | `digitable_line` | string | Plain text string line the user can use to manually pay for the PIX instead of scanning the QR | # Recurring Payment Endpoint ## Deposit Creation `POST` `https://api-stg.onekeypayments.com/v3/deposits` In order to create recurring payments, we utilize the same endpoint as for regular deposits, with additional mandatory fields, in order to identify the enrollment and the date.\ \ All detailed information for the deposits API can be found [here.](/api-documentation/deposits-api) #### 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 | ### Recurring Payment Fields | Name | Type | Description | | -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | enrollment | object | Contains the ID and Date | | enrollment.id | number | ID of the previously created enrollment. Can be obtained with [this endpoint.](/api-documentation/automatic-pix-api/enrollment-creation-endpoint) | | enrollment.scheduled\_date | date | Scheduled date of the payment, format YYYY-MM-DD | This additional object needs to be included, together with the deposits API fields, in order to create an instance for the customer to pay an automatic PIX. Fields can be [found here.](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#request-body) ### Example Request ```json { "invoice_id": "invoiceid10000", "country": "BR", "currency": "BRL", "payment_method": "IXA", "payer": { "first_name": "Ricardo", "last_name": "Carlos", "document": "01234567890", "document_type": "CPF", "email": "ricardo.carlos@example.com", "phone": "+5511999999999" }, "amount": 1, "success_url": "https://merchant.com/payment/success", "notification_url": "https://merchant.com/payment/notification", "back_url": "https://merchant.com/payment/back", "error_url": "https://merchant.com/payment/error", "enrollment": { "id": 30, "scheduled_date": "2025-11-22" } } ``` {% hint style="info" %} The ID from the enrollment must be acquired from a previously created enrollment; the scheduled date is the date by which the payment needs to be completed by the customer. {% endhint %} ### Status & Flow \ As this works exactly the same as our deposits API, both for the payment flow and the usage of our APIs, the status for each transaction can be handled with our [deposit status endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint), and [notification](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint/notifications) info is also handled in the same manner. # Enrollment Status Endpoint ### Enrollment Status `GET` `https://api-stg.onekeypayments.com/v3/enrollments/{id}` This endpoint allows you to obtain the information of a certain enrollment, together with all the deposits tied to it. #### Path Parameters | Name | Type | Description | | ------------------------------------ | ------- | ----------------------------------------------------------- | | id\* | integer | Enrollment ID. It is obtained when creating the enrollment. | #### Headers
NameTypeDescription
X-Date*stringISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*stringMerchant X-Login API Key
Authorization*stringAuthentication signature hash
## Example response ```json { "enrollment_id": 30, "amount": 1.00, "country": "BR", "currency": "BRL", "invoice_id": "invoiceid10000", "amount_type": "FIXED", "status": "ACTIVE", "frequency": "MONTHLY", "start_date": "2025-10-22", "payer": { "id": "404606303", "email": "ricardo.carlos@example.com", "first_name": "Ricardo", "last_name": "Carlos", "phone": "+5511999999999", "full_name": "Ricardo Carlos" }, "deposits": [ 1398852515 ] } ``` {% hint style="success" %} This response gives you all the information about the enrollment created, and also the "deposits" **object,** which includes all the deposits tied to this enrollment ID. You can use the regular [deposit status API ](/api-documentation/deposits-api/endpoints/deposit-status-endpoint)to get details of each deposit ID. {% endhint %} # Cancel Enrollment Endpoint ### Cancelling an Enrollment This endpoint allows you to cancel an existing enrollment.\ \ This uses the same API credentials as the deposit endpoint.\ \ `DELETE` `https://api-stg.onekeypayments.com/v3/enrollments/{enrollment_id}/` #### Path Parameters | Name | Type | Description | | ------------ | ------- | ------------------------------------------------------------------ | | enrollmentId | integer | OKP enrollment\_id. It is obtained when creating a new enrollment. | #### 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 | ### Example Response ```json { "enrollment_id": 36, "status": "CANCELLED" } ``` # Quickpay With QuickPay, merchants can start receiving payments from their customers first and ask them to signup then This API allows final users to make deposits without the need to fill out forms with their personal information. The customer will be able to deposit without giving any personal information as after the payment we receive the deposit and get the depositor info and proceed with KYC verification. We send to you the KYC data in the background, so you can create your account without the need of presenting a registration form. {% hint style="info" %} This solution is currently available for Pix in Brazil. Check with your Account Manager regarding the activation and availability of this solution on your Payment Methods of preference. {% endhint %} ## Configuration Merchants who integrate QuickPay will have the option to configure a new callback URL where you will receive the KYC of the payer. ## Flow
> This integration offers an optimized, seamless and secure experience for the customer, achieving a higher conversion rate and resulting in a payment flow 12x faster :rocket: 1. Customer gets into your website 2. The customer chooses to deposit money 3. You create a transaction on our side with the following information: country, payment method, currency, and amount\ \ \ **For Pix** * We will answer with the PIX QR code * The customer will scan the QR and pay on their HomeBanking\ \ \ \ **After the payment is done**
1. We collect the following KYC data of current customer and send it to you using the previously configured callback URL: Name, Date of Birth, Document type, Document number, Address, Cadastral Status, and PEP (Politically exposed person) 2. We perform a thorough user validation with the KYC data, this process includes: * Age limit * PEP check * Legal status * Greylist and blacklist checks * IP validations 3. We reject (and refund) the deposit or allow it to process it successfully, crediting you the money and sending you a webhook 4. You will be able to ask the customer to set up an account (user, password). The customer is all set up and can access your service. # Endpoints Learn how to integrate QuickPay APIs The QuickPay solution uses the same integration of our [Deposits API](/api-documentation/deposits-api) endpoints with the difference that you don't need to send us the **`payer[]`** object (the customer details) on the [Deposit Creation Endpoint](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#deposit-creation)API. Also, after the transaction is paid by the customer we will send you a new [web-hook ](/api-documentation/quickpay/endpoints/deposit-creation-endpoint/notifications#deposit-notification-example)and extra information regarding customer's KYC on the response of the [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint). ### # Deposit creation endpoint Learn how to create deposits with QuickPay The QuickPay solution uses the same integration of our [Deposits API](/api-documentation/deposits-api) endpoints with the difference that you don't need to send us most of the **`payer[]`** object (the customer details) on the [Deposit Creation Endpoint](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint#deposit-creation) API since this information is not required.
{% hint style="info" %} Note: For MEXICO SPEI payments, the payer object needs to be included with only an "id", which is NOT the document of the customer, it is the unique reference for the payer within the merchant's system.\ \ payer\[] object is not mandatory for PIX Brasil. {% endhint %} Hence, requests must not contain any payer info. Please take a look at the following example request and follow the details on [Deposit Creation Endpoint](/api-documentation/deposits-api/endpoints/deposit-creation-endpoint) for further details about the integration. ### OneShot Request example {% tabs %} {% tab title="Example Brasil" %} ```javascript { "invoice_id" : "1000000001", "amount": "1000", "country": "BR", "currency": "BRL", "payment_method": "IX", "description": "test description", "client_ip": "123.123.123.123", "device_id": "00000000-00000000-01234567-89ABCDEF", "notification_url": "https://www.onekeypayments.com/OKP/notify", "test": false, "mobile": true, "language": "pt" } ``` {% endtab %} {% endtabs %} # Notifications Learn about how the notifications for deposits works QuickPay notifications about the change of status of a deposit use the same structure than a normal deposits as shown on [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) ## Deposit Notification example ```json { "deposit_id": 123456789 } ``` Use the [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) to check the status of the transaction. Also, before approving the transaction we send you an extra notification (if you have configured the callback URL for QuickPay) with the following details ## QuickPay Deposit Notification example ```javascript { "depositId": 123456789, "document": "84932568207", "fullName": "John Doe", "cadastralSituation": "REGULAR", "dateOfBirth": "19871027", "pep": true, "address": "Rua 13, Sao Paulo, 12345-678 ", "email": "jon.doe@example.com", "success": true } ``` You must respond with an HTTP 2XX code for the deposit to be approved. If you respond with anything different, a refund will be initiated. This also triggers a notification similar to the previous one, but with the addition of the ‘refunded = true’ field. ```javascript { "depositId": 123456789, "document": "84932568207", "fullName": "John Doe", "cadastralSituation": "REGULAR", "dateOfBirth": "19871027", "pep": true, "address": "Rua 13, Sao Paulo, 12345-678 ", "email": "jon.doe@example.com", "success": true, "refunded":true } ``` # Deposit status endpoint Retrieve the status of a previously created deposit Given that QuickPay uses the same Deposit Status Endpoint than our Deposits APIs, please check [Deposit Status Endpoint](/api-documentation/deposits-api/endpoints/deposit-status-endpoint) for further details about the integration. In the case of QuickPay (and COMPLETED) transactions, this endpoint will add extra information about the customer KYC. ## Example response {% hint style="info" %} * Be aware that the field full\_name is the name validated by our KYC engine, while first\_name and last\_name is the info client was first registered with in our database. * Birth date format is yyyyMMdd {% endhint %} {% tabs %} {% tab title="COMPLETED" %} ```java { "user_id": "11", "deposit_id": 123456789, "invoice_id": "ql4vhBUlvnic", "country": "BR", "currency": "BRL", "usd_amount": 35.00, "local_amount": 281.06, "bonus_amount": 0.00, "bonus_relative": false, "payment_method": "IX", "payment_type": "BANK_TRANSFER", "status": "COMPLETED", "payer": { "document": "84932568207", "document_type": "CPF", "email": "johnSmith12@gmail.com", "first_name": "John", "last_name": "Smith", "birth_date": "19770930", "full_name": "John Smith", "pep": true, "legal_situation": "REGULAR" }, "refunded": false, "current_payer_verification": "NO_CURRENT_PAYER_DATA" } ``` {% endtab %} {% endtabs %} # Bank Account Validation Bank Accounts Validation API Introduction The Bank Accounts Validation API allows you to verify if a bank account is not only valid, but also if it exists and can receive funds. We do this by using the same algorithm the banks use to create and validate the accounts and by making a *micro-deposit* that verifies the account exists and is able to receive funds. {% hint style="success" %} Check with your Account Manager regarding the availability of this API on the banks you require {% endhint %} See how to integrate to the Bank Account Validation API by clicking below:
{% content-ref url="/pages/6Y9tcLS2czxBN2SRJ1gh" %} [Bank Account Validation Endpoint](/api-documentation/bank-account-validation/endpoints/bank-account-validation-endpoint) {% endcontent-ref %} # Technical and Security Aspects Learn about the technical and security aspects of our Bank Accounts Validation APIs ## Security Considerations * All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. * API requests without Authentication will also fail. * You will be able to hit our APIs only from the IPs you have previously whitelisted on the Merchant Panel. ## Environments All the integration must be performed on our **TEST environment**, where you can perform your tests freely without risks of any kind. When you sign up with us, we will generate you an account on our STG environment where you will be able to: * See the transactions created * Approve and cancel transactions * Retrieve your API Keys * Whitelist your IPs, and more ### Endpoint domains Each environment has its own domain. The path of the endpoints doesn't change. | Environment | Domain | | ----------- | -------------------------------------- | | Testing | `https://api-stg.onekeypayments.com/` | | Production | Provided once you complete the testing | {% hint style="info" %} Notes: * You will use the STG endpoints to integrate. * The STG and PROD environments are not communicated in any way. * No transaction created on the STG environment will be reflected on the PROD environment or vice versa. * The API Keys and configurations between environments are also different. {% endhint %} ## API Keys Our Bank Accounts Validation APIs uses API Keys in all of the requests to authenticate. Your API Keys can be retrieved from the Merchant Panel by going to Settings -> API Access -> Cashouts Credentials. {% hint style="info" %} * The API Keys on the STG and PROD environments are different. {% endhint %} Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). You must provide your API Key in all the requests as the basic auth username value. You do not need to provide a password. Your API Key must be sent in all the API calls using the X-Login field on the header of the request. Your API Keys, along with your IP Addresses are your way to authenticate yourself, therefore, do not share your secret API keys in publicly accessible areas such as GitHub, client-side code and so forth. ## Headers All the requests sent through the API of Deposits v3 must have the following headers.
HeaderFormatMandatoryDescription
AuthorizationStringYes"D24 " plus a hash HMAC256 to verify request integrity
X-LoginStringYesMerchant Cashout API Key
X-DateStringYes ISO8601 Datetime: yyyy-MM-dd'T'HH:mm:ssZ. E.g.: 2020-06-21T12:33:20Z
Content-TypeStringYesapplication/json
### Authorization Signature All the requests you send must contain the `Authorization` header with an HMAC256 control string signature using your own API Signature. This is used to verify the request integrity as we will calculate the same Signature and compare it with the one you send. In case of mismatch we will decline the request. You can retrieve your API Signature from our backoffice by going to Settings -> API Access -> Cashout API Signature Check the following page for instructions on how to calculate the Control Signature. {% content-ref url="/pages/qWogWfcSD2e30Enbh4OE" %} [Calculating the Signature](/api-documentation/bank-account-validation/technical-and-security-aspects/calculating-the-signature) {% endcontent-ref %} ### X-Login All the requests you send must contain the header `X-Login` with your own API Key value used to authenticate yourself. Check [API Keys](#api-keys). ### X-Date All the requests you send must contain the header `X-Date` with the time in which the request was created. The format is in ISO8601 Datetime: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. {% hint style="warning" %} Make sure you use UTC as the timezone specified and not your client's local timezone. {% endhint %} If the date you send differs in **more than 5 seconds** with the time in our servers, we will block the request for security reasons. #### Example of how to generate the correct X-Date value {% tabs %} {% tab title="First Tab" %} ```java import java.time.LocalDateTime; import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; public class ClientUtils { private static final String DATE_PATTERN = "yyyy-MM-dd'T'HH:mm:ss'Z'"; private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern(DATE_PATTERN); public static String now() { return LocalDateTime.now(ZoneOffset.UTC).format(DATE_TIME_FORMATTER); } } ``` {% endtab %} {% tab title="Second Tab" %} ```php API Access** and add the list of IPs you will possibly use under the **Cashout IP Address** section. Reach out to [integration@onekeypayments.com](mailto:integration@d24.com) if you need to whitelist **our servers IPs** on your firewall. ## Best Practices We recommend you follow this list of technical and security practices to maximize the security of the information end-to-end. 1. Always ensure to verify the Signatures control string sent in the notifications to validate its veracity. 2. We convert all the data we receive to UTF-8. Make sure you are also converting it into UTF-8 to make sure both parties have the same details. Go to the next page to learn how to generate the requests signatures control string to verify the requests' you send and receive integrity. # Calculating the Signature Learn how to calculate and send the Signature header value to verify requests integrity ## Calculating the Signature All the calls to our Bank Account Validation APIs will contain an `Authorization` field on the header used to ensure request integrity and to authenticate yourself since you will use your own secret key (API Signature) to generate and encrypt a hash. It has to be created using **HMAC-SHA-256 (RFC 2104)** encoding and the payload must include the following details: > [X-Date](broken://pages/6jhbTM0NkFftgMW0fIDL#x-date) + [X-Login](broken://pages/6jhbTM0NkFftgMW0fIDL#x-login) + `JSONPayload` {% hint style="success" %} Use your API Signature to generate the Authorization value {% endhint %} The `Authorization` field on the header of the requests will contain the string "D24 " concatenated to the hash generated, in the following format: > Authorization: "D24 " + HMAC256(X-Date + X-Login + JSONPayload) Example: > Authorization: D24 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf ### Notes The `X-Login` is your login API Key, it can be retrieved from the Merchant Panel by going to Settings -> API Access -> Cashout credentials -> API Key. The `X-Date` is the date in ISO8601 Datetime with Timezone. Format expected: ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ`. E.g.: `2020-06-21T12:33:20Z`. The `Authorization` value is case sensitive and must include all the above mentioned values. The `JSONPayload` is the exact same JSON you sent in the body of the request. In case the `JSONPayload` value is empty (for example in the status or payment methods endpoints), use an empty string ("") instead. The `JSONPayload` should be converted to UTF-8 before hashing it to prevent *Invalid Signature* error when sending characters with different encodings. ## Examples Check the examples in the different languages on how to properly calculate the Signature. You can also check the code of our SDKs in [Java](/deposits-tools/java-sdk) and [PHP](/deposits-tools/php-sdk) to see how it is calculated. {% tabs %} {% tab title="Java" %} ```java import java.io.ByteArrayOutputStream; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.util.Formatter; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public static final String D24_AUTHORIZATION_SCHEME = "D24 "; private static final String HMAC_SHA256 = "HmacSHA256"; public static String buildCashoutKeySignature(String apiSignature, String xDate, String cashoutApiKey, String JSONPayload) throws NoSuchAlgorithmException, InvalidKeyException, IOException { byte[] hmacSha256 = null; Mac mac = Mac.getInstance(HMAC_SHA256); SecretKeySpec secretKeySpec = new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), HMAC_SHA256); mac.init(secretKeySpec); hmacSha256 = mac.doFinal(buildByteArray(xDate, cashoutApiKey, JSONPayload)); return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256); } private static byte[] buildByteArray(String xDate, String cashoutApiKey, String JSONPayload) throws IOException { ByteArrayOutputStream bos = new ByteArrayOutputStream(); bos.write(xDate.getBytes(StandardCharsets.UTF_8)); bos.write(cashoutApiKey.getBytes(StandardCharsets.UTF_8)); if (JSONPayload != null) { bos.write(payload.getBytes(StandardCharsets.UTF_8)); } return bos.toByteArray(); } private static String toHexString(byte[] bytes) { Formatter formatter = new Formatter(); for (byte b : bytes) { formatter.format("%02x", b); } return formatter.toString(); } ``` {% endtab %} {% tab title="C#" %} ```csharp using System; using System.Text; using System.IO; using System.Security.Cryptography; namespace Application { class Directa24Example { public readonly static string D24_AUTHORIZATION_SCHEME = "D24 "; private readonly static string HMAC_SHA256 = "HmacSHA256"; public static String buildCashoutKeySignature(String apiSignature, String xDate, String cashoutApiKey, String jsonPayload) { byte[] hmacSha256 = null; var apiSignatureEncod = Encoding.UTF8.GetBytes(apiSignature); var hash = new HMACSHA256(apiSignatureEncod); hmacSha256 = hash.ComputeHash(buildByteArray(xDate, cashoutApiKey, jsonPayload)); return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256).ToLower(); } private static byte[] buildByteArray(String xDate, String cashoutApiKey, String jsonPayload) { try { MemoryStream stream = new MemoryStream(); var xDateEncod = Encoding.UTF8.GetBytes(xDate); var cashoutApiKeyEncod = Encoding.UTF8.GetBytes(cashoutApiKey); stream.Write(xDateEncod, 0, xDateEncod.Length); stream.Write(cashoutApiKeyEncod, 0, cashoutApiKeyEncod.Length); if (!string.IsNullOrWhiteSpace(jsonPayload)) { var jsonPayloadEncod = Encoding.UTF8.GetBytes(jsonPayload); stream.Write(jsonPayloadEncod, 0, jsonPayloadEncod.Length); } return stream.ToArray(); } catch (Exception ex) { throw ex; } } private static string toHexString(byte[] bytes) { return BitConverter.ToString(bytes).Replace("-", string.Empty); } } } ``` {% endtab %} {% tab title="PHP" %} ```php `POST` `https://api-stg.onekeypayments.com/v5/account/validate` This endpoint allows you to validate if a bank account is valid, if it exists and if it can receive funds #### 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 Cashouts API Key | | Authorization\* | string | Authorization control hash | #### Request Body | Name | Type | Description | | ------------------------------------------------------------- | --------- | ------------------------------------------------------------- | | country\* | String | Country of the bank account to validate | | document\* | String | Document of identity of the beneficiary | | document\_type\* | String | Type of the document specified | | first\_name | String | First name of the beneficiary | | last\_name | String | Last name of the beneficiary | | bank\_account.bank\_code | Numeric | Code of the bank of the beneficiary | | bank\_account.account\* | String | Bank account of the beneficiary | | bank\_account.branch | String | Bank branch of the beneficiary | | bank\_account.account\_type\* | String | Bank account type of the beneficiary | | bank\_account\* | Object\[] | Object containing the details of the bank account to validate | | amount | Numeric | Amount of the withdrawal | | currency | String | Currency of the amount specified | {% tabs %} {% tab title="204: No Content Success" %} ```java { "description": "Valid account" } ``` {% endtab %} {% tab title="400: Bad Request Validation error" %} ```java { "code": 300, "description": "Invalid document number", "type": "INVALID_DOCUMENT" } ``` {% endtab %} {% tab title="401: Unauthorized Invalid Credentials" %} ```java { "code": 100, "description": "Invalid Credentials", "type": "INVALID_CREDENTIALS" } ``` {% endtab %} {% endtabs %} ## Description This endpoint allows you to validate not only if the details of the beneficiary are correct according to the validations performed by the banks, but also to validate if the account exists in the bank and if it can receive funds. Validations performed: 1. The bank account, branch and type are valid 2. The account exists in the bank 3. The bank account belongs to the beneficiary details indicated (Document, name, etc) 4. The amount specified is within the minimum and maximum limits (optional, only performed if `amount` is sent) 5. The account can receive funds (it's not blocked, closed, etc) If all these checks pass, we can be sure that the account is valid and that a Withdrawal created with those details will be fulfilled successfully. In order to start using this API, you need to: 1. Send the request with **POST** method. 2. Use the headers described [here](/api-documentation/bank-account-validation/technical-and-security-aspects). 3. Specify the details required to validate the account in the body as JSON {% hint style="success" %} This API must be activated on your account. Check with your Account Manager regarding the activation {% endhint %} ## Example Request {% tabs %} {% tab title="cURL" %} ```java curl --location --request POST 'https://api-stg.directa24.com/v5/account/validate' \ --header 'X-Login: cashouts_api_key' \ --header 'X-Date: 2022-01-01T19:00:06Z' \ --header 'Authorization: D24 520ec3e5e2d8f8c2fc66948bc87984a2ff8dec0fe25d13781272f0ae94665c3c' \ --header 'Content-Type: application/json' \ --data-raw '{ "country": "BR", "document": "84932568207", "document_type": "CPF", "first_name": "Ricardo", "last_name": "Carlos", "amount": 100, "currency": "BRL", "bank_account": { "bank_code": 100, "account": "123456-7", "branch": "6789-X", "account_type": "S" } }' ``` {% endtab %} {% endtabs %} ### Request fields description | Field | Format | Description | Validations | | --------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------: | | `country` | string (length: 2) | Country code of the deposit in *ISO 3166-1 alpha-2 code* format | [Country codes](/knowledge-base/countries-specifications#countries-and-currencies) | | `document` | string (max length: 30) | Document of identity of the beneficiary |

Valid document for the country of the deposit.

See validations here

| | `document_type` | string (max length: 10) | Type of the document specified |

Valid document type for the country of the deposit.

See validations here

| | `first_name` | String (max length: 255) | First name of the beneficiary | String of up to 255 characters | | `last_name` | String (max length: 255) | Last name of the beneficiary | String of up to 255 characters | | `amount` | decimal (max decimals: 2) | Amount to validate | | | `currency` | string (length: 3) | Currency code of the amount in *ISO 4217* format. Default is `USD` | Valid [currency](/knowledge-base/countries-specifications#countries-and-currencies) | | `bank_account.bank_code` | String (max length: 10) | Beneficiary's valid `bank_code` for the country. Use the [Bank Codes Endpoint.](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | Valid [bank code](/api-documentation/cashouts-api/endpoints/cashout-bank-codes) | | `bank_account.account` | String (max length: 45) | Bank account of the beneficiary | String of up to 45 characters | | `bank_account.branch` | String (max length: 45) | Bank branch of the beneficiary | String of up to 45 characters | | `bank_account.account_type` | Array | Beneficiary's account type | | ## Example Responses ### Success Example In case the bank account passed all the validations, an HTTP 204 status code will be returned. ### Error Responses Example ```java // The document informed didn't pass our validations { "code": 300, "description": "Invalid document number", "type": "INVALID_DOCUMENT" } // The API Key used is incorrect { "code": 100, "description": "Invalid Credentials", "type": "INVALID_CREDENTIALS" } // The bank account is invalid { "code": 302, "description": "Invalid bank account", "type": "INVALID_BANK_ACCOUNT" } ``` ### Error Responses Fields
FieldFormatDescription
codeIntegerError code. Click here to check all the possible error codes
typeStringType of the error. Click here to check all the possible error types for refund
descriptionStringHuman readable description of the error
� # Pix Key Validation and Details Endpoint Validate PIX Keys in real time, with their full banking details. ## Account Validation Request `POST` `https://api-stg.onekeypayments.com/v5/account/pix_key/validate/details` This endpoint allows you to validate if a Pix Key exists, and what banking details are tied to this PIX key Check with your Account Manager or Technical Account Manager regarding the production API endpoint. #### 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 Cashouts API Key | | Authorization\* | string | Authorization control hash | #### Request Body | Name | Type | Description | | --------------------------------------------------- | ------ | -------------------------------------------------------------------------------- | | key\_type\* | String | Type of the PIX, this can be either `DOCUMENT`, `EMAIL` , `PHONE` or `RANDOM_ID` | | document\* | String | CPF of the customer. | | pix\_key\* | String | Contains the value of the PIX key that you want to get the details for. | | notification\_url\* | String | API URL utilized to receive the banking information from your side. | **Example Request** ```json { "key_type": "DOCUMENT", "document": "29318456719", "pix_key": "29318456719", "notification_url": "https://test.com" } ``` **Response** {% tabs %} {% tab title="200 Response" %} ```json { "document": "29318456719", "pix_key": "29318456719", "message": "The Pix validation is in progress", "status": "IN_PROGRESS" } ``` {% endtab %} {% tab title="400 Response" %} ```json { "document" : "29318456719", "pix_key" : "29318456719", "status" : "ERROR", "message" : "The Pix key is not valid." } ``` {% endtab %} {% endtabs %} \ **Callback**\ After obtaining the HTTP 200 response, we'll send a callback to your previously designated `notification_url`, this will include all the following banking information, tied to the Pix key: ```json { "key_type": "DOCUMENT", "pix_key": "29318456719", "bank_account": 1234567, "bank_branch": 0199, "bank_code": 33, "ispb_code": 90400888, "account_type": "SAVINGS", "is_licensed": true | false } ``` {% hint style="info" %} In this case, the PIX KEY DOCUMENT "29318456719" would be tied to the banking details in the response. {% endhint %} **Error callback**\ This happens for example when the account CPF does not match the one sent ```json { "document": "96247806175", "pix_key": "96247806175", "message": "An error ocurred during the validation", "status": "ERROR" } ``` **API Messages** | **status** | **Message** | **Description** | | ------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------- | | IN\_PROGRESS | The Pix validation is in progress | The PIX Key exists and we are validating the bank account details | | ERROR | The Pix key does not belong to the document | The account associated to PIX Key sent does not belong to the document sent in the request. | | ERROR | The document is not a CPF | The CPF provided is invalid. | | ERROR | The Pix Key is invalid | The PIX Key does not exist or it’s greylisted. | # API Codes Learn about the API Codes returned by this API ## API Error Codes ### Categories We group the error codes into different categories for better understanding. * `1xx` - Header errors * `2xx` - Merchant/request validations errors * `3xx` - User data errors * `4xx` - Bank errors * `5xx` - Internal server errors ### Error Codes | API Code | HTTP Code | Type | Message | | :------: | :-------: | :----------------------------: | ----------------------------------------------------------------------------------------------------------------------- | | 100 | 401 | `INVALID_CREDENTIALS` | Invalid credentials | | 101 | 400 | `MISSING_REQUIRED_HEADER` | Missing or invalid format for required header {0} | | 102 | 401 | `INVALID_SIGNATURE` | Invalid signature | | 103 | 400 | `INVALID_DATE_RANGE` | X-Date header value out of valid range | | 200 | 405 | `METHOD_NOT_ALLOWED` | Request method {0} not supported | | 201 | 401 | `INVALID_IP` | Unregistered IP address | | 202 | 400 | `INVALID_REQUEST_BODY` | Invalid request body: {0} | | 203 | 403 | `FORBIDDEN_MERCHANT` | Merchant not allowed to use this api | | 300 | 400 | `INVALID_DOCUMENT` | Invalid document number | | 301 | 400 | `INVALID_BANK_CODE` | Invalid bank code | | 302 | 400 | `INVALID_BANK_ACCOUNT` | Invalid bank account | | 303 | 400 | `INVALID_BANK_BRANCH` | Invalid bank branch | | 305 | 400 | `MISSING_REQUIRED_FIELDS` | Missing required fields | | 306 | 400 | `INVALID_PIX_KEY` | Invalid Pix Key | | 307 | 400 | `COUNTRY_NOT_AVAILABLE` | Country not available | | 308 | 400 | `INVALID_AMOUNT` | Invalid amount. The minimum is {amount} {currency} or equivalent in {currency} | | 309 | 400 | `INVALID_CURRENCY` | Invalid Currency | | 310 | 400 | LIMIT\_EXCEEDED | Limit exceeded | | 311 | 400 | USER\_LIMIT\_EXCEEDED | Transaction declined because the limit of cashouts allowed from different users to that Bank Account has been exceeded. | | 400 | 400 | `BANK_ACCOUNT_BLOCKED` | The bank account is blocked | | 401 | 400 | `BANK_ACCOUNT_CLOSED` | The bank account is closed | | 402 | 400 | `INVALID_BENEFICIARY_NAME` | The beneficiary name doesn't match the bank details | | 403 | 400 | `INVALID_BENEFICIARY_DOCUMENT` | The beneficiary document doesn't match the bank details | | 404 | 400 | `INVALID_ACCOUNT_TYPE` | Invalid account type | | 405 | 400 | `TRANSFER_TYPE_NOT_SUPPORTED` | The transfer type is not supported on this account | | 406 | 400 | `BANK_ACCOUNT_UNAVAILABLE` | The account is unable to receive transfers | | 407 | 400 | `OTHER` | Other | | 408 | 400 | `REJECTED_BY_BANK` | Rejected by bank | | 500 | 500 | `INTERNAL_SERVER_ERROR` | Oh no! Something has gone wrong. Please contact a system administrator. | # Cards SDK Learn the technical aspects about our Cards SDK, in order to have the ultimate native checkout experience. #### What is Cards SDK about? Our SDK is designed to simplify the process of integrating payments into your application, allowing you to handle payments securely and efficiently without needing to meet strict PCI requirements. We offer two integration modes: 1. 1.**With User Interface**: Ideal for quick and easy integration with a ready-to-use user interface, and very customizable. 2. 2.**Without User Interface**: Perfect for those who need a more customized integration and full control over the payment process. #### Benefits of Using Our SDK * **Easy to Integrate**: With straightforward instructions and code examples, you can have the payment system up and running in no time. * **Secure**: Our system complies with the highest security standards, eliminating the need for your application to be PCI compliant. * **Customizable**: We offer customization options to match the look and feel of your application. #### Select the SDK type that suits best for you! * ​[With User Interface](/deposits-tools/cards-sdk/with-user-interface)​ * [​Without User Interface](/deposits-tools/cards-sdk/without-user-interface)​ ​​ # With User Interface Learn the technical aspects about our Cards SDK, in order to have the ultimate native checkout experience. ### Getting started This guide introduces the D24 Credit Card SDK, aimed at simplifying credit card processing integration. Follow these steps for a quick setup and start leveraging secure payment processing in your application. {% hint style="info" %} This page is limited to the explanation of how to Install, Instantiate and technically understand the SDK.\ In order to learn how to create a integrate the Cards SDK in the payment flow, please visit [Deposits with Cards SDK](broken://pages/KtV3jRp0Oid6MvGEguvF)**.** {% endhint %} ### Installation #### **Load D24 as a npm module** Install the D24.js from the npm public registry. ```bash npm install @d24/sdk ``` or #### **Manually load the D24.js script** Add the D24.js module as a script in the top of your app HTML ```html ``` ### How to use #### **Instantiation** First of all, we must instantiate the SDK. Keep in mind that the SDK can be instantiated only once, and it is a requirement to be able to use all its methods. In order to instantiate the SDK we need to specify the **public key** and the **environment**. {% hint style="info" %} #### Retrieving your `publicKey` Before instantiating the SDK make sure to retrieve your publicKey.\ This can be done by: Logging into the Merchant Panel, going into **Settings** > **API Access**, under your **Read Only Credentials** you will find your **API Public key**. {% endhint %} * npm ```javascript import SDK from '@d24/sdk'; new SDK('as1i2nxal12bvd', { environment: 'stg' }); ``` * es ```javascript new window.D24.SDK('as1i2nxal12bvd', { environment: 'stg' }); ``` ### How to use the constructor `SDK(publicKey, options)` ***Required parameters***
ParameterTypeDescriptionRequiredPossible values
publicKeystringPublic key provided by ustrue-
optionsobjectOptionstrue-
options.environmentstringEnvironmenttruestg, prod
options.localestringLocaletrueen, es, pt
**Possible errors** | Error | Explanation | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | SDK was already instantiated. | The SDK has already been instantiated and you are trying to instantiate it again | | The environment \[config.environment] is not supported. | The environment you passed to the constructor is not valid, remember that it only accepts "`stg`" or "`prod`" | | You must instantiate D24CreditCardSDK before using SDK methods | You attempted to use the SDK features without having previously instantiated it. | ## CreditCardForm After instantiating the SDK, you will be able to use the **CreditCardForm** component. ```typescript ``` ### Properties
PropertyTypeDescriptionRequiredExampleDefaultPossible values
authTokenstringThe checkout_token returned by the Deposit Creation Endpoint.true
countrystringCountry codetrueCL
onTokenGenerationErrorfunctionCallback function that will be executed when an error occurs generating tokentrue-
onBackfunctionCallback function that will be executed when the user clicks on the Go Back buttontrue-
### Callbacks #### `onTokenGenerationError` This callback function will be executed when an error occurs generating token. ```typescript function handleTokenErrorCallback(error: string) { console.log(error); } ``` #### `onBack` This callback function will be executed when the user clicks on the Go Back button. ```typescript function handleGoBackCallback() { console.log('Go back'); } ``` ## Deposit Creation To learn who to use the Cards SDK With User Interface within the Deposit Creation, please visit de page below of our Knowledge Base :sunglasses: {% content-ref url="/pages/HaFdbXh6mKPwYB0ARkS7" %} [With User Interface](/knowledge-base/deposits-with-cards-sdk/with-user-interface) {% endcontent-ref %} # Color Customization Elevate your user experience with our advanced color customization feature. We provide a bespoke version of the theme to perfectly match the unique style of your websited's UI. To fine-tune the colors, simply add a `colorSchema[]` object as illustrated in the example. {% hint style="success" %} You don't need to send the entire object, you can include the sections you would like to change. {% endhint %} ### `colorSchema[]` object 
const colorSchema = {
  //primary button is to complete the action like "Complete payment" and "Continue"
  "button": {
    "primary": {
      "background": {
        "default": "#3C5BFC",
        "hover": "#7087FF",
        "active": "#2E47C9"
      },
      "text": {
        "color": {
          "default": "#FFFFFF"
        }
      }
    },
    //this is the link button like "go back"
    "tertiary": {
      "text": {
        "color": {
          "default": "#3C5BFC"
        }
      }
    }
  },
  //This affect the inputs and select
  "input": {
    "background": {
      "default": "#FFFFFF",
      "locked": "#E6E7EB"
    },
    "border": {
      "color": {
        "default": "#373840",
        "locked": "#D5D6DE",
        "active": "#3C5BFC",
        "error": "#CF3434"
      }
    },
    "text": {
      "color": {
        "label": "#B0B3BF",
        "input": "#0B1130",
        "placeholderHint": "#B0B3BF"
      }
    }
  },
  //This affects the text that is not related to the inputs.
  "text": {
    "color": "#373840"
  },
  //This is the background color of the label on the input and select when add some value
  "label": {
    "background": "#FFFFFF"
  }
};
### Visual references In the images below you will find the visual references of the colorSchema parameters and color customization possibilities. ![](https://docs.d24.com/~gitbook/image?url=https%3A%2F%2F773174111-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-M792I7hN0PzC-Sx95CP-887967055%252Fuploads%252FK1qSimGh6A4xYUHLhGCu%252Fcc-checkout-payment-select.jpg%3Falt%3Dmedia%26token%3D59e97d75-ee7f-43c8-ad4e-206f1bd926bd\&width=768\&dpr=4\&quality=100\&sign=f2bbdee6440bff59ec6c129c08f89a7810d9d948faf0b20a1f80ff52811a4151)![](https://docs.d24.com/~gitbook/image?url=https%3A%2F%2F773174111-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-M792I7hN0PzC-Sx95CP-887967055%252Fuploads%252FuHAT4pky1FWz59PZCXJw%252Fcc-checkout-payment.jpg%3Falt%3Dmedia%26token%3D4912717c-d3d9-41a4-85d5-bad15201df36\&width=768\&dpr=4\&quality=100\&sign=a0721f72118d5604091d4638915eb556427305cd46e0453443dd682cfed0b701)![](https://docs.d24.com/~gitbook/image?url=https%3A%2F%2F773174111-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-M792I7hN0PzC-Sx95CP-887967055%252Fuploads%252FzUupkPysdC4TKfYXcEqP%252Fcc-checkout-status.jpg%3Falt%3Dmedia%26token%3Daefbc439-0dbb-4f9e-9d8c-edd225a33338\&width=768\&dpr=4\&quality=100\&sign=ebc27191c9e6672d5a1d47e42fd453c890095e0595c2b6b9661dcd02c5104452) [^1]: # Without User Interface Learn how to use our SDK in Javascript to allow integrations with our Deposits APIs ## Getting started ### Installation #### Load D24 as a npm module Install the D24.js from the npm public registry. ```bash npm install @d24/sdk-minimal ``` or #### Manually load the D24.js script Add the D24.js module as a script in the of your app HTML ```markup ``` ### How to use #### Instantiation First of all, we must instantiate the SDK. Keep in mind that the SDK can be instantiated only once, and it is a requirement to be able to use all its methods. In order to instantiate the SDK we need to specify the public key and the environment. * npm ```javascript import SDK from '@d24/sdk-minimal'; new SDK('as1i2nxal12bvd', {environment: 'stg'}); ``` * umd ```javascript new window.D24.SDK('as1i2nxal12bvd', {environment: 'stg'}); ``` **constructor(publicKey, options)** **Parameters**
ParameterTypeDescriptionRequiredPossible values
publicKeystringPublic key provided by ustrue-
optionsobjectOptionstrue-
options.environmentstringEnvironmenttruestg, production
#### Tokenization a credit card Once we instantiate the SDK, we can tokenize a card, said token will be used later to send it to the backend and generate the payment through an endpoint. * npm ```javascript import {generateToken} from '@d24/sdk-minimal'; const creditCard = { number: '4509953566233704', holder: 'Juan Perez', cvv: '123', expirationMonth: '11', expirationYear: '25', } const response = await generateToken({card: creditCard}); const token = response.token; ``` * umd ```javascript const creditCard = { number: '4509953566233704', holder: 'Juan Perez', cvv: '123', expirationMonth: '11', expirationYear: '25', } const response = await window.D24.generateToken({card: creditCard}); const token = response.token; ``` ## API #### Possible errors | Error | Explanation | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | SDK was already instantiate. | The SDK has already been instantiated and you are trying to instantiate it again | | The environment \[config.environment] is not supported. | The environment you passed to the constructor is not valid, remember that it only accepts "test" or "prod" | ### generateToken({card}): Promise<{token: string}> This method validates that the card data is correct and generates a token. Although it has validations that occur at the frontend level, it uses a D24 endpoint to be able to generate the token which executes additional validations. To validate the data structure, the [joi](https://joi.dev/api/?v=17.9.1#errors) library is used, therefore the errors returned at the frontend level are generated with said library. #### Parameters
ParameterTypeDescriptionRequiredExample
cardobjectCredit card valuestrue-
card.numberstringCredit card numbertrue4509953566233704
card.holderstringCredit card holdertrueJuan Perez
card.cvvstringCredit card security code. Must be 3 digits, except for AMEX which are 4true123, 1234
card.expirationMonthstringCredit card expiration month. Must be 2 digitstrue11
card.expirationYearstringCredit card expiration year. Must be 2 digitstrue25
#### Possible errors | Error | Explanation | | -------------------------------------------------------------- | ---------------------------------------------------------------------- | | You must instantiate D24CreditCardSDK before using SDK methods | You executed the method without having previously instantiated the SDK | ## Deposit Creation To learn who to use the Cards SDK Without User Interface within the Deposit Creation, please visit de page below of our Knowledge Base :sunglasses: {% content-ref url="/pages/2YOaKheDYzkTqbaiykan" %} [Without User Interface](/knowledge-base/deposits-with-cards-sdk/without-user-interface) {% endcontent-ref %} # Java SDK Learn how to use our SDK in Java to facilitate even further the integration with our Deposits APIs ## Introduction The Deposits Java SDK (Software Development Kit) is a software package you can download and add to your existing code facilitating the integration by having pre-defined classes and functions you can call to integrate the [Deposits Endpoints](/api-documentation/deposits-api/endpoints). Review and download the source code from GitHub by clicking on the button below[![Open in GitHub](https://www.kindpng.com/picc/m/141-1419051_github-icon-png-transparent-png.png)](https://github.com/directa24/cashin-java-sdk/) ## Installation ### Requirements * Java 1.8 or later ### Gradle Users Add this dependency to your project's build file: {% code title="Java Gradle Dependency" %} ```java implementation "com.directa24:cashin-java-sdk:1.0.13" ``` {% endcode %} ### Maven Users Add this dependency to your project's POM: {% code title="Java Maven dependency" %} ```markup com.directa24 cashin-java-sdk 1.0.13 ``` {% endcode %} #### ### Dependencies The library uses [Project Lombok](https://projectlombok.org/). While it is not a requirement, you might want to install a [plugin](https://projectlombok.org/setup/overview) for your favorite IDE to facilitate development. [JUnit 4](https://junit.org/junit4/) and [Wiremock](http://wiremock.org/) library are needed to run the bundled tests. ## Usage Begin by initializing your credentials ### **Deposit Credentials** ```java String depositKeySbx = "fUEhPEKrUt"; String secretKeySbx = "wSHTfsMMdNskTppilncuZPEklgLmdUAOg"; Directa24 directa24Sandbox = new Directa24.Sandbox(depositKeySbx, secretKeySbx); ``` ### **Read-Only Credentials** ```java String readOnlyKeySbx = "EKiFOWiHnI"; Directa24 directa24Sandbox = new Directa24.Sandbox(readOnlyKeySbx); ``` {% hint style="success" %} Make sure you have whitelisted your servers IPs on our Merchant Panel by going to Settings -> API Access. {% endhint %} [Click here](/api-documentation/deposits-api/technical-and-security-aspects#api-keys) for more information about the API Keys. Once the credentials and the IPs have been properly set-up, you are ready to start using the classes the SDK provides. Each Class can be used to execute the functionalities of its respective [Deposit Endpoint.](/api-documentation/deposits-api/endpoints) Make sure you take a look at the [Deposit Endpoints here](/api-documentation/deposits-api/endpoints) to review how the integration of each of them works, the validations and the responses formats. {% hint style="success" %} As soon as you are ready with the integration and you have the production credentials, replace the credentials for the production ones. {% endhint %} ## Classes {% hint style="success" %} heck the respective [Endpoint Page ](/api-documentation/deposits-api/endpoints)to see the format of the responses, fields requirements and validations. {% endhint %} ### Create Deposit Every time you need to create a deposit, you will need to invoke the `CreateDepositRequest` Class with all the objects containing the information required to be sent. The amount of information required depends on the flow you have chosen, either the [Hosted Checkout Experience](/api-documentation/deposits-api#hosted-checkout-experience) or the [ONE SHOT Experience.](/api-documentation/deposits-api#oneshot-experience) ```java public class CreateDepositExample { public static void main(String[] args) { Address address = Address.builder() .street("Rua Dr. Franco Ribeiro, 52") .city("Rio Branco") .state("AC") .zipCode("11600-234") .build(); Payer payer = Payer .builder() .id("4-9934519") .address(address) .document("21329039050") .documentType("CPF") .email("juanCarlos@hotmail.com") .firstName("Ricardo") .lastName("Carlos") .phone("+59899000878") .build(); BankAccount bankAccount = BankAccount .builder() .bankCode("01") .accountNumber("3242342") .accountType("SAVING") .beneficiary("Ricardo Carlos") .branch("12") .build(); CreateDepositRequest createDepositRequest = CreateDepositRequest .builder() .invoiceId("108") .amount(new BigDecimal(100)) .country("BR") .currency("BRL") .payer(payer) .paymentMethod("BB") .paymentType("BANK_TRANSFER") .bankAccount(bankAccount) .earlyRelease(false) .feeOnPayer(false) .surchargeOnPayer(false) .bonusAmount(BigDecimal.ONE) .bonusRelative(false) .strikethroughPrice(BigDecimal.ONE) .description("Test") .clientIp("186.51.171.84") .language("es") .deviceId("00000000-00000000-01234567-89ABCDEF") .backUrl("https://yoursite.com/deposit/108/cancel") .successUrl("https://yoursite.com/deposit/108/confirm") .errorUrl("https://yoursite.com/deposit/108/error") .notificationUrl("https://yoursite.com/ipn") .logo("https://yoursite.com/logo.png") .test(true) .mobile(false) .idempotency("") .build(); try { CreateDepositResponse createDepositResponse = directa24Sandbox.client.createDeposit(createDepositRequest); // Handle response } catch (Directa24Exception e) { // Handle errors } } } ``` {% hint style="info" %} CreateDepositRequest.amount and CreateDepositRequest.country are the only mandatory fields for a successful request. The rest of the fields needs to be sent depending on the flow you have chosen as those will be collected by us if not sent. {% endhint %} ### ### Deposit Status As soon as the deposit is created and you have received the notification in your `notification_url`, you will want to invoke the `DepositStatusRequest` Class to retrieve the [status](/api-documentation/deposits-api/api-codes#deposits-status-codes) of the deposit. Click here to see the [deposits status flow.](/api-documentation/deposits-api/endpoints/refund-status-endpoint#status-flow) ```java public class DepositStatusExample { public static void main(String[] args) { DepositStatusRequest depositStatusRequest = DepositStatusRequest .builder() .id(300000001) .build(); try { DepositStatusResponse depositStatusResponse = directa24Sandbox.client.depositStatus(depositStatusRequest); // Handle response } catch (Directa24Exception e) { // Handle errors } } } ``` {% hint style="success" %} Make sure you are adding the deposit\_id received on your notification\_url in the field DepositStatusRequest.id. {% endhint %} ### Payment Methods For the best user experience, we recommend integrating our [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to automatically retrieve the [list](/api-documentation/deposits-api/payment-methods) of payment methods name, logos, types and more that your account has available. In order to do that, invoke the `PaymentMethodRequest` Class containing the [Country's ISO code](/knowledge-base/countries-specifications#countries-and-currencies) of the country you need the payment methods from in the field `PaymentMethodRequest.country` ```java public class PaymentMethodsExample { public static void main(String[] args) { PaymentMethodRequest paymentMethodRequest = PaymentMethodRequest .builder() .country("BR") .build(); try { List paymentMethodResponse = directa24Sandbox.client.paymentMethods(paymentMethodRequest); // Handle response } catch (Directa24Exception e) { // Handle errors } } } ``` ### Exchange Rates If you need to know the Exchange Rate of a given currency, you can do so by invoking `ExchangeRateRequest` with the [Country's ISO code](/knowledge-base/countries-specifications#countries-and-currencies) of the origin and the amount you want to convert to USD. ```java public class ExchangeRateExample { public static void main(String[] args) { ExchangeRateRequest exchangeRatesRequest = ExchangeRateRequest .builder() .country("BR") .amount(BigDecimal.TEN) .build(); try { ExchangeRateResponse exchangeRateResponse = directa24Test.client.exchangeRates(exchangeRateRequest); // Handle response } catch (Directa24Exception e) { // Handle errors } } } ``` ### Create Refund In order to create a refund, you need to send the deposit\_id, merchant\_invoice\_id, and the bank\_account object (only for non-cc payments, otherwise, it is optional). ```java public class CreateRefundTest extends AbstractDirecta24Test { @Before public void createMocks() { stubFor(post(urlMatching("/v3/refunds")) .withHeader("X-Login", equalTo(DEPOSIT_KEY)) .withHeader("Content-Type", equalTo("application/json")) .willReturn(aResponse().withStatus(200).withHeader("Content-Type", "application/json").withBody("{\"refund_id\": 1000043\n}"))); } @Test public void createRefundTest() throws Directa24Exception { Directa24 directa24Test = new Directa24.Test(DEPOSIT_KEY, SECRET_KEY); BankAccount bankAccount = BankAccount .builder() .bankCode("01") .accountNumber("3242342") .accountType("SAVING") .beneficiary("Ricardo Carlos") .branch("12") .build(); CreateRefundRequest createRefundRequest = CreateRefundRequest .builder() .depositId(9999) .invoiceId("1234") .amount(new BigDecimal(100)) .bankAccount(bankAccount) .comments("Test") .notificationUrl("https://yoursite.com/ipn") .idempotency("") .build(); CreateRefundResponse createRefundResponse = directa24Test.client.createRefund(createRefundRequest); assertTrue(createRefundResponse != null && createRefundResponse.getRefundId() != null); verify(postRequestedFor(urlEqualTo("/v3/refunds")).withHeader("Content-Type", equalTo("application/json"))); } } ``` ### Refund Status ```java public class RefundStatusTest extends AbstractDirecta24Test { @Before public void createMocks() { stubFor(get(urlMatching("/v3/refunds/123456")) .withHeader("X-Login", equalTo(DEPOSIT_KEY)) .withHeader("Content-Type", equalTo("application/json")) .willReturn(aResponse() .withStatus(200) .withHeader("Content-Type", "application/json") .withBody( "{\"deposit_id\": 300537729,\"merchant_invoice_id\": \"postmanTest971574817\",\"status\": \"PENDING\",\"amount\": 1000.00}"))); stubFor(get(urlMatching("/v3/refunds/999999")) .withHeader("X-Login", equalTo(DEPOSIT_KEY)) .withHeader("Content-Type", equalTo("application/json")) .willReturn(aResponse().withStatus(404).withHeader("Content-Type", "application/json"))); } @Test public void refundStatusTest() throws Directa24Exception { Directa24 directa24Test = new Directa24.Test(DEPOSIT_KEY, SECRET_KEY); RefundStatusRequest refundStatusRequest = RefundStatusRequest.builder() // .id(123456) // .build(); RefundStatusResponse refundStatusResponse = directa24Test.client.refundStatus(refundStatusRequest); assertTrue(refundStatusResponse != null); assertEquals(refundStatusResponse.getStatus(), "PENDING"); verify(getRequestedFor(urlEqualTo("/v3/refunds/" + 123456)).withHeader("Content-Type", equalTo("application/json"))); } @Test public void refundNotFoundTest() { Directa24 directa24Test = new Directa24.Test(DEPOSIT_KEY, SECRET_KEY); RefundStatusRequest refundStatusRequest = RefundStatusRequest.builder() // .id(999999) // .build(); RefundStatusResponse refundStatusResponse = null; try { refundStatusResponse = directa24Test.client.refundStatus(refundStatusRequest); fail("Refund doesn't exists"); } catch (Directa24Exception e) { } assertTrue(refundStatusResponse == null); } ``` # PHP SDK Learn how to use our SDK in PHP to facilitate even further the integration with our Deposits APIs ## Introduction The Deposits PHP SDK (Software Development Kit) is a software package you can download and add to your existing code facilitating the integration by having pre-defined classes and functions you can call to integrate the [Deposits Endpoints](/api-documentation/deposits-api/endpoints). Review and download the source code from GitHub by clicking on the button below[![Open in GitHub](https://www.kindpng.com/picc/m/141-1419051_github-icon-png-transparent-png.png)](https://github.com/directa24/cashin-php-sdk/) ## Installation ### Requirements * PHP 5.6 or later ### Install Via Composer {% code title="Install PHP SDK via Composer" %} ```php composer require directa24/cashin-php-sdk ``` {% endcode %} ## Usage Begin by initializing your credentials ### **Deposit Credentials** ```java $x_login = "fUEhPEKrUt"; $api_key = "lTMZgRTakW"; $secret_key = "wSHTfsMMdNskTppilncuZPEklgLmdUAOg"; $directa24 = Directa24::getInstance($x_login, $api_key, $secret_key); ``` {% hint style="success" %} Make sure you have whitelisted your servers IPs on our Merchant Panel by going to Settings -> API Access. {% endhint %} [Click here](/api-documentation/deposits-api/technical-and-security-aspects#api-keys) for more information about the API Keys. Once the credentials and the IPs have been properly set-up, you are ready to start using the classes the SDK provides. Each Class can be used to execute the functionalities of its respective [Deposit Endpoint.](/api-documentation/deposits-api/endpoints) Make sure you take a look at the [Deposit Endpoints here](/api-documentation/deposits-api/endpoints) to review how the integration of each of them works, the validations and the responses formats. {% hint style="success" %} As soon as you are ready with the integration and you have the production credentials, replace the credentials with the production ones and set the ProductionMode to True to use the production endpoints. {% endhint %} {% code title="Set Production Mode to True" %} ```php Directa24::setProductionMode(true); ``` {% endcode %} ## Classes {% hint style="success" %} Check the respective [Endpoint Page ](/api-documentation/deposits-api/endpoints)to see the format of the responses, fields requirements and validations. {% endhint %} ### Create Deposit Every time you need to create a deposit, you will need to invoke the `CreateDepositRequest` Class with all the objects containing the information required to be sent. The amount of information required depends on the flow you have chosen, either the [Hosted Checkout Experience](/api-documentation/deposits-api#hosted-checkout-experience) or the [ONE SHOT Experience.](/api-documentation/deposits-api#oneshot-experience) #### Hosted Checkout Experience ```java $create_deposit_request = new CreateDepositRequest(); $create_deposit_request->invoice_id = Helpers::generateRandomString(8); $create_deposit_request->amount = 100; $create_deposit_request->country = "BR"; $create_deposit_request->currency = "BRL"; $create_deposit_request->language = "en"; try { $response = $directa24->createDeposit($create_deposit_request); if ($response->checkout_type === 'HOSTED') { $redirect_url = $response->redirect_url; $response->deposit_id; $response->user_id; $response->merchant_invoice_id; header('Location: '. $redirect_url); } echo json_encode($response); } catch (Directa24Exception $ex){ echo $ex; } ``` #### #### ONE SHOT Experience ```php $address = new Address(); $address->street = "Rua Dr. Franco Ribeiro, 52"; $address->city = "Rio Branco"; $address->state = "AC"; $address->zip_code = "11600-234"; $payer = new Payer(); $payer->id = "4-9934519"; $payer->address = $address; $payer->document = "72697858059"; $payer->document_type = "CPF"; $payer->email = "juanCarlos@hotmail.com"; $payer->first_name = "Ricardo"; $payer->last_name = "Carlos"; $payer->phone = "+598 99730878"; $bank_account = new BankAccount(); $bank_account->bank_code = "01"; $bank_account->account_number = "3242342"; $bank_account->account_type = "SAVING"; $bank_account->beneficiary = "Ricardo Carlos"; $bank_account->branch = "12"; $create_deposit_request = new CreateDepositRequest(); $create_deposit_request->invoice_id = Helpers::generateRandomString(8); $create_deposit_request->amount = 100; $create_deposit_request->country = "BR"; $create_deposit_request->currency = "BRL"; $create_deposit_request->language = "en"; $create_deposit_request->payer = $payer; $create_deposit_request->payment_method = "BB"; $create_deposit_request->bank_account = $bank_account; $create_deposit_request->early_release = false; $create_deposit_request->fee_on_payer = false; $create_deposit_request->surcharge_on_payer = false; $create_deposit_request->bonus_amount = 0.1; $create_deposit_request->bonus_relative = false; $create_deposit_request->strikethrough_price = 0.1; $create_deposit_request->description = "Test"; $create_deposit_request->client_ip = "186.51.171.84"; $create_deposit_request->device_id = "00000000-00000000-01234567-89ABCDEF"; $create_deposit_request->back_url = "https://yoursite.com/deposit/108/cancel"; $create_deposit_request->success_url = "https://yoursite.com/deposit/108/confirm"; $create_deposit_request->error_url = "https://yoursite.com/deposit/108/error"; $create_deposit_request->notification_url = "https://yoursite.com/ipn"; $create_deposit_request->test = true; $create_deposit_request->mobile = false; try { $response = $directa24->createDeposit($create_deposit_request); if ($response->checkout_type === 'ONE_SHOT') { $payment_info = $response->payment_info; if ($payment_info->type === 'CREDIT_CARD') { header('Location: ' . $response->redirect_url); } // Referenced transfer if ($payment_info->type === 'BANK_TRANSFER') { header('Location: ' . $response->redirect_url); } // Bank deposit if ($payment_info->type === 'BANK_DEPOSIT') { echo '
';
            print_r($payment_info->metadata);
            echo '
'; } // Several types of payment methods: Boleto, Picpay, Oxxo if ($payment_info->type === 'VOUCHER') { $metadata = $payment_info->metada; if (isset($metadata->qr_code)) { echo ''; } else if (isset($metadata->digital_line) || isset($metadata->barcode)) { echo '
';
                print_r($metadata);
                echo '
'; } } } } catch (\Directa24Exception $ex) { echo $ex; } ``` {% hint style="info" %} The amount and the country are the only mandatory fields for a successful request. The rest of the fields needs to be sent depending on the flow you have chosen as those will be collected by us if not sent. {% endhint %} ### Deposit Status As soon as the deposit is created and you have received the notification in your `notification_url`, you will want to retrieve the [status](/api-documentation/deposits-api/api-codes#deposits-status-codes) of the deposit. Click here to see the [deposits status flow.](/api-documentation/deposits-api/endpoints/refund-status-endpoint#status-flow) ```java $depositId = 300533668; $directa24->depositStatus($depositId); ``` {% hint style="success" %} Make sure you are adding the deposit\_id received on your notification\_url in the field depositId. {% endhint %} ### Payment Methods For the best user experience, we recommend integrating our [Payment Methods Endpoint](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to automatically retrieve the [list](/api-documentation/deposits-api/payment-methods) of payment methods name, logos, types and more that your account has available. In order to do that, invoke the `PaymentMethodRequest` Class containing the [Country's ISO code](/knowledge-base/countries-specifications#countries-and-currencies) of the country you need the payment methods from in the field `PaymentMethodRequest.country` ```java $data = $this->directa24->paymentMethods('BR'); foreach ($data as $paymentMethodResponse) { $paymentMethodResponse->country; } ``` ### Exchange Rates If you need to know the Exchange Rate of a given currency, you can do so by invoking `ExchangeRateRequest` with the [Country's ISO code](/knowledge-base/countries-specifications#countries-and-currencies) of the origin and the amount you want to convert to USD. ```java $amount_in_dollars = 100; $country = 'BR'; $data = $this->directa24->currencyExchange($country, $amount_in_dollars); ``` ### Create Refund In order to create a refund, you need to send the deposit\_id, merchant\_invoice\_id, and the bank\_account object (only for non-cc payments, otherwise, it is optional). ```java $bank_account = new BankAccount(); $bank_account->bank_code = "01"; $bank_account->account_number = "3242342"; $bank_account->account_type = "SAVING"; $bank_account->beneficiary = "Ricardo Carlos"; $bank_account->branch = "12"; $create_refund_request = new CreateRefundRequest(); $create_refund_request->deposit_id = 300533180; $create_refund_request->invoice_id = 'MP_b451645f30b8415ba833d37f3fa21209'; $create_refund_request->amount = 1; $create_refund_request->bank_account = $bank_account; $create_refund_request->comments = 'test'; $create_refund_request->notification_url = "https://yoursite.com/deposit/108/confirm"; $directa24 = Directa24::getInstance("fUEhPEKrUt", "lTMZgRTakW", "wSHTfsMMdNskTppilncuZPEklgLmdUAOg"); try { $refund_id = $directa24->refund($create_refund_request); echo $refund_id; } catch (\Directa24Exception $ex) { echo $ex; } ``` ### Refund Status ```java $refundId = 168250; $directa24->refundStatus($refundId); ``` # Javascript Library Learn how to build and personalize your own custom cashiers by using our library in Javascript ## Introduction We have created a library in Javascript that you can use to build your very own cashier directly into your site, giving you all the control just as if it would have been created by you. The library's fonts and styles can be completely customizable according to your own website UI/UX, and we will take care of rendering the necessary payment methods and required fields for each payment method. Once all the payments details have been collected, a POST will be made to your server with the details you can use then to [create the deposit request using our Deposits API.](/api-documentation/deposits-api) In just a few steps, you will be able to start collecting payments through us by using our Javascript Library. See first-hand the following example of a cashier created using the directa24.js library {% embed url="" %} ![](/files/-MLtcraiW_zmDR-D-aiM) ![](/files/-MLtd35tVFRvON0YRXBo) ## Getting started Follow the below steps to get the library working on your site: 1. Include the directa24.js library 2. Prepare the `directa24` object with your API Key 3. Include all the required values such as amount and country and the optional values such as currency, language, payer data and CSS/Javascript styles object 4. Initialize the directa24.js library to render the cashier on your site and allow the customer to complete the payment flow 5. Submit the form info collected to your server and send the payment request to our Deposits API ### Requirements Before getting started, please consider the following requirements: 1. Your site must have HTTPS implemented in order for the library to work properly. 2. You will need to have a server listening to a POST (over HTTPS as well) with the payment data in order for you to send the request through our Deposits API. 3. You will need to register with us to get an API Key to authenticate yourself. ## 1. Including directa24.js The first step is to include the Javascript Library onto your index.html file. In order to do so, please add the following ` ``` Note the Library must always be loaded directly from : ```markup https://connect-js.directa24.com ``` For testing purposes you can use: ```markup https://connect-js-stg.directa24.com ``` {% hint style="success" %} While adding or modifying features to the directa24.js library, please keep the browser's console open to see any error/message it can throw. {% endhint %} The API Keys between Production and STG environments are different. ## 2. Preparing the directa24 object Now that you have included the directa24.js library, a new object called `directa24` is created on the window. The second step is to prepare your API Key and all the parameters that will be sent before rendering the form to the customer. To do so, instantiate the library as follows: ```javascript let directa24Lib = directa24('EKiFOWiHnI', params); ``` The API Key can be retrieved from our Merchant Panel by going to Settings -> API Access -> Web Status Credentials -> API Key. ## 3. Including required parameters Create an object named `params` with all the required and optional fields you want to send as follows: ```javascript const params = { country: 'BR', amount: 100, currency: 'USD', lang: 'PT', url: 'https://directa24-js.com/deposit', payerData: { payerFirstName: 'FirstName', payerLastName: 'LastName', payerEmail: 'payerEmail@test.com' }, disableInputDefaultValue: true } ``` ### Mandatory Parameters | Parameter name | Format | Description | Default | Validations | | -------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: | :-------------------------------------------------------------------------------------------------: | | `country` | string (length: 2) | Country code of the deposit in *ISO 3166-1 alpha-2 code* format | | [See country codes](/knowledge-base/countries-specifications#currencies) | | `amount` | decimal (max decimals: 2) | Deposit amount in the currency specified | | > 0 | | `currency` | string (length: 3) | Currency code of the amount in *ISO 4217* format. Must be USD or the country's local currency | | [See currency codes](/knowledge-base/countries-specifications#countries-and-currencies). Upper case | | `lang` | string (length: 2) | Language in which the deposit page will be rendered | `EN` | Spanish, English or Portuguese: `[ES, EN, PT]` | | `url` | string (max length: 2048) | Valid URL over HTTPS. It will be used to POST the form data collected to your server so you can send the payment request through our [Deposits API](/api-documentation/deposits-api). | | `HTTPS URL` | ### Optional Parameters | Parameter name | Format | Description | Default | Validations | | ----------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- | :-----: | :---------------------------------------------------------------------------------------------: | | `disableInputDefaultValue` | boolean | Allow or disallow the customers to modify the parameters you send in the object payerData | `false` | `[true, false]` | | `styles` | Object | Override the default CSS styles with your own CSS/JavaScript Object | | [View details](/deposits-tools/javascript-library#styles) | | `payerData.payerFirstName` | string (max length: 128) | Customer's first name | | String of up to 128 characters | | `payerData.payerLastName` | string (max length: 128) | Customer's last\_name | | String of up to 128 characters | | `payerData.payerEmail` | string (max length: 255) | Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits | | Valid email address | | `payerData.payerDocumentType` | string (max length: 10) | Customer's document type | | [document types validations](/knowledge-base/countries-specifications#documents) | | `payerData.payerDocument` | string (max length: 30) | | | [document validations](/knowledge-base/countries-specifications#documents) | | `payerData.payerPhone` | string (max length: 32) | Valid customer's phone number | | [phone number validations](/knowledge-base/countries-specifications#mobile-numbers-validations) | | `payerData.payerAddress` | string (max length: 255) | Customer's address | | String of up to 255 characters | | `payerData.payerCity` | string (max length: 128) | Customer's city | | String of up to 128 characters | | `payerData.payerState` | string (max length: 3) | Customer's state in [*ISO 3166-2 code* format](https://en.wikipedia.org/wiki/ISO_3166-2) | | Valid state code in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) | | `payerData.payerZipcode` | string (max length: 16) | Customer's zip code | | [Zip code validations](/knowledge-base/countries-specifications#postal-code-validations) | {% hint style="info" %} Even though those parameters are optional, we recommend you sending all the optional parameters you have already stored on your DB to avoid asking the customer for the same details multiple times. {% endhint %} ### The object *STYLES* The object `styles` allows you to override the default styles of the library. It has to be a CSS/Javascript object. To know more about CSS into a Javascript object, we recommend reading the following pages: {% embed url="" %} {% embed url="" %} To transform a CSS file to a Javascript Object, you may use the following tool: {% embed url="" %} Apart from the CSS properties you can specify, you can also modify other components of the library by directly specifying the name of the property inside the object style as described in the following sections. #### Font To overwrite the font used by the library, you can specify the property `font` inside the object `styles`. ```javascript const params ={ ... "styles":{ "font":{ "fontFamily":"Epilogue" } } } ``` Inside the `font` object you can modify any attribute, such as the color, weight, etc. #### Container The library is inside a `
` with the class `container` , you can modify or add styles to the div by adding the property `container` inside the object `styles`. ```javascript const params ={ ... "styles":{ "container":{ "backgroundColor":"blue" } } } ``` Inside the `container` object you can modify any other attribute. #### Spinner In order to modify the style of the spinner loader that is shown when the form page is loading, you need to add the property `spinner` inside the object `styles`. ```javascript const params ={ ... "styles":{ "spinner":{ "borderTopColor":"green" } } } ``` Inside the `spinner` object you can modify any other attribute. #### Buttons The library has two different buttons: "Continue" shown when choosing a payment method and to confirm the transaction and "Go Back", used to go the Payment Methods page again. In order to modify the "Continue" button, you need to add the property `continueBtn` inside the object `styles` and to modify the "Go Back" button use the property `backBtn`. ```javascript const params ={ ... "styles":{ "continueBtn":{ "backgroundColor":"green", ":hover":{ "backgroundColor":"blue" } }, "backBtn":{ "color":"red", "border":"1px solid red" } } } ``` Inside the buttons properties object you can modify any other attribute. #### Grid View The library has different properties you can use to modify the style of the Payment Methods Grid View: * `gridItemBox` allows to customize the container of each payment method * `gridItemCheckIcon` allows to customize how the payment method looks like when it was selected by the customer * `gtidItemLabel` allows to customize the label of each payment method ```javascript const params ={ ... "styles":{ "gridItemBox":{ "width":"170px", "height":"170px", "backgroundColor":"red", ":hover":{ "backgroundColor":"green" } }, "gridItemCheckIcon":{ "color":"green", "borderColor":"blue", "background":"yellow" }, "gridItemLabel":{ "color":"violet" } } } ``` Inside the grids objects you can modify any other attribute. #### Title The library has two titles you can personalize: * `stepsItems` allows to change the style of all the titles * `stepsItemsActive` allows to change the style of the active title ```javascript const params ={ ... "styles":{ "stepsItems":{ "color":"orange", "backgroundColor":"green" }, "stepsItemActive":{ "color":"violet", ":after":{ "content":"''", "display":"block", "height":"3px", "position":"absolute", "left":0, "right":0, "bottom":0, "backgroundColor":"yellow" } } } } ``` #### Inputs In order to modify the input forms, you have the following properties available: * `inputContainer` * `inputText` * `inputErrorLabel` * `inputErrorIcon` ```javascript const params ={ ... "styles":{ "inputErrorIcon":{ "color":"red" } } } ``` #### Selects If you want to modify the selects that will be used to render the form and the select of the payment method you can modify the following properties: * `inputSelect` * `inputSelectOption` ```javascript const params ={ ... "inputSelect":{ "background":"lightBlue", "&:hover":{ "borderColor":"red" } }, "inputSelectOption":{ "background":"red", "&:hover":{ "borderColor":"green" } } } ``` ## 4. Initialize directa24.js As soon as you have all the required parameters, we will invoke the `init` function to create and render the payment page. ```markup ``` The `init` function is composed by the following parameters: ```javascript public init( formId: HTMLElement, displayType: FIELD_TYPE, paymentMethod?: string, loadPaymentForm?: boolean ) ``` ### Parameters description #### formId Name of the HTML element where the library directa24.js has to render the payment page. #### displayType It specifies how the payment methods will be shown. It can either be in `COMBO` format or in `GRID` format. If an invalid value is sent, it defaults to GRID. ```javascript export enum FIELD_TYPE { COMBO = 'combo', GRID = 'grid', } ``` #### paymentMethod The library allows you to specify the Payment Method. That way we won't ask the customer for the Payment Method again. If the payment method is sent and it is invalid or you don't have it enabled, we will show the customer all the payment methods so they can choose one. You can use the [Payment Methods API](/api-documentation/deposits-api/endpoints/payment-methods-endpoint) to determine which payment methods you have enabled. Also check the [Payment Methods](/api-documentation/deposits-api/payment-methods#payment-methods) section for the codes, logos and more. #### loadPaymentForm The `loadPaymentForm` parameter, is an optional and boolean value `[true, false]` that specifies whether the payment method specified can or can't be changed by the customer. If `true`, the user will be redirected straight to the page to complete the payment details. If `false`, the customer will be prompted to select a payment method, with the payment method specified pre-selected by default. It not sent or an invalid value is sent, we will default to `false`. ## 5. Send the payment info to your server Once the user has successfully went through the "payment method" selection page and the "Details" page and clicks on "Confirm", we will send to the url specified as part of the cashier invokation a POST in form-data with the details collected. You will need to use those details to create a deposit request by using our [Deposits API to create the payment link.](/api-documentation/deposits-api) ## Working Code Example Find below a working code example: {% embed url="" %} Directa24 GIT Repository - Example cashier with the Javascript library {% endembed %} As you can see, the directa24.js file is loaded directly from the header of the HTML file, the script tag contains the request to the library, and the payment form is rendered inside the `
` with id 'main'. ```markup Directa24 Payment Form
``` # Deposits with Cards SDK Learn how to create Deposits with our Cards SDK for a seamless checkout experience. In this page you will find the information needed in order to integrate the Deposit Endpoints and the Cards SDK. This integration will enable merchants to: * host natively the credit card checkout; avoid redirections, improve conversion. * merchants do not require a PCI AOC Certificate, while the transaction processing remains fully compliant. * Seamless User Experience. # With User Interface {% hint style="info" %} **Requirements:** * Integrate the OneShot Experience flow within the [Deposit Creation Endpoint](/api-documentation/quickpay/endpoints/deposit-creation-endpoint) for credit and debit cards payment methods. * Install the [Cards SDK](/deposits-tools/cards-sdk). {% endhint %} ### 1. Create a Deposit It must be a deposit for a **credit or debit card payment method** and within the **OneShot Experience**, therefore all the required payer information should be included in the request. Additionally, merchants opting to use our Cards SDK should send the parameter **`token_requested`** with value **`true`**. **Example request** ```javascript { "invoice_id" : "1000000001", "amount": "1000", "country": "MX", "currency": "MXN", "payer": { "id": "11", "document": "CURP4321TEST", "first_name": "Ricardo", "last_name": "Carlos", "email": "juanCarlos@hotmail.com" }, "payment_method": "VI", "client_ip": "123.123.123.123", "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", "token_requested":true } ``` **Example response** ```javascript { "checkout_type": "ONE_SHOT", "redirect_url": "https://pay.depositcheckout.com/validate/4BmNaZNydAokLUzAg2jbCrzqBsyyBTVV", "deposit_id": 981624749, "user_id": "11", "merchant_invoice_id": "1000000001", "payment_info": { "type": "CREDIT_CARD", "payment_method": "VI", "payment_method_name": "Visa", "amount": 1000.0, "currency": "MXN", "expiration_date": "2024-04-11 18:11:11", "created_at": "2024-04-11 18:01:11" }, "checkout_token":"4BmNaZNydAokLUzAg2jbCrzqBsyyBTVV" } ``` The **`checkout_token`** contains the information within the context of the generated deposit. This information will be decrypted and consumed by the SDK in order to adequate the checkout experience. ### 2. Instantiate Cards SDK Now you need to instantiate the **already installed** Cards SDK. [Here](/deposits-tools/cards-sdk) you will find all the technical aspects within instantiation. Remember to retrieve your **publicKey** from the Merchant Panel, and define the proper **environment**. ### 3. Display the Cards SDK component Now you can display the **CreditCardForm**. In order to do so, you need to send in the **`authToken`** parameter, the value obtained in the **`checkout_token`** of the first step alongside the rest of the parameters (`country`, `onTokenGenerationError` and `onBack`). ![](https://docs.d24.com/~gitbook/image?url=https%3A%2F%2F773174111-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-M792I7hN0PzC-Sx95CP-887967055%252Fuploads%252FWxkTMCemIRIlcNe2a8mv%252FScreenshot%25202024-04-12%2520at%252011.35.19%25E2%2580%25AFAM.png%3Falt%3Dmedia%26token%3D84552e87-74b7-4d9e-8eae-0c53c603e1cb\&width=768\&dpr=4\&quality=100\&sign=2f7dd1d97390499c0ca6d58428a47b4136ec52898cb364a1a20cdc83b70c7a74) The component will take care of the deposit creation by collecting the payer's credit card, and then processing the transaction with the acquirer. ### 4. Retrieve the Deposit final status Everytime that the deposit changes it's status, you will receive a webhook notification with the `deposit_id` for you to retrieve the Status. Once the user clicks in the Complete button, we will process the transaction and you will receive such webhook. # Without User Interface This article aims to explain which are the steps for Creating a Deposit with Card Token, the tools and Endpoints involved and how each one of them should be used. {% hint style="info" %} **Requirements:** * Integrate the [PCI Deposit Creation Endpoint](/api-documentation/deposits-api/endpoints/pci-deposit-creation-endpoint). * Install the [Cards SDK](/deposits-tools/cards-sdk). * Create your own frontend components for retrieving the card details. {% endhint %}

Illustration of how a checkout can natively be displayed, with the tools and endpoints involved.

### 1. Generation of the card token Putting it simple; our Cards SDK Without User Interface receives card details as input, and returns a `card_token` as an output. Please make sure of: * saving that `card_token` for further usage in the following step. * **not** storing any card details on your backend. **This is key for remaining the deposit creation PCI Compliant. Just let the SDK handle the card details in the frontend.** {% hint style="success" %} The `token` created can be used within **10 minutes**. After that, it is no longer valid. {% endhint %} ### 2. Create the transaction In order to create the transaction you should send the `card_token` generated with all the transaction details. Make sure of sending the generated token, as `card_token`. #### Example request ```javascript { "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" } }, "card_token":"C4RD_T0K3N_G3N3R4T3D_W1TH_TH3_SDK", "description": "Test transaction", "client_ip": "123.123.123.123", "device_id": "knakvuejffkiebyab", "fee_on_payer": false } ``` # Countries Specifications Learn how to validate the country's specific details ## Countries and currencies * The country codes are in **ISO 3166-1 alpha-2** format. * The currencies are in **ISO 4217** format. | Country | Country code (ISO 3166-1 alpha-2 code) | Currency code (ISO 4217) | | ------------------ | :----------------------------------------: | :---------------------------: | | Argentina | AR | USD / ARS | | Brazil | BR | USD / BRL | | Bolivia | BO | USD / BOB | | Cameroon | CM | USD / XAF | | Canada | CA | USD / CAD | | Chile | CL | USD / CLP | | Colombia | CO | USD / COP | | Costa Rica | CR | USD / CRC | | Côte d'Ivoire | CI | USD / XOF | | Dominican Republic | DO | USD / DOP | | Ecuador | EC | USD | | El Salvador | SV | USD / SVC | | Ghana | GH | USD / GHS | | Guatemala | GT | USD / GTQ | | India | IN | USD / INR | | Indonesia | ID | USD / IDR | | Japan | JP | USD / JPY | | Kenya | KE | USD / KES | | Malaysia | MY | USD / MYR | | Mexico | MX | USD / MXN | | Nicaragua | NI | USD / NIO | | Nigeria | NG | USD / NGN | | Panama | PA | USD | | Peru | PE | USD / PEN | | Paraguay | PY | USD / PYG | | Philippines | PH | USD / PHP | | Singapore | SG | USD / SGD | | South Africa | ZA | USD / ZAR | | Tanzania | TZ | USD / TZS | | Thailand | TH | USD / THB | | Uganda | UG | USD / UGX | | Uruguay | UY | USD / UYU | | Venezuela | VE | USD / VES | | Vietnam | VN | USD / VND | ## Documents validations The `document` sent must follow the validations for its respective `document_type` described below. | Country | Document type | Validation | | ------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- | | Argentina | DNI | Numeric. Length 7-9 | | Argentina | CUIT / CUIL | Numeric. Length between 7 and 9 inclusive or equal to 11 | | Brazil | CPF | Numeric. Length 11 (Validate verifier-digits) | | Bolivia | CI | Numeric. Length: 7 | | Bolivia | CIE | Alphanumeric. One character followed by 8 digits | | Bolivia | PASS | Alphanumeric. One character followed by 6 digits | | Bolivia | NIT | Numeric. Length:12 | | Cameroon | PASS | Numeric. Length between 9 and 11 inclusive | | Cameroon | CI | Numeric. Length between 8 and 12 inclusive | | Cameroon | DL (Driving License) | Numeric. Length between 8 and 10 inclusive | | Canada | DL (Driving License) | Numeric and length between 6 and 9 inclusive or string between 10 and 15 inclusive | | Canada | HC (Health Card) | Numeric. Length 10 | | Canada | PASS (Passport) | Length between 8 and 12 inclusive | | Chile | ID / RUN / RUT | Length 8 or 9 | | Colombia | CC | Numeric. Length between 6 and 10 inclusive | | Colombia | NIT | Numeric. Length between 8 and 15 | | Colombia | CE | Numeric. Length between 6 and 10 inclusive. | | Colombia | PASS | Length between 6 and 10 inclusive | | Colombia | PPT | Length: 7 | | Costa Rica | CI | Length: 9 | | Côte d'Ivoire | ID | Length between 8 and 12 inclusive | | Dominican Republic | CIE | Numeric. Length 11 | | Ecuador | CC | Numeric. Length between 9 and 10 inclusive | | Ecuador | RUC | Numeric. Length between 12 and 13 inclusive and ends with 001 | | Ecuador | PASS | Length between 8 and 13 inclusive and ends with 001 | | El Salvador | DUI | Length between 6 and 18 inclusive | | Ghana | ID | Length between 8 and 12 inclusive | | Guatemala | DPI | Length between 6 and 18 inclusive | | India | ID (PAN) | Length between 8 and 12 inclusive | | India | DL (Driver's License) | Length between 15 and 16 inclusive | | India | UID (Aadhar Card) | Numeric. Length 12 | | Indonesia | NIK / KTP | Numeric. Length between 14 and 18 inclusive | | Japan | DL / ID / PASS / RD (Resident Registration Card) | Length between 9 and 12 inclusive | | Kenya | ID | Length between 7 and 12 inclusive | | Malaysia | ID | Numeric. Length between 10 and 14 inclusive | | Mexico | CURP / RFC / IFE / PASS | Length between 8 and 18 inclusive | | Nicaragua | CI | Length between 8 and 18 inclusive | | Nigeria | ID | Length between 9 and 12 inclusive | | Panama | CIP | Numeric. Length between 5 and 10 inclusive | | Panama | PASS | Length between 8 and 11 inclusive | | Paraguay | CIC (Cédula de Identidad Civil) | Length between 6 and 8 inclusive | | Peru | CE/CPP | Numeric. Length 9 | | Peru | DNI | Numeric. Length 8-9 | | Peru | PASS | Numeric. Length 12 | | Peru | RUC | Length 11 | | Philippines | PSN | Numeric. Length between 9 and 13 inclusive | | Singapore | NRIC | Length 9 | | Singapore | PASS | Length 9 | | South Africa | ID | Numeric. Length between 9 and 14 inclusive | | Tanzania | ID | Length between 8 and 20 inclusive | | Thailand | ID | Numeric. Length between 10 and 14 inclusive | | Uganda | RIC / NID | Numeric. Length between 11 and 15 inclusive | | Uruguay | CI | Numeric. Length between 6 and 8 inclusive | | Venezuela | CI | Numeric. Length between 3 and 20 inclusive | | Venezuela | RIF | Numeric. Length between 3 and 20 inclusive | | Vietnam | ID | Numeric. Length between 9 and 13 inclusive | ## Postal code validations The validation for the postal codes dependes up on the country sent. Make sure you validate them with the regex in the table below to avoid errors due to Invalid postal Code. | Country | Regex | Example | | ------------------ | -------------------------------------- | :-------: | | Argentina | `^\d{4}\|[A-Za-z]\d{4}([a-zA-Z]{3})?$` | A1234ABC | | Brazil | `^\d{5}[\s-/]?\d{3}$` | 12345-678 | | Cameroon | N/A | N/A | | Canada | `^[a-zA-Z]\d[a-zA-Z]\s?\d[a-zA-Z]\d$` | A1A 2B2 | | Chile | `^\d{3}[\s-/]?\d{4}$` | 123-4567 | | Colombia | `^\d{5,6}$` | 12345 | | Côte d'Ivoire | N/A | N/A | | Dominican Republic | `^\d{5}$` | 12345 | | Ecuador | `^\d{6}$` | 123456 | | El Salvador | N/A | N/A | | Ghana | `^[A-Za-z]{2}\d{3,5}$` | AB1234 | | Guatemala | N/A | N/A | | India | `^\d{3}[\s-/]?\d{3}$` | 123-456 | | Japan | N/A | N/A | | Indonesia | `^\d{5}$` | 12345 | | Kenya | `^\d{5}$` | 12345 | | Malaysia | `^\d{5}$` | 12345 | | Mexico | `^\d{5}$` | 12345 | | Nicaragua | N/A | N/A | | Nigeria | `^\d{6}$` | 123456 | | Panama | `^\d{4,6}$` | 12345 | | Paraguay | `^\d{4}$` | 1234 | | Peru | `^\d{5}$` | 12345 | | Philippines | `^\d{3,4}$` | 1234 | | Singapore | N/A | N/A | | South Africa | `^\d{4}$` | 2345 | | Tanzania | `^\d{5}$` | 12345 | | Thailand | `^\d{5}$` | 12345 | | Uganda | N/A | N/A | | Uruguay | `^\d{5}$` | 12345 | | Venezuela | N/A | N/A | | Vietnam | `^\d{5}$` | 12345 | ## Phone numbers validations We use the Google's common library for parsing, formatting, and validating international phone numbers. Validating the phone numbers on your end could help preventing `Invalid phone number` errors. {% embed url="" %} ## Emails validations We suggest you using the following regex to validate email addresses on your end and prevent `invalid email` errors. ``` (?i)[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9]) ``` # WooCommerce Here you will find all the information and resources needed in order to install our WooCommerce plugin!
Details **Contributors:** OKP\ **Requires at least:** 7.0 \ **Tested up to:** 7.4.0 \ **Stable tag:** 1.0.0 \ **License:** GPLv3 \ **License URI:**
## Description This plugin adds OKP Payment Gateway to your WooCommerce store, allowing customers to pay with multiple local payment methods: ### **We support:**
💳 Credit and Debit cards
🏦Online bank transfers
💵 Cash methods
### Translations
🇬🇧 English
🇧🇷Portuguese
🇪🇸Español
## Download {% file src="/files/q0fzHtJ2lJyfHgO6Jbjb" %} v 1.0.0 {% endfile %} ## Next steps Click in the cards below to see the details in how to install and configure the plugin.
🧑‍💻Installation/pages/k49LguvBs3jyrpMzKxSI
⚙️Configuration/pages/ZKicRMbGf3zOyA3taAU1
### Changelog * 1.0.0 (2023-03-01): Initial plugin release # Installation ## **Minimum Requirements** * WooCommerce 7.0 or greater ## Manual installation uploading files to the server Extract the zip file and just drop the contents in the wp-content/plugins/ directory of your WordPress installation and then activate the Plugin from Plugins page. ## Manual installation uploading zip file from WordPress Admin 1. Sign in to your **WordPress Admin.**\
2. In the left-hand menu, select: **Plugins** > **Add New**.\ ![](/files/LMFXufm6B4vtrE9Jl6r7) 3. Select **Upload Plugin**.\ ![](/files/loefyPDTotzCL70u7kCF) 4. Select **Choose File**.\ ![](/files/XTuKfNx2BQvJrZVYZaFG) 5. Locate and select the plugin .zip file on your local computer and then select **Open**. 6. Select **Install Now**.\ ![](/files/e7nSlKIzY04tfI69W3wR) 7. *Optional*: Select Activate Plugin if you want the plugin to be active after the installation. If not, you can always activate it later. # Configuration If you have installed the plugin, follow this steps and tips to have it up and running! Brief explanation In OKP we provide two environments to our clients, **Staging** and **Production**. Each one with its own set of credentials. * With your **Staging** credentials you will be able to test the different payment methods and flows with mocked information that simulates real payments, risk free. * With your **Production** credentials, you will be using real-life gateways and payment information, therefore users will be capable to pay! ## Step-by-step 1. In the left-hand menu go to **Woocommerce** > **Settings**.\ ![](/files/lZubVd6GmvAqNnatpkFD) 2. Then go to **Payments** and you will see **onekeypayments Checkout** on the method list. Click it to configure
3. In the plugin configuration you will find four sections: ***Environment selection***, ***Staging credentials***, ***Production credentials*** and ***Configuration.*** * ***Environment selection:*** in this section you will be capable to select which environment you want to use at your checkout.\ :warning:Please use Staging for testing purposes ***only***. * ***Staging credentials***: this are your Staging environment keys, you can fetch them by logging into the [STG Merchant Panel](https://merchants-stg.onekeypayments.com/), and going into **Settings** >**API Access** > **Deposit credentials** \ :information\_source:*Make sure to whitelist the IPs in which your WooCommerce site is hosted. You can do so by adding the IPs in the list that is below the credentials.* * ***Production credentials***: instructions are the same as for *Staging credentials* but in our production environment. * ***Configuration***: finally in this section you get to choose if you want to enable/disable the plugins and the auto-complete functionality. 4. Lastly, make sure to **Save changes** and yo are good to start using OKP's plugin! :rocket:
# Welcome to OneKey Payments We're excited to introduce our **newly redesigned documentation**, built to help you integrate with OneKey Payments more effectively and efficiently.\ Whether you're a onboarding or a long-time merchant, this guide is your central resource for understanding how our platform works. ### How to navigate this Guide We've structured the guide to follow a logical path from initial setup to advanced features. Based on the main sections in the navigation panel, here’s a quick overview of what you'll find: * **Getting started**: This is your essential first stop. It covers the basics of starting your onboarding, authentication, environments, and the fundamental concepts you'll need to start making calls. * **Deposits**: This section covers everything related to receiving payments. You'll find detailed explanations on: * Our payment method Coverage and available Solutions. * Step-by-step guides to Create deposits and understanding the payment Status flow. * Information on Refunding a deposit. * **Cashouts**: Here you'll learn how to send payouts. * This section includes guides on Countries validations. * How to Create cashouts. * And the Status flow for payouts. * **Platforms Booster**: For our partners offering platform based services, this section details the * Onboarding process * and how to Manage Submerchants payments We recommend starting with the Getting started section and then moving on to the product you wish to integrate first. {% hint style="success" %} #### Navigation tips Through out this site you will find a lot of Buttons pointing you to useful resources! {% endhint %} # Getting started ### Explore our products **Payments solutions**
SolutionDescription
DepositsThis is our solution to help you collect payments, with worldwide coverage and local expertise.
Payment methods of all varieties: credit cards, bank transfers, cash vouchers and wallets.
You will find different types of integrations and tools to achieve your perfect integration.
This technical solutions scopes all sort of deposit flows: one-type payments, subscriptions, card-on-file, and more.
CashoutsWith this solution you will have the capability of generating local cashouts in all our coverage.
Payout methods can take shake of bank transfers, cash vouchers and payouts to wallets.
Platforms BoosterThis is the solution for clients that have a platform-alike solution and need to create transaction on behalf of Submerchant accounts, acting as technology partner for them.
{% hint style="info" %} #### Other solutions Besides payments processing we provide high-value API integrations to fulfill technological and business requirements to safely operate and smoothly incorporate our solutions in your day-to-day. * [**Know Your Customer API**](/api-reference/know-your-customer-api/security-aspects): very useful to retrieve information about your client. * [**Reconciliation API**](/api-reference/reconciliation-api/security-aspects): to blend the information accessible from Merchant Panel within your internal systems. * [**Bank Account Validation API**](/api-reference/cashouts-api/validate-bank-accounts): validate if a bank account exists and check the correct format {% endhint %} ### Create a merchant account By filling this Form our Sales team will get in touch with you and guide you through our **onboarding process**. Meanwhile, our team will create your **merchant account** in order to start your integration on a parallel track. ### Access the Merchant Panel Once your merchant account is created, you will have access to the Merchant Panel within the Staging environment: {% hint style="success" %} #### :e-mail: Activation email Once your application is approved, we will send an activation email to your registered address. * From: **`merchants@onekeypayments.com`** * Subject: **Activate your account** Please click the **activation link** inside this email to set your password and log in for the first time. 🗓️ The email is usually sent within **one business day** of your account approval. :question:What if I don't receive the email? 1. Check your spam/junk folder 2. Add `merchants@onekeypayments.com` to your email contacts to ensure delivery. 3. Get in touch: if you still haven't received it after 48 hours, please reach out to our commercial team. ❗️ **Important security note**: For your protection, only trust emails sent from the `merchants@onekeypayments.com` address. \ We will never ask for your password or financial details via email. {% endhint %} Follow this guide to learn our integration concepts and quickstart your integration. *** ## Next steps
Get your API Keys/files/9vCfyzsigHFqHD4zgT70/pages/d4l0zreZpwI6Zi6Fy698
Important configurations/files/ApKuyWm6NlTjG4fnKm8b/pages/P7oMGpV6Xi7D036wjQAl
Start testing/files/orD3s37YZ5rloDg2pX47/pages/aYIMOMJGpu8QwQgRXfcF
Go Live/files/2n4jABztEPI3y4yAvGXD/pages/dqCJX57Mjf33jNTMvGGq
--- [Next Page](/llms-full.txt/1)