Pre-authorized Purchases: Capture and Cancel

Optimize your payment workflows by using capture and void operations for pre-authorized credit and debit card transactions. The capture function allows you to finalize purchases with adjustable amounts, while the void function lets you cancel unnecessary authorizations.

Looking for previous API versions?

If you’re searching for documentation on earlier API versions (V2), please refer to our Legacy Systems section

Capture a purchase

This method allows you to confirm a pre-authorized purchase. The capture process allows you to confirm and finalize a pre-authorized transaction, giving you the flexibility to adjust the amount if needed.

Authorization per Country

All payment methods may not support the authorization feature, 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/v3/api/purchase/{{TransactionId}}/capture
Stage: https://api.stage.bamboopayment.com/v3/api/purchase/{{TransactionId}}/capture

Remember to include your merchant’s Private Key in the request headers.
For more details, check our Authentication Guide.

Request parameters

The request body is optional to confirm a purchase. If you don’t send any request, the method commits the pre-authorized purchase by its original amount.

The purchase amount may vary concerning the one sent in the initial purchase process, but the new amount cannot be higher than the original amount.

Request example (Partial Capture)

You must include the new amount in the request to confirm a purchase with a lower amount than the original. For example:

{
  "Amount": 50
}

Response example (Partial Capture)

You will get the same Response object for the purchase object.

Result:COMPLETED - Status: PREAUTHORIZED

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "PREAUTHORIZED",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": "2024-08-07T17:51:56.879",
    "AuthorizationCode": "839936",
    "Amount": 5000,
    "Currency": "BRL",
    "Installments": 2,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/79632697147789184",
    "MetadataOut": null,
    "Action": null,
    "PaymentMethod": {
        "Brand": "Visa",
        "CardOwner": "João Silva",
        "Bin": "450799",
        "IssuerBank": "Banco do Brasil",
        "Type": "CreditCard",
        "Expiration": "203008",
        "Last4": "4905"
    }

Cancelling a purchase

A void (or cancel) is the act of canceling a pre-authorized transaction 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.

The cancel operation is only available for purchases previously authorized with state PreAuthorized. If you’re interested in refunding a purchase that has already been captured, please refer to the refunds section for detailed instructions.

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/v3/api/purchase/{{TransactionId}}/cancel
Stage: https://api.stage.bamboopayment.com/v3/api/purchase/{{TransactionId}}/cancel

Remember to include your merchant’s Private Key in the request headers.
For more details, check our Authentication Guide.

Request parameters

Request body is not required to cancel 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.

Note

The availability of partial cancellation functionality may vary depending on the country. For detailed information about this feature in your specific region, please consult with your Account Manager.

Request example (Partial Cancellation)

To perform the cancel of the 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 cancel, you will get the same Response object for the purchase object.

Result:COMPLETED - Status: CANCELLED

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "CANCELLED",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": "2024-08-07T17:51:56.879",
    "AuthorizationCode": "839936",
    "Amount": 5000,
    "Currency": "BRL",
    "Installments": 2,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/79632697147789184",
    "MetadataOut": null,
    "Action": null,
    "PaymentMethod": {
        "Brand": "Visa",
        "CardOwner": "João Silva",
        "Bin": "450799",
        "IssuerBank": "Banco do Brasil",
        "Type": "CreditCard",
        "Expiration": "203008",
        "Last4": "4905"
    }
}

Last modified December 20, 2024