Cashout Request

POST https://api-stg.zimo-pagos.com/v3/cashout

This endpoint allows you to generate cashout requests

Headers

Request Body

{
    "cashout_id": "8405147"
}

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

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

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

{
    
    "code": 504,
    "message": "User unauthorized due to cadastral situation",
    "reason": "Underage user detected",
    "reason_code": 105
}

Request Fields Description

Error response

Error response fields

Error response examples

{
  "code": 300,
  "message": "bankAccount: Invalid or missing Bank account"
}

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

{
  "code": 504,
  "message": "User unauthorized due to cadastral situation."
  "reason": "Underage user detected",
  "reason_code": 105
}

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 integration@zimo-pagos.com with your cashout API Key

STG endpoint for Debit Cards: https://cc-api-stg.zimo-pagos.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"
}

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

STG Testing

In the STG environment you can force a notification to be sent to your notification_url from the STG Merchant Panel 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.

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.

Check the examples below on how to calculate the control string for the notifications:

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)));
}

$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)));

 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();
 

Retry logic

Every time a cashout changes its status, we will send you a notification so you can check its status 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.

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:

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.

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.