Retrieve a Payment

This guide provides detailed instructions on how to use the EBANX API to retrieve information about a payment. This API call is useful for checking the status and details of a specific transaction.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Payment Identifier - hash or merchant_payment_code of the payment you want to retrieve.

Instructions

To retrieve a payment, follow the steps below.

1. Retrieve the payment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/query
   
   

   Provide the following parameters.

   Field	Type	Description
   integration_key	String	Your EBANX integration key.
   hash	String	(Optional) The unique payment identifier provided by EBANX.
   merchant_payment_code	String	(Optional) The unique payment code provided by the merchant.

   • Either hash or merchant_payment_code must be provided to identify the payment.

2. Sample Request

   Use the following examples to initiate a payment query.

   Using Hash.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/query' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9" // Hash
     }'

   Using Merchant Payment Code.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/query' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "merchant_payment_code": "1416854121" // merchant_payment_code
     }'

3. Sample response

   A successful request will return a response similar to the one below.

   {
      "payment": {
          "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9",
          "country": "br",
          "merchant_payment_code": "12345678",
          "order_number": null,
          "status": "CO",
          "status_date": "2024-12-02 14:27:54",
          "open_date": "2024-12-02 14:27:53",
          "confirm_date": "2024-12-02 14:27:54",
          "transfer_date": null,
          "amount_br": "5.74",
          "amount_ext": "1.00",
          "amount_iof": "0.02",
          "amount_ext_requested": "1.00",
          "currency_rate": "5.7400",
          "currency_ext": "USD",
          "due_date": "2024-12-05",
          "instalments": "1",
          "payment_type_code": "visa",
          "details": {
              "billing_descriptor": "DEMONSTRATION"
          },
          "transaction_status": {
              "acquirer": "EBANX",
              "code": "OK",
              "description": "Accepted",
              "authcode": "12345",
              "description_code": "ACQUIRER_ACCEPTED"
          },
          "pre_approved": true,
          "capture_available": false,
          "refunds": [
              {
                  "id": "12345678",
                  "merchant_refund_code": null,
                  "status": "RE",
                  "request_date": "2024-12-02 14:28:30",
                  "pending_date": null,
                  "confirm_date": null,
                  "cancel_date": null,
                  "amount_ext": "1.00",
                  "description": "Order did not arrive",
                  "amount_local": "5.74",
                  "email_quantity": 0,
                  "email_first_date": null,
                  "email_last_date": null,
                  "bank_info_customer_filled": 0,
                  "bank_info_customer_filled_date": null,
                  "single_transaction": {
                      "amount_local": "0.00",
                      "amount_crossborder": "1.00"
                  },
                  "refund_status_details": {
                      "can_be_cancelled": false
                  },
                  "refund_method": "card"
              }
          ],
          "customer": {
              "document": "12345678901",
              "email": "customer.test@ebanx.com",
              "name": "CUSTOMER TEST",
              "birth_date": "2000-01-01",
              "address": "Rua A",
              "street_number": "020",
              "street_complement": "",
              "city": "Curitiba",
              "state": "PR",
              "zipcode": "82000000",
              "country": "br",
              "phone_number": "41999999998"
          },
          "single_transaction": {
              "amount_local": "0.00",
              "amount_crossborder": "1.00"
          },
          "card_unique_id": "123456C",
          "threedsecure": {
              "has_threeds": false
          },
          "creditcard_token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6"
      },
      "status": "SUCCESS"
   }
   
   

   Failure response - using Hash

   {
      "status": "ERROR",
      "status_code": "BP-Q-2",
      "status_message": "Payment not found for merchant, hash: 5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9"
   }
   
   
   

   Failure response - using Merchant Payment Code

   {
      "status": "ERROR",
      "status_code": "BP-Q-2",
      "status_message": "Payment not found for merchant, merchant_payment_code: 123456789"
   }
   

4. Congratulations!

   You have succesfully retrieved a payment.

   For more information, refer to the API reference for retrieving a payment.

Retrieve a payment via EBANX Dashboard

Alternatively, you can retrieve a payment directly through your EBANX Dashboard.

• Log in to your EBANX dashboard and navigate to /transactions/payments.
• In the search field, use payment hash, customer email, or order number to search for a payment.
• Once found, click on the entry for more details.

Guidelines

• Payment Status - Possible statuses include:

  • Pending (PE) - Payment is pending and awaiting completion.
  • Confirmed (CO) - Payment has been completed and confirmed.
  • Cancelled (CA) - Payment was canceled and is no longer active.

• Error Handling - If the payment is not found, the API will return an error status with a message. Make sure to handle errors gracefully in your application.

Still need help?

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

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.