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

200 Cashout request successfully created.

{
    "cashout_id": "8405147"
}

401 The credentials specified are incorrect.

{
    "code": 401,
    "message": "Invalid credentials."
}

412 Error in the data validation.

{
    "code": 303,
    "message": "Invalid bank code"
}

{
    "code": 300,
    "message": "bank_account: must not be null; Invalid Bank account"
}

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
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
document_id	string (max length: 40)	Beneficiary’s personal identification number	See document validations
document_type	string (maxLength: 15)	Beneficiary’s personal identification number type	See document types validations
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
phone	string (maxLength: 20)	Beneficiary's phone number	See phone number validations
bank_code	Integer (max length: 8)	Beneficiary's bank code or ISPB – Identificador do Sistema de Pagamentos Brasileiro	See bank codes API
bank_account	string (max length: 30)	Beneficiary's bank account number	See bank_account validations
bank_branch	string (max length: 15)	Beneficiary's bank branch number	See bank_branch validations
account_type	string (max length: 1)	Type of account	See bank_account types
registered_bank_accounts	object	Optional field to send registred accounts	See registred bank accounts example
registered_bank_accounts.account_number	string (max length: 30)	Beneficiary's registred account number	See bank_account validations
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
registered_bank_accounts.bank_branch	Integer (max length: 8)	Beneficiary's bank branch from the registred account	See bank codes API
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
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 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 [e-mail] 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 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 if it is a valid card number and/or with a regex for each brand, like the example below.

public static final String SENSIBLE_DATA_PATTERN = new StringBuilder("(?:(?<visa>4[0-9]{12}(?:[0-9]{3})?)")
      .append("|(?<mastercard>5[1-5][0-9]{14})")
      .append("|(?<discover>6(?:011|5[0-9]{2})[0-9]{12})")
      .append("|(?<amex>3[47][0-9]{13})")
      .append("|(?<diners>3(?:0[0-5]|[68][0-9])?[0-9]{11})")
      .append("|(?<jcb>(?: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.

Sending a debit card number through the non-cc endpoint will make the request to fail with the following error:

{
    "code": 300,
    "message": "bank_account: Invalid bank account, it shouldn't be a credit card"
}

Invalid bank_account error on the cc-api endpoint:

{
    "code": 300,
    "message": "bankAccount: invalid credit card number"
}