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

On STG, the notifications could take up to 5 minutes in being sent.

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.

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.

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

JAVA

public static void main(String[] args) throws IOException, NoSuchAlgorithmException, InvalidKeyException {
      String external_id = "cashoutID1234";
      String message = "Be4" + external_id + "Bo7";
      String apiSignature = "your_cashout_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)));
}

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

C#

 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.

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.

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.

It can take up to 2 minute for the notification to be resent.