Refunds and voids

Refunds and voids are related to the process of reversing a purchase already confirmed or the cancellation of a pre-authorized purchase.

Before we start, let’s review some concepts.

Void: A void is the act of canceling a pre-authorized transaction (rollback) before it is finalized or settled. When a transaction is voided, it is as if the purchase never occurred, and no money is transferred. Voids usually occur before the payment is fully processed, so the customer’s payment method is not charged for the voided transaction.
Refund: A refund, on the other hand, is a transaction that occurs when a customer returns a purchased item or cancels a service, and the merchant reimburses the customer for the amount paid. The refunded amount is usually returned to the original payment method used by the customer. Unlike voids, the refund occurs after the transaction has been settled.

Setting the language of the response codes

You can receive the error description by relying on localization features. To do this, you need to send the lang header in your integration, using any of the following languages in ISO 639-1 format.

Code	Language
`en`	English. This is the default language. If you don’t send this header or set a non-existent language, you will receive errors in this language.
`es`	Spanish.
`pt`	Portuguese.

Rollback a purchase

The rollback operation is only available for purchases previously authorized with state PreAuthorized.

Note

Pre-authorization feature may not be supported by all payment methods and it’s available for the following countries.

Request URL

You must invoke a POST request to the following URLs according to your needs.

Production: https://api.bamboopayment.com/v1/api/purchase/{{PurchaseID}}/rollback
Stage: https://api.stage.bamboopayment.com/v1/api/purchase/{{PurchaseID}}/rollback

Request parameters

Request body is not required to rollback a purchase. If you don’t send any request the purchase will be voided with its original amount.

The amount to be void may vary with respect to the one that was sent in the initial Purchase process, but the new amount cannot be higher than the original amount.

Request example

To perform the rollback of a purchase with a lower amount than the original, you need to include the new amount in the request. For example:

{
  "Amount": 50
}

Response parameters

When you perform the rollback, you will get the same Response object returned.

Refund a purchase

The refund operation is only available for purchases with state Approved. Refunds can be total or partial.

Request URL

You must invoke a POST request to the following URLs according to your needs.

Production: https://api.bamboopayment.com/v2/api/purchase/{{PurchaseId}}/refund
Stage: https://api.stage.bamboopayment.com/v2/api/purchase/{{PurchaseId}}/refund

Request parameters

Consider the following parameters when invoking a refund request.

Parameter	Type	Mandatory	Description
`Amount`	`number`	No	Amount to be refunded (Partial refund). If this parameter is not send, the refund will be for the amount of the purchase (Total refund). If you require to include decimals in the amount, concatenate the decimal places without de decimal point. Example: `12,25` > `1225`. This value cannot be higher than the original amount of the purchase.
`MetadataIn` → `Description`	`string`	No	Optional description for the refund.

Request example

{
  "Amount":"2500",
  "MetadataIn": {
    "Description": "Refund description"
  }
}

Response parameters

Parameter	Type	Description
`Response` → `PurchaseRefundId`	`number`	Internal identifier of the refund.
`Response` → `Created`	`date`	Date and time when the refund was created. Date format ISO-8601.
`Response` → `Amount`	`number`	Refund amount as sent in the request.
`Response` → `Currency`	`string`	Currency of the refund, according to ISO-4217 (alphanumeric codes).
`Response` → `StatusId`	`number`	Identifier of the refund status.
`Response` → `Status`	`string`	Description of the refund status.
`Response` → `AuthorizationCode`	`string`	Refund code returned by the acquirer of the transaction.
`Response` → `Code`	`string`	Error code returned by the acquirer of the transaction.
`Response` → `Description`	`string`	Description returned by the acquirer of the transaction.
`Response` → `MetadataOut`	`object`	Additional information returned by the acquirer.
`Errors` → `ErrorCode`	`string`	Error code returned by Bamboo.
`Errors` → `Created`	`string`	Date and time when the error was generated.
`Errors` → `Message`	`string`	Descriptive text of the error.
`Errors` → `Detail`	`string`	Error detail.

Response example

{
    "Response": {
        "PurchaseRefundId": 1246459,
        "Created": "2023-09-22T13:46:47.089",
        "Amount": 100.00,
        "Currency": "CLP",
        "StatusId": 10,
        "Status": "Refund_OK",
        "AuthorizationCode": null,
        "Code": "0",
        "Description": "REVERSED",
        "MetadataOut": null
    },
    "Errors": []
}

Last modified November 18, 2024