Create a Purchase

Create a purchase using the API flow providing its basic information for PCI and Non-PCI Merchants.

Configuring the authentication

All methods used in Purchase API require the following authentication headers.

Key	Value	Comments
`Content-Type`	`application/json`	With this header, the request will be transmitted in JSON format.
`Authorization`	`Basic {{Merchant Private Key}}`	Send the `{{Merchant Private Key}}` (your merchant identifier) and the word `Basic`. Example: `Basic RVkeLr-86_iTzSMLvDtuyQ-1zqIcsmFG-oSzncn_uFv-nj7bhB3rtZg__`

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.

Create a Purchase

After successfully tokenizing a card, you can proceed with generating a purchase using this method. The Purchase API is specifically designed for merchants who do not have PCI DSS certification, allowing them to process payments securely without handling sensitive card data directly.

For alternative payment methods such as cash payments or bank transfers, you only need to provide the corresponding payment method ID to initiate the transaction.

Request URL

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

Production: https://api.bamboopayment.com/v3/api/purchase
Stage: https://api.stage.bamboopayment.com/v3/api/purchase

Request parameters

Parameter	Type	Mandatory?	Description
`TrxToken`	`string`	No¹	Card token, previously generated through the tokenization flow. Used for card payment methods.
`NetworkToken`	`object`	No¹	Network token information used in the transaction. For more information, review the Network Tokenization Object.
`PaymentMethodId`	`integer`	No¹	Payment method identifier. Used only for alternative payment methods (transfer, cash, etc.)
`UniqueID`	`string`	No	Unique identifier of the purchase. This optional value allows you to identify a unique purchase and avoid duplication of transactions in case of communication errors. For more information, refer to Concepts.
`Capture`	`boolean`	No	Defines whether the purchase should be performed in one or two steps.² If `false`, only the authorization is processed, and the purchase is pre-authorized until the final confirmation through the capture and cancel calls. If `true`, the transaction is authorized and captured. All payment methods and countries may not support the pre-authorization feature.
`TargetCountryISO`	`string`	Yes	This parameter indicates the country where the payment will be processed. Send the country using `ISO-3166-1` format.
`Currency`	`string`	Yes	Currency of the purchase, according to ISO-4217. Find the possible values in the Currencies table of each country.
`Amount`	`integer` (64 bits)	Yes	Amount of the purchase. This value must be greater than zero. If you must include decimals in the amount, concatenate the decimal places without the decimal point. Example `12,25` > `1225`.
`Tip`	`integer` (64 bits)	No	Tip amount in the transaction. Value with two decimals, without points or commas.
`TaxableAmount`	`integer` (64 bits)	No	Taxable amount of the transaction. Value with two decimals, without points or commas.
`Installments`	`integer`	No	Number of installments.
`Order`	`string`	Yes	Order number generated by the merchant.
`InvoiceNumber`	`string`	No	Invoice number associated with the transaction.
`Description`	`string`	No ⁴	Optional description of the purchase.
`AdditionalData`	`string`	No	Additional information that may be relevant to the transaction.
`MetadataIn`	`object`	No	Additional transaction data in key-value format.
`Customer`	`object`	Yes ³	The `Customer` object provides the data of the person who performs the purchase.

Customer Object

Parameter	Type	Mandatory?	Description
`Customer` → `FirstName`	`string`	No	Customer’s first name.
`Customer` → `LastName`	`string`	No	Customer’s last name.
`Customer` → `ReferenceCode`	`string`	No	Reference code for the customer.
`Customer` → `PhoneNumber`	`string`	No	Customer’s phone number.
`Customer` → `DocumentNumber`	`string`	No	Customer’s document number.
`Customer` → `DocumentType`	`string`	No	Document type. (Format `DOCUMENT`.`COUNTRY`)
`Customer` → `Email`	`string`	No	Customer’s email address.
`Address`	`object`	No	Customer’s shipping address.

Address Object

Parameter	Type	Mandatory?	Description
`Address` → `Country`	`string`	No	Country of the customer address.
`Address` → `City`	`string`	No	City of the customer address.
`Address` → `State`	`string`	No	State or region of the customer address.
`Address` → `PostalCode`	`string`	No	Postal code of the customer address.
`Address` → `AddressDetail`	`string`	No	Additional details of the customer address.

Notes

¹ The PaymentMediaId and TrxToken parameters are not required. Nevertheless, sending one of them is mandatory, depending on the flow you want to use.
² All the payment methods may not support the pre-authorization feature. Review the Countries and payment methods section to check availability.
³ This object is not required if you create the purchase using CommerceToken.
⁴ When using cards in Brazil, the description is mandatory and must use a fixed format, as explained in the request parameters.
Keep in mind that for the Anti-fraud system’s correct functioning, we suggest sending additional data described in the Anti-fraud section.
For detailed information about 3D Secure - 3DS and Network Token objects, please refer to their corresponding sections in this documentation. PaymentMethodId is mandatory when sending a Network Token.

Request example

{
    "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": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    }
}

Direct Purchase for PCI-Compliant Merchants

For merchants who have achieved PCI DSS compliance, Bamboo offers enhanced flexibility through the Direct Purchase method. This advanced option allows PCI-compliant merchants to handle card data directly within their secure environments.

Request URL

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

Production: https://secure-api.bamboopayment.com/v3/api/purchase
Stage: https://secure-api.stage.bamboopayment.com/v3/api/purchase

Request parameters

CardData Object

