Overview

When a buyer performs a purchase, the final amount may be modified for several reasons:

• Currency conversion (e.g. USD to the local currency of the destination country).
• Commissions to be paid by the customer.
• Taxes (for example, in Argentina several taxes affect the final amount).

As a consequence, the merchant cannot show the real amount that will be charged until the purchase is processed. Purchase Preview solves this: it returns the calculated amounts, taxes, charges, and exchange rate for a given payment without creating a transaction, so you can show the customer the real amount before they confirm.

The preview also returns a QuoteId that you can send in the Create Purchase request to honor the quoted exchange rate.

📘

This guide documents the v3 Purchase Preview. The preview mirrors the Create Purchase request, so the same payment instrument and customer data produce an accurate quote.

Choose your flow

As with Create Purchase, the preview has two variants depending on your PCI compliance level. Use the option that matches your integration:

⚠️

Only one payment instrument should be included in your request: CardData (PCI only), TrxToken, or PaymentMethod.

Choose your environment

Non-PCI Merchants

Use these endpoints when the payment is tokenized through Bamboo's Tokenization Form or processed via an alternative payment method.

PCI-Certified Merchants (raw card data)

Use these endpoints when sending card data directly (PAN, CVV, Expiration). Available only for merchants certified under PCI DSS.

⚠️

Only PCI-certified merchants can access the secure secure-api endpoints.

Note
Remember to include your merchant's Private Key in the request headers.

Building the request

The preview accepts the same identifying fields as a purchase. The taxes and exchange rate depend on the amount, currency, destination country, payment instrument, and customer data, so provide as much of it as you can for an accurate quote.

Request parameters

¹ One of CardData (PCI), TrxToken, NetworkToken, or PaymentMethod identifies the payment instrument. ² For countries such as Argentina, Customer (with DocumentType, DocumentNumber and Address.State) is required to calculate the applicable taxes.

CardData object (PCI merchants only)

💡

For non-PCI merchants, card payments must be tokenized using the Tokenization Form; send the resulting TrxToken instead of CardData.

Customer object

Address object

Example with Token (Non-PCI)

To test this endpoint, use the API Reference or the Postman Collection

{
  "TrxToken": "OT__6dHAgJo6qeg62qIroA7H7_f_NWZZ6IEx4jiYpVJ8SzQ_",
  "Amount": 10000,
  "Currency": "USD",
  "TargetCountryISO": "AR",
  "Installments": 1,
  "Order": "AR-2025-0001",
  "Customer": {
    "FirstName": "Juan",
    "LastName": "Pérez",
    "Email": "[email protected]",
    "DocumentType": "DNI.AR",
    "DocumentNumber": "20222222223",
    "Address": {
      "Country": "AR",
      "State": "Buenos Aires",
      "PostalCode": "8512"
    }
  }
}

Example with Card Data (PCI)

To test this endpoint, use the API Reference or the Postman Collection

{
  "CardData": {
    "CardHolderName": "Juan Pérez",
    "Pan": "4507990000004905",
    "CVV": "123",
    "Expiration": "08/30",
    "Email": "[email protected]",
    "Document": "20222222223"
  },
  "Amount": 10000,
  "Currency": "USD",
  "TargetCountryISO": "AR",
  "Installments": 1,
  "Order": "AR-2025-0001",
  "Customer": {
    "FirstName": "Juan",
    "LastName": "Pérez",
    "Email": "[email protected]",
    "DocumentType": "DNI.AR",
    "DocumentNumber": "20222222223",
    "Address": {
      "Country": "AR",
      "State": "Buenos Aires",
      "PostalCode": "8512"
    }
  }
}

Response

The preview returns the destination currency, the total amount the customer will be charged, the exchange rate applied, and the breakdown of charges and taxes.

ExchangeRate object

Charges object

Response Example

{
  "ErrorCode": null,
  "ErrorDescription": null,
  "QuoteId": "b3f1c2a4-9d6e-4f02-8a1b-7c2e5d4f6a90",
  "CurrencyCode": "ARS",
  "TotalAmount": 58865.98,
  "ExchangeRate": {
    "Value": 402.09,
    "Code": "USD/ARS"
  },
  "Charges": [
    {
      "CurrencyCode": "ARS",
      "AmountCategoryCode": "Gross",
      "Amount": 40209.00,
      "Sign": "Debit",
      "ResponsibleType": "Buyer",
      "ExchangeRate": {
        "Value": 402.09,
        "Code": "USD/ARS"
      },
      "Tax": null
    },
    {
      "CurrencyCode": "ARS",
      "AmountCategoryCode": "Tax",
      "Amount": 9650.16,
      "Sign": "Debit",
      "ResponsibleType": "Merchant",
      "ExchangeRate": null,
      "Tax": {
        "Code": "AR-VAT-DIGITAL",
        "Name": "VAT",
        "Percentage": 20.0
      }
    },
    {
      "CurrencyCode": "ARS",
      "AmountCategoryCode": "Tax",
      "Amount": 965.02,
      "Sign": "Debit",
      "ResponsibleType": "Merchant",
      "ExchangeRate": null,
      "Tax": {
        "Code": "AR-INGR-BRUTOS",
        "Name": "II.BB",
        "Percentage": 2.0
      }
    }
  ]
}

Test the API

Test your preview integration in the API Reference: