Electronic funds transfer (EFT) is the electronic transfer of money from one bank account to another, either within a single financial institution or across multiple institutions, via computer-based systems, without the direct intervention of bank staff. Consumers pay for goods using their online banking facility. They are either redirected to their bank or select their bank from a provider’s page. In most cases the Authorization is immediately, especially when payment is made via an instant payment such as PIX.

Available Payment Methods

Payment MethodCountriesRefundsRecurringChargebacksTypeSub-type
PIXBRYesNoNoeftpix

Brazil

PIX

Type: eft

Sub-type: pix

Pix is the Brazilian instant payment. The payment method created by the Central Bank (BC) in which funds are transferred between accounts in a few seconds, at any time or day. It's practical, fast and secure. Pix can be made from a checking account, savings account or prepaid payment account.

PIX always includes:

  • Issuer bank information
  • Payable amount value
  • QR Code: This is the image of the QR Code generated for the payment, the buyer can scan it using the Pix App of their choice.
  • Payment Code: This is the code generated by the PIX, which can be used directly in the payer's PIX application or in their Internet Banking to process the payment.

Workflow


  1. Customer fills and submits all necessary payment information to the merchant server.
  2. The merchant submits to /transactions to create the transaction.
  3. PagSeguro creates an order and returns the transaction code, QR Code image and payment code to the merchant.
  4. The merchant displays the QR Code image and payment code to the customer.

Creating an PIX Payment

To create an PIX payment method, make a POST request as the example.

⚠️

The minimum amount value is 1.00 BRL.

Request

📘

Production URL:

https://api.boacompra.com/transactions

Method: POST

🚧

Sandbox URL:

https://api.sandbox.boacompra.com/transactions

Method: POST

Example of a request using PIX

{
    "transaction": {
        "reference": "REF-XXX-1234567890",
        "project-number": 1,
        "country": "BR",
        "currency": "BRL",
        "checkout-type": "direct",
        "notification-url": "https://billing.checkout.com/processing",
        "language": "pt-BR"
    },
    "charge": [
        {
            "amount": 1.00,
            "payment-method": {
                "type": "eft",
                "sub-type": "pix"
            }
        }
    ],
    "payer": {
        "name": "John Doe",
        "email": "[email protected]",
        "birth-date": "1988-12-25",
        "phone-number": "+5511987654321",
        "document": {
            "type": "CPF",
            "number": "98765432101"
        },
        "address": {
            "street": "Rua Teste",
            "number": "1102",
            "complement": "AP 302",
            "district": "Bairro dos testes",
            "state": "PR",
            "city": "Maringá",
            "country": "BR",
            "zip-code": "87030000"
        },
        "ip": "200.221.118.80"
    },
    "shipping": {
        "cost": 0,
        "address": {
            "street": "Rua Teste",
            "number": "1102",
            "complement": "AP 302",
            "district": "Bairro dos testes",
            "state": "PR",
            "city": "Maringá",
            "country": "BR",
            "zip-code": "87030000"
        }
    },
    "cart": [
        {
            "quantity": 1,
            "description": "My Product",
            "category": "Collectibles",
            "type": "physical",
            "unit-price": 1.00
        }
    ]
}

Request Parameter List

ParameterDescriptionTypeSizeMandatory
transactionSet of general transaction's informationObject-Yes
transaction.referenceMerchant transaction identifierStringUp to 64Yes
transaction.project-numberMerchant project identifier. Default value is 1Integer-No
transaction.countryCountry of the payment. Accepts only BRString2Yes
transaction.currencyCurrency transactionString3e.g.: BRL
transaction.checkout-typeCheckout type of the transaction. Accepts only directString-Yes
transaction.notification-urlURL (must bind ports 80 or 443) used to send transaction status changes notifications by HTTPStringUp to 200Yes
transaction.languageLanguage used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TRString5Yes
charge[]Set of payments. Currently accepting just one paymentArray1Yes
charge[].amountAmount of the transaction. Separating cents by point, with two decimal places. Amount sum must be equal to shipping.cost plus cart items valueDoubleMin of 0.40 BRLYes
charge[].payment-method.typePayment Method type (credit-card, postpay , e-wallet or eft)String-Yes
charge[].payment-method.sub-typePayment Method sub-type. Available payment methods (see more)String-Yes
payerSet of customer's informationObject-Yes
payer.nameCustomer nameStringUp to 50Yes
payer.emailCustomer e-mailStringUp to 60Yes
payer.birth-dateCustomer birth date. ISO-8601 Pattern (YYYY-MM-DD)String-No
payer.phone-numberCustomer phone number. e.g (+5544999884455)String-No
payer.document.typeCustomer document Type. accepts: cpf and cnpjString-Yes
payer.document.numberCustomer identification document. No special characters allowed.String-Yes
payer.ipCustomer IP. accepts IPv4 or IPv6String-Yes
payer.addressCustomer address objectObject-No [1]
payer.address.streetCustomer address streetString1 - 160Yes
payer.address.numberCustomer address numberString1 - 20Yes
payer.address.complementCustomer address complementStringUp to 40No
payer.address.districtCustomer address districtString1 - 60Yes
payer.address.stateCustomer address state or provinceString2Yes
payer.address.cityCustomer address cityString1 - 60Yes
payer.address.countryCustomer address country (country iso 2)String2Yes
payer.address.zip-codeCustomer address zip codeString8Yes
shippingSet of information that will be used to deliver the items in cart (see more)Object-No [1]
shipping.costShipping cost. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
shipping.address.streetShipping address streetString3 - 160Yes
shipping.address.numberShipping address numberString1 - 20Yes
shipping.address.complementShipping address complementString5 - 40No
shipping.address.districtShipping address districtString4 - 60Yes
shipping.address.stateShipping address state or ProvinceString2Yes
shipping.address.cityShipping address cityString3 - 60Yes
shipping.address.countryShipping address country (country iso 2)String2Yes
shipping.address.zip-codeShipping address zip CodeString8Yes
cart[]Set of items (at least one Item)ArrayMin of 1Yes
cart[].quantityItem quantityIntegerMin of 1Yes
cart[].descriptionItem descriptionString1 - 200Yes
cart[].unit-pricePrice per unit. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
cart[].typeItem type - must be one of the following: digital, physical, service, subscriptionString-Yes
cart[].categoryItem categoryString1 - 64No
[1] Required when cart[].type is physical

