Version: current

Payments Notification

About this guide

This guide shows you how to work with payment notifications. Due to the nature of some payment methods, payments will not always be confirmed instantly which is the case of all cash payments for an example. We'll guide you through the steps to handle this type of calls.

How it works

  1. Verify the notification signature

    When a payment status is changed to confirmed (CO) or cancelled (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 payment hash codes from the notification

    The notification will contain the following parameters:

    ParameterDescription
    operationThe value is always payment_status_change.
    notification_typeEvent that triggered the notification
    hash_codesA single hash or an array of hashes separated by commas.

    And notification_type can have the following values:

    • update: The payment status has changed from PE(Pending) to CO(Confirmed) or CA(Cancelled);
    • chargeback: A chargeback was issued for this payment;
    • refund: A refund was issued for this payment;
    • chargeback_credit: A chargeback credit was issued for this payment;

    Here's a sample of a notification:

    operation=payment_status_change&notification_type=update&hash_codes=53ad936c0dfb7b008d57bf7d396c83a28d24869949fdc84f
  3. Query the payments using the /ws/query end-point and the hash codes received in the notification

    To query a payment, you just need to call the end-point /ws/query (from your server) with the following required fields:

    FieldDescription
    integration_keyYour unique and secret integration key
    hashThe payment hash (EBANX unique identifier)

    Here's an example of a payment query:

    curl -X GET 'https://sandbox.ebanxpay.com/ws/query?integration_key=1231000&hash=5a15e30b970d9f9f4bc33466e42e92515c7a7ed755dc1e45'

    The EBANX server will send a JSON object as a response, including the payment status. Here’s an example:

    {
    "payment": {
    "hash": "5a15e30b970d9f9f4bc33466e42e92515c7a7ed755dc1e45",
    "pin": "020593132",
    "merchant_payment_code": "1120a8eb178",
    "order_number": null,
    "status": "CO",
    "status_date": "2017-11-22 20:50:18",
    "open_date": "2017-11-22 20:50:18",
    "confirm_date": "2017-11-22 20:50:18",
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2017-11-25",
    "instalments": "3",
    "payment_type_code": "visa",
    "details": {
    "billing_descriptor": ""
    },
    "transaction_status": {
    "acquirer": "EBANX",
    "code": "OK",
    "description": "Sandbox - Test credit card, transaction captured",
    "authcode": "45101"
    },
    "pre_approved": true,
    "capture_available": false
    },
    "status": "SUCCESS"
    }
  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.

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you‚Äôre not our partner yet and would like to know more about our prices and conditions please fill ou this form and our comercial team will get in touch with you.
  • In case you‚Äôre already our partner please get in touch with our support team at integration@ebanx.com.
Last updated on by Fernando Pankiewicz Gomes