In some situations, merchants may need to cancel a payment that has been initiated but not yet completed. The EBANX API provides a straightforward method for canceling payments, ensuring flexibility and control over transaction management. This feature allows you to manage payment status effectively. Below, you’ll find the details required to integrate and utilize the cancel payment functionality.
Features
- Time limits
- Payments can only be canceled if their status is pending or open.
- Payments with a status of confirmed can only be refunded, not canceled.
- Partial cancellations
- EBANX does not support partial cancellations.
- If a partial refund is required, use the Refund API instead.
- Error handling - If the payment is already processed or confirmed, you will receive an error message, as cancellation is no longer possible.
Requirements
To cancel a payment, ensure the following conditions are met:
- You have access to your EBANX API credentials (your integration_key).
- You have the payment_hash of the transaction you want to cancel.
- Status must be pending (PE) or open (OP). The status must not be confirmed (CO).
- To confirm the payment status, refer to the instructions below.
Instructions
To cancel a payment, follow the steps below.
Verify payment status
To confirm payment status, please refer to the Retrieve Payment guide before initiating a cancellation request.
Status must be pending (PE) or open (OP).
Cancel 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.
https://sandbox.ebanx.com/ws/cancelProvide the following parameters.
Parameter Type Description integration_keystringYour EBANX API key. payment_hashstringThe unique identifier of the payment provided by EBANX. Sample request
Use the following example to initiate a cancel request.
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/cancel' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9"
}'Sample response
A successful request will return a response similar to the one below.
{
"payment": {
"country": "br", // country of transaction
"hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9", // Payment identifier
"merchant_payment_code": "1461416920319", // Merchant reference
"order_number": "146",
"status": "CA", // (CA = Canceled)
"status_date": "2014-11-26 17:34:11", // Status update timestamp
"open_date": "2014-11-25 10:45:56", // Payment initiation time
"confirm_date": null, // Confirmation time (null if not confirmed)
"transfer_date": null, // Transfer time (null if not processed)
"amount_br": "204.45", // Amount in BRL
"amount_ext": "87.00", // Amount in foreign currency
"amount_iof": "0.00", // IOF tax
"currency_rate": "2.3500", // Exchange rate
"currency_ext": "USD", // External currency (USD)
"due_date": "2014-12-2", // Due date
"instalments": "1", // Number of installments
"payment_type_code": "boleto",
"details": {
"billing_descriptor": "DEMONSTRATION" // Billing Descriptor
},
"transaction_status": { // Operation status
"acquirer": "EBANX",
"code": "OK",
"description": "Accepted",
"authcode": "12345",
"description_code": "ACQUIRER_ACCEPTED"
},
"pre_approved": false,
"capture_available": false,
"customer": { // Customer Information
"document": "12345678901",
"email": "customer.test@ebanx.com",
"name": "Customer Test",
"birth_date": "2000-01-01"
},
"single_transaction": {
"amount_local": "0.00",
"amount_crossborder": "1.00"
},
"card_unique_id": "123456C",
"threedsecure": {
"has_threeds": false
}
},
"operation": "cancel", // Operation performed (cancel)
"status": "SUCCESS" // Operation status (SUCCESS = successful)
}Failure response - Payment is already cancelled
{
"status": "ERROR",
"status_code": "BP-CAN-3",
"status_message": "Payment is already cancelled"
}Failure response - Payment not found
{
"status": "ERROR",
"status_code": "BP-CAP-2",
"status_message": "Payment not found for merchant, hash: 5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9, merchant_payment_code: "
}Congratulations!
You have succesfully cancelled a payment.
For more information, refer to the API reference for cancelling a payment.
Cancel payment with EBANX dashboard
Canceling an open payment can be easily done through the EBANX Dashboard.
Follow these steps:
- Log in to the EBANX Dashboard.
- Go to Transactions > Payments.
- Locate the open payment you want to cancel and click on it.
- On the payment details page, click the Actions for this payment dropdown.
- Select Cancel Payment from the dropdown options.
- Confirm the cancellation in the popup window.
Resources
Use the following resources when testing in your sandbox environment.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
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.