Some considerations about the payer name:

  • Maximum length of 50 characters
  • Minimum two words
  • Each word must be separated by ONE space
  • The first and last word must have at least 2 characters long
  • Middle words can have only one character
  • Accepted characters: A to Z, uppercase and/or lowercase letters
  • Special characters accepted: éíóúãõâêôàèìòùäëïöüçñÁÉÍÓÚÃÕÂÊÔÀÈÌÒÙÄËÏÖÜÇÑ&/'.-

Some considerations about the payer email:

  • On the local-part (before the @), only alphanumeric characters and the special characters - + . _ are allowed.

Response

Example of a response using PIX

{
  "transaction": {
    "code": "418824267",
    "reference": "REF-XXX-1631109433",
    "amount": 1,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2021-09-08T10:57:17.781893506-03:00",
    "payment-code": "00020101021226830014br.gov.bcb.pix2561api.pagseguro.com/pix/v2/21D1BDC9-6ACF-4A94-B552-72A1D946EECD27600016BR.COM.PAGSEGURO013621D10000-6ACF-4A94-B552-72A1D946EECD52047994530398654041.005802BR5922BOA COMPRA TECNOLOGIA 6009Sao Paulo62070503***630412C3",
    "qrcode-image": "https://payment.boacompra.com/img/V1kxd1Y1SUVuQjlUWk81d2kyNlhnZz09"
  }
}

Response Parameter List

PropertyDescriptionTypeSizeFormat
transaction.codePagSeguro´s referenceStringUp to 36e.g.: 111181153
transaction.referenceMerchant´s referenceStringUp to 64XXX-XXX-XX-XXXXXXXXXX
transaction.amountTransaction AmountNumber-e.g.: 50.0
transaction.statusCurrent status (see more)String-e.g.: PAID
transaction.currencyCurrency transactionString3e.g.: BRL
transaction.countryCountry transactionString2e.g.: BR
transaction.payer-emailPayer emailStringUp to 60e.g.: [email protected]
transaction.date-createdDate of creationString-e.g.: 2018-10-10T14:39:32.991217999-03:00
transaction.payment-codeCode generated for the payment, can be copied and pasted by the payer.String250e.g.: 00020101021226830014br.gov.bcb.pix2561api.pagseguro.com/pix/v2/21D1BDC9-6ACF-4A94-B552-72A1D946EECD27600016BR.COM.PAGSEGURO013621D1BDC9-6ACF-4A94-B552-72A1D946EECD52047994530398654041.005802BR5922BOA COMPRA TECNOLOGIA 6009Sao Paulo62070503***630412C3
transaction.qrcode-imageURL with the image of the generated QR Code.String64e.g.: https://payment.boacompra.com/img/V1kxd1Y1SUVuQjlUWk81d2kyNlhnZz09

PIX best practices

When providing an alternative payment method like PIX, it is required to include a confirmation page on the flow. Furthermore, on this page we can include some features to increase the payment method conversion, as well as informing the particularities of the payment method chosen to the customer.
Points of attention for payment with PIX:

  • The amount paid must be the same as the transaction amount if the amount paid is different the payment will not be recognized.
  • The payer must use the option "pay with QR Code" in the app or internet banking.
  • The payer cannot use the transfer option to complete the payment if this occurs the payment will not be recognized by the system.
  • The Pix generated by the system is valid for 1 hour, after this period it will not be recognized and cannot be paid.
  • The payment takes an average of 10 seconds to be confirmed.

Confirmation page example

In Brazil, Banks, Mobile Wallets APPs has the funcionallity to make payment with PIX, where users can scan the QR Code or just Inserting the Copy of Payment Code.

  1. When you provide a QR Code with a good quality resolution it will make the convertion payment increase as it will allow the client make the payment easly just point their phone and scanning the QR Code to finalize the payment.

    INFO: To use this feature, use transaction.qrcode-image included in PIX's transaction response.

  2. When you provide the Copy of your Payment Code it will also help to increase your sales if by any chance the user couldn´t make the payment with QR Code, in this case it will allow the client make a copy of the payment code and insert it in their Bank or Wallet App to finalize the payment.

    **INFO**: To use this feature, use the `transaction.payment-code` line included in the Pix transaction response.
    

    Those two options mentioned will definitly make you payment convertion increase so if you want higher volume of sale this mandatory for you.