Parameter	Type	Mandatory?	Description
`CardHolderName`	`string`	Yes	The name of the cardholder as it appears on the card.
`Pan`	`string`	Yes	The Primary Account Number (PAN) of the card.
`CVV`	`string`	Yes	The Card Verification Value (CVV) or Card Security Code.
`Expiration`	`string`	Yes	The expiration date of the card in the format “MM/YY”.
`Email`	`string`	Yes	The email associated with the cardholder.
`Document`	`string`	No	The identification document number of the cardholder.

Info

Note: The CardData object should only be used for transactions with non-tokenized cards. Ensure that sensitive card data is handled securely and in compliance with PCI DSS standards.

Request example

{
    "CardData": {
        "CardHolderName": "João Silva",
        "Pan": "4507990000004905",
        "CVV": "123",
        "Expiration": "08/30",
        "Email": "joao.silva@example.com",
        "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": "joao.silva@example.com",
        "Address": {
            "Country": "BR",
            "City": "São Paulo",
            "State": "SP",
            "PostalCode": "01310-200",
            "AddressDetail": "Avenida Paulista 1000"
        }
    }
}

The fields CardData, PaymentMethodId, NetworkToken and TrxToken are not required; Nevertheless, one of them must be send depending of which flow to use.

Response

The response structure for Direct Purchase operations performed by PCI-compliant merchants is identical to the standard Purchase response. This ensures consistency across different transaction types and simplifies integration processes.

All fields, statuses, and error codes described in the standard Purchase response apply equally to Direct Purchase transactions.

Parameter	Type	Description
`TransactionId`	`string`	Unique identifier for the transaction. A 19-digit number sent as a string for compatibility.
`Result`	`string`	Outcome of the transaction. `COMPLETED` or `ACTION_REQUIRED`. See the “Action” object for instructions.
`Status`	`string`	Current status of the transaction (e.g., Approved, Rejected).
`ErrorCode`	`string`	Error code if the transaction was rejected.
`ErrorDescription`	`string`	Detailed description of the error if the transaction was rejected.
`Created`	`string`	Timestamp of when the transaction was created, in ISO 8601 format.
`AuthorizationDate`	`string`	Timestamp of when the transaction was authorized, in ISO 8601 format.
`AuthorizationCode`	`string`	Unique code provided by the issuer to confirm the transaction authorization.
`Amount`	`integer`	Total transaction amount.
`Currency`	`string`	Currency code used for the transaction. May differ from the request currency based on business agreements.
`Installments`	`integer`	Number of payment installments for the transaction.
`TaxableAmount`	`integer`	Amount subject to taxes.
`Tip`	`integer`	Tip amount.
`Url`	`string`	Link to access additional transaction details.
`MetadataOut`	`object`	Additional metadata returned with the transaction response.
`Action`	`object`	Details of required actions when Result is “ACTION_REQUIRED”.
`PaymentMethod`	`object`	Information about the payment method used for the transaction.

Action Object

The Action object provides information about additional steps required to complete a transaction. It is typically present when the transaction result is “ACTION_REQUIRED”, indicating that further action is needed from the user or merchant to finalize the payment process.

Parameter	Type	Description
`SessionId`	`string`	Session identifier related to the action. Informational value.
`Reason`	`string`	Reason for the requested action. Possible values: • `VERIFICATION_CODE_NEEDED:` Transaction pending CVV, redirection to “URL” required to display CVV input form. • `REDIRECTION_NEEDED_EXTERNAL_SERVICE`: Redirection to “URL” required to complete transaction details.
`URL`	`string`	Redirection URL to complete the required action.

PaymentMethod Object

The PaymentMethod object contains detailed information about the payment method used in the transaction. This includes card details (for card transactions) or other relevant payment method information.

Parameter	Type	Description
`Brand`	`string`	Brand of the card used (e.g., MasterCard, Visa).
`CardOwner`	`string`	Name of the cardholder.
`Bin`	`string`	First 6 digits of the card number.
`IssuerBank`	`string`	Issuing bank of the card.
`Type`	`string`	Type of payment method (e.g., CreditCard, DebitCard).
`Expiration`	`string`	Card expiration date in yyyymm format.
`Last4`	`string`	Last 4 digits of the card number.

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": 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"
    }
}

Result:COMPLETED - Status: REJECTED

{
    "TransactionId": "79632697147789184",
    "Result": "COMPLETED",
    "Status": "REJECTED",
    "ErrorCode": "LP042",
    "ErrorDescription": "Insufficient balance.",
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": "2024-08-07T17:51:56.879",
    "AuthorizationCode": "839936",
    "Amount": 25000,
    "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"
    }
}

Result:ACTION_REQUIRED - Status: PENDING

{
    "TransactionId": "79632697147789184",
    "Result": "ACTION_REQUIRED",
    "Status": "PENDING",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-08-07T17:51:54.620",
    "AuthorizationDate": null,
    "AuthorizationCode": null,
    "Amount": 25000,
    "Currency": "BRL",
    "Installments": 2,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/79632697147789184",
    "MetadataOut": null,
    "Action": {
        "SessionId": "CA_a4032a2a-25ae-4f5f-a8bb-fb2e5ab2ae3c",
        "URL": "https://url_to_be_redirected.com/redirection_example",
        "Reason": "VERIFICATION_CODE_NEEDED"
    },
    "PaymentMethod": {
        "Brand": "Visa",
        "CardOwner": "João Silva",
        "Bin": "450799",
        "IssuerBank": "Banco do Brasil",
        "Type": "CreditCard",
        "Expiration": "203008",
        "Last4": "4905"
    }
}

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

Last modified September 19, 2024