Refunds

Refunds revert all or part of an approved purchase, generating a new transaction logically linked to the original one. Refunds are used for returns, cancellations, or billing adjustments once the purchase has been successfully completed.

This page describes the functional behavior, constraints, and typical flows for refunds in the Purchase API. For the full endpoint definition, request/response schema, and testable examples, refer to the Refunds section in the API Reference.

Refund Availability

Refunds are only permitted for purchases with final status Approved.
The following refund types may be available, depending on the payment method and acquirer:

Full Refund

Reverts the entire amount of the original purchase in a single operation.

Partial Refund

Reverts only part of the original amount.
The refunded amount cannot exceed the remaining refundable balance.

Multiple Refunds

Allows several partial refunds, provided that the cumulative amount does not exceed the original purchase value.

📘
Additional limitations or processing times may apply depending on the country and payment method. Refer to the specific payment method documentation for detailed rules.

Endpoint

Send a POST request to the refund endpoint associated with the purchase being reverted:

Production
https://api.bamboopayment.com/v3/api/purchase/{{TransactionId}}/refund

Staging
https://api.stage.bamboopayment.com/v3/api/purchase/{{TransactionId}}/refund

For full endpoint details, refer to the **Refunds** section in the API Reference.

Request Parameters

The refund request accepts the following fields:

Parameter	Type	Required	Description
`Amount`	`integer` (64 bits)	No	Amount to be refunded. If omitted, the API processes a full refund. When decimals are required, concatenate them without a separator (e.g., `12,25` → `1225`). The value cannot exceed the remaining refundable balance.
`MetadataIn`	`object`	No	Container for optional metadata associated with the refund.
`MetadataIn.Description`	`string`	No	Optional description or internal reference for the refund operation.

Request example

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

Response parameters

Parameter	Type	Description
`TransactionId`	`string`	Unique identifier for the refund transaction.
`Result`	`string`	The result of the refund operation (e.g., `COMPLETED`).
`Status`	`string`	The status of the refund (e.g., `APPROVED`, `PENDING`).
`ErrorCode`	`string`	Error code if the refund failed (null if successful).
`ErrorDescription`	`string`	Description of the error if the refund failed (null if successful).
`Created`	`string`	Timestamp of when the refund was initiated.
`AuthorizationDate`	`string`	Timestamp of when the refund was authorized.
`AuthorizationCode`	`string`	Authorization code for the refund transaction.
`Amount`	`integer`	The amount that was refunded.
`Currency`	`string`	The currency of the refund.
`MetadataOut`	`object`	Additional metadata returned with the refund response.

Response example

Result:COMPLETED - Status: APPROVED

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "APPROVED",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-09-02T15:58:13.078",
    "AuthorizationDate": "2024-09-02T15:58:18.334",
    "AuthorizationCode": "673531",
    "Amount": 25000,
    "Currency": "BRL",
    "MetadataOut": null
}

📘
Pending Status: A refund may remain in a pending status depending on the payment method and acquirer. This means that while the refund request has been initiated, it may not be processed immediately.

Result:COMPLETED - Status: PENDING

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "PENDING",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-09-02T15:58:13.078",
    "AuthorizationDate": null,
    "AuthorizationCode": null,
    "Amount": 25000,
    "Currency": "BRL",
    "MetadataOut": null
}

Final Result Notification

The final status of a refund is delivered through the webhook notification mechanism.
This ensures that the definitive result is communicated even when the initial response returns a PENDING status.

Refer to the Webhook Notifications section for the full structure and event definitions.

Discover the API

Refunds for Alternative Payment Methods

Review how refunds are processed for payment methods where Bamboo handles the reversal.

Error Codes

Review processor and validation errors that may affect refund operations.

Refunds API Reference

Access the complete endpoint definition, schema, and testable examples.