Documentation

Create an EFT Transaction

Suggest Edits

Electronic Funds Transfer (EFT) allows users to transfer money electronically between bank accounts, either within the same financial institution or across different institutions. These transactions occur through computer-based systems without the direct involvement of bank staff.

In Brazil, users typically complete EFT payments using PIX, an instant payment system developed by the Central Bank. During checkout, the user selects their bank from a list or is redirected to their banking app or website. Authorization is often immediate, especially with instant methods like PIX.

Key Differences in Gateway Mode

In gateway mode, merchants integrate directly with the payment provider using our Direct API. This integration includes specific validation behaviors for PIX transactions:

  • No transaction amount limits.
  • No daily, monthly, or yearly transaction limits per end-user.

Additional Validations for Online Betting

For the online betting segment in Brazil, our platform performs additional compliance checks:

  • Bank account information provided in the request is validated.
  • The payer's identity is verified using the document submitted and matched against the data returned by PIX.

PIX (Brazil)

Payment MethodCountryRefundsRecurringChargebacksTypeSub-type
PIXBRYesNoNoeftpix

PIX is Brazil’s instant payment method developed by the Central Bank. It allows funds to be transferred within seconds, 24/7, including weekends and holidays. PIX transactions can be initiated from checking, savings, or prepaid accounts.

Each PIX transaction includes:

  • Issuer Bank Information
  • Payment Amount
  • QR Code
  • Payment Code

EFT Payment Flow

  1. Customer → Merchant: The customer submits payment information on the merchant's website.
  2. Merchant → PagSeguro: The merchant sends a request to the Create transaction endpoint.
  3. PagSeguro → Merchant: PagSeguro returns a transaction code, QR code image, and payment code.
  4. Merchant → Customer: The merchant displays the QR code and payment code to the customer.

Step 1: Collecting Customer's Information

Before initiating the payment, you need to collect all necessary information from the customer. This includes basic details such as their name, email, birth date, contact information, and address. Make sure that all fields are correctly filled out to avoid any issues during the payment process.

Step 2: Requesting a PIX Payment

After the customer sends their information, you can use the Create transaction endpoint to submit it to PagSeguro.

📘

Minimum Transaction Amount

The minimum amount for a credit card transaction is 1.00 BRL.

Below are examples of Default and Gateway Mode requests and a success response:

{
    "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
        }
    ]
}

{
    "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",
        "ip": "200.221.118.80",
        "document": {
            "type": "CPF",
            "number": "98765432101"
        },
        "banks": [
            {
                "code": "00000000",
                "account": {
                    "type": "SVN",
                    "branch": "0001",
                    "number": "1234567"
                }
            },
            {
                "code": "00000000",
                "account": {
                    "type": "SVN",
                    "branch": "0001",
                    "number": "1234567"
                }
            }
        ],
        "address": {
            "street": "Rua Teste",
            "number": "1102",
            "complement": "AP 302",
            "district": "Bairro dos testes",
            "state": "PR",
            "city": "Maringá",
            "country": "BR",
            "zip-code": "87030000"
        }
    },
    "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
        }
    ]
}

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

📘

Reason Codes

If the request fails, the API will return an HTTP status code other than 200. The response body will include an errors array with descriptive messages and corresponding error codes.

For the full list of possible error codes, see the Reason Codes reference.

Step 3: Displaying Payment Codes

With the payment-code and qrcode-image from the response, you can display the PIX payment page for your client.

Confirmation Page Example

PIX Confirmation Page

Best Practices for PIX Payments

Follow these best practices to increase payment success rates and provide a smooth user experience:

  • Always display a confirmation page
    After creating a transaction, direct the user to a confirmation page where they can complete the payment.

  • Show both the QR code and payment code
    Some users may not be able to scan the QR code—offering the text-based payment code as a fallback ensures better accessibility.

  • Ensure exact payment amounts
    The amount paid must match the transaction amount precisely. Discrepancies may cause the payment to fail.

  • Guide users to use the correct payment flow
    Instruct users to choose the "Pay with QR Code" option in their banking app. Standard bank transfers are not supported and will not be recognized.

  • Inform users about payment code expiration
    PIX payment codes are valid for 1 hour. Encourage users to complete the transaction promptly.

  • Set expectations for confirmation speed
    PIX payments are typically confirmed within 10 seconds, allowing for near real-time transaction updates.

Updated 20 days ago