Skip to main content

Payout Notification

This guide shows you how to work with payout notifications. The payouts are processed in batch. Each step in the payout processing flow can dispatch notifications to the merchart. We'll guide you through the steps to handle this type of calls.

Instructions​

Follow the steps below:

  1. Verify the notification signature

    When a payout status is changed to pending (PE), paid(PA) or canceled (CA), EBANX sends a notification to your system through the Notification URL that you should set in your Dashboard. For more details on setting your notification URL, you can refer to the Settings Tab on your EBANX Dashboard.

    EBANX signs every notification request using a private certificate and send the signature in the HTTP headers. The merchant can verify if the request really came from EBANX by validating the digital signature using our public certificate.

    The available certificates and their fingerprints are shown on the table below:

    FingerprintCertificate
    4ABAD89CF66B99998465470550EB15E3E271A246Download

    EBANX will send the following headers in the notification request:

    X­-Signature­Type: rsa,sha1
    X­-Signature­Fingerprint: 4ABAD89CF66B99998465470550EB15E3E271A246
    X-­Signature­Content: xh5hstzZt5Rf5ihNzbfFfkmN89askd...DrHJAnzHgaf2vzA==
    ParameterDescription
    X­-Signature­TypeThe signing algorithm. EBANX will always use RSA/SHA1.
    X­-Signature­FingerprintThe signature fingerprint. It indicates which certificate was used to sign the notification.
    X­-­Signature­ContentThe signed payload, encoded as a Base64 string.

    The signature can be validated in PHP as follows:

    $cert = file_get_contents('ebanx-notifications-public.pem');
    $data = file_get_contents("php://input");
    $signature = base64_decode($_SERVER['HTTP_X_SIGNATURE_CONTENT']);

    // http://php.net/manual/en/function.openssl-verify.php
    $result = openssl_verify($data, $signature, $cert);

    if ($result === 1)
    {
        echo "OK, signature is correct.";
    }
    else
    {
        echo "ERROR, the signature is incorrect.";
    }

  2. Get the payout hash codes from the notification

    The notification will contain the following parameters:

    ParameterDescription
    operationThe value returned give the updated operation in payout.
    notification_typeEvent that triggered the notification. Always returns update.
    hash_codeThe uid hash identifing the payout.

    And operation can have the following values:

    • payout_status_open: The payout status has been created;
    • payout_status_committed: The payout status has changed from OP(Open) to CM(Committed);
    • payout_status_processing: The payout status has changed from CM(Committed) to PE(Pending);
    • payout_status_awaiting_documents: The payout status has changed from PE(Pending) to AD(Awaiting Documents);
    • payout_status_awaiting_payment: The payout status has changed from PE(Pending), or AD(Awaiting Documents), to AW(Awaiting Payment);
    • payout_status_paid: The payout status has changed from AD(Awaiting Documents), or AW(Awaiting Payment) to PA(Paid);
    • payout_status_canceled: The payout status has changed from OP(Open), or CM(Committed), or PE(Pending), or AD(Awaiting Documents), or AW(Awaiting Payment) to CA(Cancelled);
    • payout_status_reverted: The payout status hs changed from PA(Paid) to RE(Reverted);

    Here's a sample of a notification:

    operation=payout_status_paid&notification_type=update&hash_codes=075191f535a332a29bef85b3b94a09d54b621b94

  3. Consult a payout using the /ws/payout/retrieve end-point

    To consult a payout, you can follow the documentation in Consult a Payout page.

  4. Let EBANX know you received our response

    Reply the notification with an HTTP 200 status. We suggest to print any message showing that you got the notification, indicating that the notification was successful.

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: