Skip to main content
Payment Notification

The Payment Notification feature at EBANX enables real-time updates to merchants about the status of transactions, ensuring smooth and efficient payment processing. By leveraging webhooks, this feature provides instant notifications when a payment is approved, failed, or requires further action. It allows merchants to automate order fulfillment, handle payment statuses accurately, and enhance the overall customer experience by maintaining timely communication throughout the payment process. Some payment methods, such as cash payments, may not provide instant transaction confirmation. As a result, notifications play a vital role in ensuring accurate tracking and timely updates.

Requirements​

  • Dashboard Credentials
  • Notification URL
    • Configure your Notification URL in the EBANX dashboard under Account Settings in the Integrations tab to receive payment status updates.

How it works​

  • Payment status update - EBANX sends a notification to your system when a payment’s status changes to either confirmed (CO) or canceled (CA).
    • The notification serves to inform that a status change has occurred.
    • It does not include full payment details.
  • Notification URL
    • Configure a Notification URL in the EBANX Dashboard to receive real-time status updates.
    • EBANX sends an HTTP POST request to the configured Notification URL. The request includes basic payment and status information, along with headers containing a digital signature to ensure authenticity.
  • Handling the notification - Upon receiving a notification, your system must:
    • Validate the notification’s signature using EBANX’s public certificate (details in the X-Signature-Content header).
    • Query the /ws/query endpoint to retrieve the full details of the payment and confirm the status change.
  • Error handling & retries - If your system fails to process a notification (e.g., due to a server error), EBANX will retry sending it multiple times. Ensure robust error handling to process notifications correctly.

This notification system ensures secure and reliable updates, but the provided notification only signals a status change. Always use /ws/query to fetch detailed information before proceeding with further actions, such as order fulfillment.


Instructions​

  1. Ensure notification URL is configured

    Ensure that your Notification URL is configured in your EBANX dashboard under Account Settings in the Integrations tab to receive payment status updates.

    To configure your notification URL, go to your
    EBANX Dashboardchevron_right

  2. Validate incoming notification

    When a payment's status changes to either confirmed (CO) or cancelled (CA), EBANX sends a notification to your system via the Notification URL.

    • To ensure the authenticity of the notification, EBANX digitally signs each request using a private certificate and includes the signature in the HTTP headers. You can verify the request’s origin by validating the digital signature with EBANX’s public certificate.

    Certificate information

    The EBANX certificate and fingerprint are listed below:

    FingerprintCertificate
    4ABAD89CF66B99998465470550EB15E3E271A246ebanx-notifications-public.pemDownload

    Notification headers

    EBANX includes the following HTTP headers in the notification request:

    // Headers
    X­-Signature­Type: rsa,sha1
    X­-Signature­Fingerprint: 4ABAD89CF66B99998465470550EB15E3E271A246
    X-­Signature­Content: xh5hstzZt5Rf5ihNzbfFfkmN89askd...DrHJAnzHgaf2vzA==
    ParameterDescription
    X­-Signature­TypeThe signing algorithm. (RSA/SHA1)
    X­-Signature­FingerprintIndicates which certificate was used to sign the notification.
    X­-­Signature­ContentThe signed payload, encoded as a Base64 string.

    Validating the signature

    You can validate the digital signature using bash as shown below:

    #!/bin/bash

    # Load the public certificate
    cert="ebanx-notifications-public.pem"

    # Read the input data (assuming it's passed as an argument)
    data="$1"

    # Read the signature from the environment variable (you can set this variable before running the script)
    signature_base64="$HTTP_X_SIGNATURE_CONTENT"

    # Decode the Base64 signature
    signature=$(echo "$signature_base64" | base64 --decode)

    # Validate the signature
    if echo -n "$data" | openssl dgst -sha256 -verify "$cert" -signature <(echo -n "$signature"); then
        echo "OK, signature is correct."
    else
        echo "ERROR, the signature is incorrect."
    fi

  3. Retrieve payment hash codes from notification

    The notification will include the following parameters:

    ParameterDescription
    operationThe value is always payment_status_change
    notification_type
    • update - Changed from Pending (PE), to Confirmed (CO) or Cancelled (CA)
    • 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_codesA single hash, or an array of hashes separated by commas.

    Example notification

    operation=payment_status_change&notification_type=update&hash_codes=53ad936c0dfb7b008d57bf7d396c83a28d24869949fdc84f

  4. Acknowledge EBANX's notification

    When you receive a notification from EBANX at your Notification URL, it's important to respond promptly to confirm that your server has successfully received it.

    • Immediate acknowledgment - Respond to the notification immediately with an HTTP 200 status code.
      • This confirms to EBANX that your server received the notification, preventing unnecessary retries.
    • Retry mechanism - If your server doesn’t respond with HTTP 200 promptly, EBANX will assume the notification was not received and will resend it.
    • Log the notification - Log or store the notification data for further processing and tracking.
    • Avoid delays - Do not delay the acknowledgment while processing the data or querying other endpoints.
      • Respond immediately to avoid triggering EBANX's retry mechanism.
    • Query payment details - (Optional) If needed, use the /ws/query endpoint to confirm or retrieve additional payment information.
    • System update - Update your system based on the verified payment status from the notification or additional query.

  5. Query the payments using the hash codes

    To query a payment, make a request to the /ws/query endpoint with the following required fields:

    FieldDescription
    integration_keyYour EBANX integration key.
    hashThe payment hash, which is EBANX’s unique identifier for the transaction.
    For more information, refer to the
    Payment query API reference guidechevron_right

  6. Example request

    Use the following example as a guide to query a payment.

    curl -X POST \
      --location 'https://sandbox.ebanxpay.com/ws/query' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "operation": "request",
        "hash": "5a15e30b970d9f9f4bc33466e42e92515c7a7ed755dc1e45"
      }'

  7. Example response

    A JSON object will be returned, providing detailed information about the payment, including its current status and other relevant transaction details.

    {
      "payment": {
      "hash": "5a15e30b970d9f9f4bc33466e42e92515c7a7ed755dc1e45",
      "merchant_payment_code": "1120a8eb178",
      "order_number": null,
      "status": "CO",  // Payment is Confirmed (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"
    }

  8. Update your system

    Update your system based on the verified payment status from the notification or query. Log payment status for further processing or tracking.

  9. Congratulations!

    You have succesfully integrated Payment Notifications.

    For more information, refer to the
    Direct API reference guidechevron_right

Still need help?

Help Image

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