Overview

Creating a purchase allows your system to request a payment authorization through Bamboo’s API. The same endpoint supports multiple payment methods (from card transactions to cash and bank transfers) across all countries where Bamboo operates.

Depending on your PCI certification level, purchases can be created using:

• CardData – for PCI-certified merchants who handle card details directly.
• TrxToken – for merchants who use tokenized cards.
• PaymentMethod – for alternative payments such as cash or bank transfers.

Each flow shares the same structure for amount, currency, customer, and country fields.

Choose your flow

Each merchant can create purchases differently depending on their PCI compliance level and the payment method selected. Use the option that matches your integration:

⚠️

Only one of these fields should be included in your request: CardData, TrxToken, or PaymentMethod.

Choose your environment

Bamboo provides two environments. Depending on how you handle card data, the endpoint you should use varies:

• Staging for simulations and homologation (recommended first).
• Production for live payments after certification.

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.

Non-PCI Merchants

Use these endpoints when validating cards through Bamboo’s Tokenization Form, which handles card data securely and returns a token for later use.

💡

Non-PCI merchants must use these endpoints together with the Tokenization Form, which captures and encrypts card data outside the merchant’s environment.

Building the request

Some fields are mandatory in every purchase, no matter which flow you choose. Others are highly recommended or recommended for optimal fraud detection and risk evaluation.

Request parameters

CardData object (PCI merchants only)

💡

For non-PCI merchants, card payments must be processed using the tokenization form provided by Bamboo.

Customer object

Address object

AntifraudData object

Use the AntifraudData object to send additional information used by Bamboo’s antifraud engine. Although optional, including this object improves the accuracy of risk evaluation.

ℹ️

For details about how these fields are validated and used in risk evaluation, refer to the Anti-fraud section.

¹ One of TrxToken, NetworkToken, or PaymentMethod is required depending on the selected flow.

³ Not required if you create the purchase using CommerceToken.

⁴ Some acquirers (e.g., Brazil card) may require a specific Description format.

💳

For detailed information about 3D Secure (3DS) and Network Token objects, see their dedicated sections. PaymentMethod is mandatory when sending a Network Token.

Example with Token

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

{
    "TrxToken": "OT__6dHAgJo6qeg62qIroA7H7_f_NWZZ6IEx4jiYpVJ8SzQ_",
    "UniqueID": "paymentID3022",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Installments": 2,
    "Order": "CH2023-001",
    "Description": "Compra de teste",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "12345678901",
        "DocumentType": "CPF.BR",
        "Email": "[email protected]",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    },
  "CustomerIP": "190.10.224.231",
  "AntifraudData": {
    "AntifraudFingerprintId": "0046f17b-197a-4d63-8b6b-6082cdd557ff"
  }
}

Example with Card Data

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

{
    "CardData": {
        "CardHolderName": "João Silva",
        "Pan": "4507990000004905",
        "CVV": "123",
        "Expiration": "08/30",
        "Email": "[email protected]",
        "Document": "12345678901"
    },
    "UniqueID": "paymentID3022",
    "Capture": true,
    "TargetCountryISO": "BR",
    "Currency": "BRL",
    "Amount": 25000,
    "Installments": 2,
    "Order": "CH2023-001",
    "Description": "Compra de teste",
    "Customer": {
        "FirstName": "João",
        "LastName": "Silva",
        "ReferenceCode": "JS-001",
        "PhoneNumber": "11987654321",
        "DocumentNumber": "12345678901",
        "DocumentType": "CPF.BR",
        "Email": "[email protected]",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    },
  "CustomerIP": "190.10.224.231",
  "AntifraudData": {
    "AntifraudFingerprintId": "0046f17b-197a-4d63-8b6b-6082cdd557ff"
  }
}

Example for an Alternative Payment Method

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

{
  "PaymentMethod": "PFC",
  "Order": "AR-2025-0001",
  "Amount": 100000,
  "Currency": "ARS",
  "Description": "Compra de prueba",
  "TargetCountryISO": "AR",
  "Customer": {
    "FirstName": "Juan",
    "LastName": "Pérez",
    "Email": "[email protected]",
    "DocumentType": "DNI.AR",
    "DocumentNumber": "12345678",
    "ReferenceCode": "CLI-45821"
  }
}

Response

The response structure for Direct Purchase (PCI merchants) is the same as the standard Purchase response.

Action object

PaymentMethod object

Response Examples

Result : COMPLETED, Status:APPROVED

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

{
   "ErrorCode": "PR001",
   "ErrorDescription": "The token sent is invalid, expired, or does not belong to the merchant."
}

Test the API

Once you’re familiar with how to create a purchase, test your integration in the API Reference: