PIX

PIX is an official Brazilian payment method launched by the local Central Bank. It allows for immediate payment confirmation and is available 24/7. To complete a payment, the payer can use any Home Banking or Wallet App by copying and pasting a Transaction ID or scanning a QR code.

↪️
Redirect Flow for PIX
This payment method uses a Redirect flow. The API response includes an Action.URL and the purchase remains in Pending status until the customer completes the payment in the Internet Banking.

Request parameters

The following parameters are required specifically for this payment method.
Refer to the Purchase operation guide for standard fields and authentication requirements.

Property	Type	Mandatory?	Description
`PaymentMethod`	`string`	Yes	`PIX` - Review the Payment Method Table.
`TargetCountryISO`	`string`	Yes	Indicate the destination country.
`Customer` → `Email`	`string`	Yes	Customer's email.
`Customer` → `FirstName`	`string`	Yes	Customer's first name.
`Customer` → `LastName`	`string`	Yes	Customer's last name.
`Customer` → `DocumentType`	`string`	Yes	Customer's document type. Refer to the Document types table to see the possible values.
`Customer` → `DocumentNumber`	`string`	Yes	Customer's Document Number.
`Customer` → `PhoneNumber`	`string`	No	Customer's phone number.
`Customer` → `Address` → `Country`	`string`	No	Customer's Country.
`Customer` → `Address` → `State`	`string`	No	Customer's State.
`Customer` → `Address` → `City`	`string`	No	Customer's City.
`Customer` → `Address` → `AddressDetail`	`string`	No	Customer's Address Detail.
`Customer` → `Address` → `PostalCode`	`string`	No	Customer's Postal Code.
`MetaDataIn` → `PaymentExpirationInMinutes`	`numeric`	Yes	Configure the expiration time for the payment using this field, specifying the duration in minutes.
`MetadataIn` → `AddressStreet`	`string`	No	Customer address street.
`MetadataIn` → `AddressNumber`	`string`	No	Customer address number, floor, apartment.
`MetadataIn` → `AddressDistrict`	`string`	No	Customer address district.

Request example

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

{
    "PaymentMethod": "PIX",
    "Order": "paymentID3022",
    "Amount": 20000,
    "Currency": "BRL",
    "Description": "Purchase Test",
    "MetaDataIn": {
        "PaymentExpirationInMinutes": "7200",
        "AddressStreet": "Avenida Anisio Fernandes Coelho",
        "AddressNumber": "661",
        "AddressDistrict": "PR"
    },
    "TargetCountryISO": "BR",
    "Customer": {
        "Address": {
            "AddressDetail": "Avenida Anisio Fernandes Coelho, 661 ",
            "PostalCode": "29060670",
            "City": "Vitoria",
            "State": "ES",
            "Country": "Brasil"
        },
        "FirstName": "Jhon",   
        "LastName": "Doe",
        "DocumentNumber": "47168892703",
        "DocumentType": "CPF.BR",
        "PhoneNumber": "3188060418",
        "Email": "[email protected]"
    }
}

Response parameters

In the response, you will find the following parameters:

Property	Type	Description
`MetadataOut` → `PaymentCode`	`string`	Payment code generated by PIX.
`MetadataOut` → `PaymentBarCode`	`string`	This code, which corresponds in Brazil to the copia e cola, allows payers to copy it in their bank app. This parameter is handy to generate the QR code when creating your checkout.
`MetadataOut` → `PaymentBarCodeUrl`	`string`	URL of the payment page, this page has the QR code generated with the string returned in `PaymentBarCode` parameter. You can also redirect the payer to this page to complete the payment.
`MetadataOut` → `PaymentExpirationDate`	`date`	Date when the payment will expire. Format DD/MM/YYYY HH:MM:SS.

Payment page in PIX

💡
Depending on your user flow, you can display both the QR Code and Copia e Cola in your interface, or use the voucher generated by Bamboo as an alternative.
The Banco Central do Brasil recommends showing both to ensure a consistent payment experience, but mobile flows may opt to display only the Copia e Cola string.

Response example

{
    "TransactionId": "128635201747174176",
    "Result": "COMPLETED",
    "Status": "PENDING",
    "ErrorCode": null,
    "ErrorDescription": null,
    "Created": "2024-12-20T20:46:20.199",
    "AuthorizationDate": "2024-12-20T20:46:20.674",
    "AuthorizationCode": "",
    "Amount": 1000,
    "Currency": "BRL",
    "Installments": 1,
    "TaxableAmount": null,
    "Tip": null,
    "Url": "https://api.stage.bamboopayment.com/Purchase/128635201747174176",
    "MetadataOut": {
        "PaymentCode": "b961a342fa172d22f22767134b0aebf1e86fa337038d4634f470ab894d71f9fc",
        "PaymentBarCode": "00020126910014BR.GOV.BCB.PIX2569api-pix-h.bancobs2.com.br/spi/v2/7cc95f1a-743e-4f4a-a3ad-e2ba14f5f6f8520400005303986540510.005802BR59086014Belo Horizonte61083038040362070503***63049F6B",
        "PaymentDigitableLine": "api-pix-h.bancobs2.com.br/spi/v2/7cc95f1a-743e-4f4a-a3ad-e2ba14f5f6f8",
        "PaymentBarCodeUrl": "https://pagar.sandbox.goboleto.com/?hash=b961a342fa172d22f22767134b0aebf1e86fa337038d4634f470ab894d71f9fc",
        "PaymentExpirationDate": "21/12/2024 20:09"
    },
    "Action": null,
    "PaymentMethod": {
        "Brand": "Pix",
        "CardOwner": null,
        "Bin": null,
        "IssuerBank": null,
        "Type": "BankTransfer",
        "Expiration": null,
        "Last4": null
    }
}

Discover the API

Once you’re familiar with how to create a purchase, you can test your integration using our API Reference:

Country Requirements

Check what each country requires in terms of documents, bank formats, and supported currencies.

Create a Payment

Explore full request and response examples.

Error Codes

Understand possible error responses and how to resolve them.