This page's content:

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.

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.

Your system receives the notification then call our API Query Operation. By doing this, you will know the status and more information about that payment.

After you get the notification, you must output a response(we suggest to print any message showing that you got the notification) indicating that the notification was successful.

Notifications are important since they will indicate when you can deliver your product/service to your customer.

The following figure shows how the flow works:

As mentioned, you need to register the notification URL of your server in the Dashboard. It could be something like this: https://www.yourstore.com/ebanx/status_change. For more details, you can refer to the Settings tab(item 3) from your EBANX Dashboard.

Every time a status changes, the EBANX server will make a POST request to the registered URL and expect a HTTP 200 code as a response. This request will only have one parameter, which includes the hash for the updated payment. operation=payment_status_change&notification_type=update&hash_codes=53ad936c0dfb7b008d57bf7d396c83a28d24869949fdc84f

Parameters

operation string

The value is always payment_status_change.

notification_type string

Event that triggered the notification:

  • 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.
hash_codes string

A single hash or an array of hashes separated by commas.

After receiving the notification, your script should call the EBANX’s Query Operation to fetch all payment information, including the payment status.

https://api.ebanx.com/ws/query?integration_key=YOUR_KEY&hash=1998bff11bf7b3185e8f2af113ee3fb1fa4c9

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

Copy
{
  "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"
}

Notification signature

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:

Fingerprint Certificate
4ABAD89CF66B99998465470550EB15E3E271A246 Download

EBANX will send the following headers in the notification request:

X­-Signature­Type: rsa,sha1

X­-Signature­Fingerprint: 4ABAD89CF66B99998465470550EB15E3E271A246

X-­Signature­Content: xh5hstzZt5Rf5ihNzbfFfkmN89askd...DrHJAnzHgaf2vzA==

X­-Signature­Type

The signing algorithm. EBANX will always use RSA/SHA1.

X­-Signature­Fingerprint

The signature fingerprint. It indicates which certificate was used to sign the notification.

X­-­Signature­Content

The signed payload, encoded as a Base64 string.

The signature can be validated in PHP as follows:

Copy
$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.";
}