Brazil Transactions

PIX

There are two types of PIX payments in Brazil: static and dynamic. First, it is important to understand that the PIX payment is only a shortcut for the bank account your customers have in Brazil.

Static PIX

For Static PIX payments, you will share your PIX key with the customer so they can make a payment using this key – usually it is an e-mail address or a random key (EVP). The customer will pay using their bank account and you will receive it in your account within Attrus. The customer can choose any amount to pay.

How to get your PIX key: The PIX key for your Attrus account is provided along with your API credentials during onboarding. You can also find it in the Bank Accounts section of the Attrus Portal.

Important requirements:

• The customer must be registered in your system before making the payment, so we can properly identify and reconcile the incoming funds
• For this type of payment, you don't need to create a transaction via API — as soon as we receive the payment, an automatic transaction will be created and you will receive an identified webhook notification

Example of sharing PIX key with your customer:

PIX Key (Email): [email protected]
PIX Key (EVP): e55eeo1d-01ef-016e-14d0-a1ea701ae17e

Once the customer pays using this PIX key, you will receive a webhook notification with the transaction details.

Dynamic PIX (QR Code)

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "subject_id": "customer id",
    "from_bank_account_id": "your physical BRL bank account id",
    "to_bank_account_id": "the internal BRL cash in id",
    "currency": "BRL",
    "exchange_currency": "BRL",
    "value": "1500.00",
    "use_dynamic_pix": true,
    "dynamic_pix_expires_at": "2025-05-08T08:30:44.074Z"
  }
}'

{
  "data": {
    "value": "1500.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Power HT Co. Ltd.",
      "owner_document_number": "1589632472",
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "internal": true,
      "intermediary_bank_account": null,
      "id": "9b95f84e-de61-460b-a14b-f23b4e71c97b",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "BRL",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "subject_is_receiver": false,
    "subject_id": "f5d357c6-7655-43f8-9e9f-8eebc2cecad1",
    "subject": {
      "updated_at": "2022-07-07T20:46:06.507246",
      "status": "approved",
      "social_name": "Machado de Assis",
      "required_clearance_level": 1,
      "references": [],
      "phone_number": "3138894070",
      "net_monthly_average_income": "0.00",
      "inserted_at": "2021-03-11T00:47:52.287547",
      "id": "f5d357c6-7655-43f8-9e9f-8eebc2cecad1",
      "fiscal_country": "Brasil",
      "email": "[email protected]",
      "document_type": "cpf",
      "document_number": "12345678909",
      "clearance_level": 1,
      "birth_date": "1994-04-01",
      "address_street": "Rua Barão do Rio Negro",
      "address_state": "SP",
      "address_postal_code": "16201220",
      "address_number": "310",
      "address_country": "Brasil",
      "address_complement": "Apt. 44 A",
      "address_city": "Birigui"
    },
    "status": "pending",
    "source_name": "Machado de Assis",
    "source_document_type": "cpf",
    "source_document_number": "12345678909",
    "meta": null,
    "inserted_at": "2025-01-15T10:30:44.074Z",
    "id": "b0a21c5f-56bd-40ef-9359-f2b573ae3883",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": {
        "type": "email",
        "key": "[email protected]"
      },
      "owner_name": "FACILITA FX MERCANTIL FINANCEIRO LTDA",
      "owner_document_number": "10789035000105",
      "intermediary_bank_account_id": null,
      "id": "8b2812f0-d6c8-4073-97bb-9fa964d08bc5",
      "iban": null,
      "currency": "BRL",
      "branch_number": "0311",
      "branch_country": "Brasil",
      "bank": {
        "swift": "PLURBRRJ",
        "name": "BRASIL PLURAL S.A. BANCO MÚLTIPLO",
        "id": "292c1958-4926-4c7d-8550-6ce9c0952552",
        "code": "125"
      },
      "account_type": "conta-corrente",
      "account_number": "562001-1",
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "279.85",
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "dynamic_pix_code": "00020101021226990014br.gov.bcb.pix2577pix.bancogenial.com/qrs1/v2/017si5czJTt4zOys319ukH9l1UD8m94JJ0xnElX3Bc6rMK3ug52040000530398654041.005802BR5923FACILITA PAGAMENTOS S/A6009SAO PAULO62070503***6304B8B8",
    "currency": "BRL",
    "cleared": true,
    "bank_transaction": null
  }
}

For Dynamic PIX payments, you'll need to create a transaction with the transaction endpoint. This type of payment requires a fixed value to be paid, and an expiration date. You will request for the dynamic pix, and we will return with a code that you will transform into the QR Code to share with the customer. Unlike the static, the dynamic QR code is unique for each payer, expirable, and its amount cannot be changed once it's generated.

You will also get a payment_expired webhook if it's not paid within the expiration date. Besides the use_dynamic_pix flag, you'll also need to provide the expiration date in dynamic_pix_expires_at.

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
transaction	An object containing all the required values	object	true
subject_id	The ID generated when you registered you customer as one of your subjects	UUID	true
from_bank_account_id	The ID of the BRL exclusive bank account that we opened for you	UUID	true
to_bank_account_id	The destination bank account ID whose currency is equals to the exchange_currency field	UUID	true
currency	Must be "BRL" for pix transactions	string	true
exchange_currency	One of: BRL, USD or EUR	string	true
use_dynamic_pix	Must be true for pix transactions. You don't need to send this field for other payment methods	boolean	true
value	Amount you want to charge with two decimal places only, e.g.: "1500.00"	string	true
dynamic_pix_expires_at	Future date at least more than 1 minute ahead of the current UTC date time. Format: YYYY-MM-DDThh:mm:ssZ	datetime	false

warning

Common Mistakes

Using an account without a registered pix key

Solution: You used an account that does not have a pix key registered on the portal. Contact our support team and share the request/response. We'll set up a pix account for you.

Providing an invalid date time format

Solution: You must provide the specified date time format. Check in the "Body Parameters" section above

Providing a past date

Solution: You must use a future date with more the 1 minute ahead of the current UTC date time

TED

The TED payment is a normal bank transfer. For this type of transaction, instead of sharing with the customer a PIX Key, you'll share the details of your bank account. The required information includes: Account Number, Account Branch, Beneficiary name, and Document Number.

Where to find your bank account details: You can find your Attrus bank account details in the Bank Accounts section of the Attrus Portal, under "Attrus Pay-in accounts". This information is also provided during onboarding along with your API credentials.

After sharing these details, the customer uses it to pay you the value they need to. For this type of payment, you don't need to create a transaction request, only have your customer registered, as soon as we receive the payment, an automatic transaction will be created.

Boleto

Boleto is a Brazilian payment method that generates a document containing a unique number and a barcode. It can be paid at banks, authorized retail stores, ATMs, or directly through the customer's banking app. You define the expiration date when generating the boleto. Once your customer makes the payment, confirmation can take up to 3 business days, as the settlement process is not instant. Paid or not, you will receive a webhook with the status change.

Please note that, due to regulatory requirements, the boleto must display the payer's full address. Therefore, the subject_id provided must be registered with all address_* fields. Additionally, both email and phone number are also mandatory.

After generating the boleto, three new variables will appear in the response:

1. url_pdf: an endpoint to download a full PDF;
2. bar_code: A string that can be converted to an image, so it can be displayed to your customer - to be scanned later;
3. digital_line: A string that can be displayed with the option to enable the customer to copy the boleto bar code and paste it into their bank app.

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "BRL",
    "exchange_currency": "USD",
    "value": "400.00",
    "from_boleto": {
      "expire_at": "2023-08-30"
    },
    "to_bank_account_id": "your internal cash-in USD/BRL id",
    "subject_id": "customer id"
  }
}'

200OK

{
  "data": {
    "value": "400.00",
    "to_bank_account": {
      "routing_number": "011103093",
      "pix_info": null,
      "owner_name": "Power Co. Ltd.",
      "owner_document_number": null,
      "owner_company": {
        "social_name": "POWER HOME THEATER",
        "id": "f64e512c-1a81-42d9-9ac9-05f369bc98e3",
        "document_type": "tax_id",
        "document_number": "2348909854385"
      },
      "nickname": null,
      "internal": false,
      "intermediary_bank_account": null,
      "id": "b51dff12-071f-486d-9667-9f3295186e3b",
      "iban": "DE89 3704 0044 0532 0130",
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": "BOFAUS2N",
        "name": "Bank of America",
        "id": "74673d00-b36c-40ed-b34c-19c6602e09f0",
        "code": null,
        "ispb": null,
        "country": null
      },
      "account_type": "conta-corrente",
      "account_number": "000518987",
      "aba": null
    },
    "subject_is_receiver": false,
    "subject_id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
    "subject": {
      "updated_at": "2023-08-10T14:33:08.174767",
      "status": "approved",
      "social_name": "Amedeo Mancini",
      "rfc_pf": null,
      "required_clearance_level": 2,
      "references": [],
      "phone_number": "434898404898",
      "net_monthly_average_income": "5000.00",
      "inserted_at": "2021-03-26T20:22:04.358980",
      "id": "9e474282-8b37-4d05-9c77-eab27976cfe9",
      "fiscal_country": "Brasil",
      "email": "[email protected]",
      "document_type": "cpf",
      "document_number": "20000000027",
      "clearance_level": 2,
      "birth_date": null,
      "address_street": "Alameda Cannobio",
      "address_state": "MG",
      "address_postal_code": "34008009",
      "address_number": "75",
      "address_neighborhood": "Jardim dos Alpes",
      "address_country": "Brasil",
      "address_complement": "Apto 1005",
      "address_city": "Nova Lima"
    },
    "status": "pending",
    "source_name": "Amedeo Mancini",
    "source_document_type": "cpf",
    "source_document_number": "20000000027",
    "meta": null,
    "inserted_at": "2023-08-10T14:33:08.161412",
    "id": "6fd2af11-dbb8-4d89-b761-8d7c6ac458e5",
    "from_credit_card": null,
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "BRL",
    "cleared": true,
    "from_boleto": {
      "bar_code": "19826349578720611155268124261060776497871242",
      "city": "Birigui",
      "district": "Res. Sao Jose",
      "expire_at": "2024-08-30",
      "inserted_at": "2024-08-11T16:13:17.729215",
      "line": "58973.44844 89239.499662 57704.966099 0 41481286139131",
      "name": "Joaquim dos Santos",
      "state_code": "SP",
      "status": "created",
      "street_line_1": "Rua Barão do Rio Branco, 310",
      "street_line_2": "Apt 20",
      "tax_id": "676.457.273-90",
      "updated_at": "2024-08-12T10:13:12.521215",
      "url_pdf": "https://api.facilitapay.com/api/v1/transactions/6fd2af11-dbb8-4d89-b761-8d7c6ac458e5/boleto_pdf",
      "zip_code": "16201-220"
    },
    "bank_transaction": null
  }
}

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
transaction	An object containing all the required values	object	true
currency	Source currency for the transaction (ISO 4217 format)	string	true
exchange_currency	Currency to be exchanged (ISO 4217 format)	string	true
value	Value to be exchanged (in the source currency)	string	true
from_boleto	An object, containing the following parameters:	object	true
from_boleto.expire_at	Expiration date of the boleto in the format YYYY-MM-DD	string	true
to_bank_account_id	ID of the account you will send the funds after the boleto is paid	string	true
subject_id	ID of your customer	string	true

Boleto PDF Download

After receiving the response, retrieve the data.id field and use it in the following endpoint to download the boleto PDF. The API will return the PDF file directly as a binary response.

curl -X GET "https://api.facilitapay.com/api/v1/transactions/:id/boleto_pdf" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."

HTTP Request

GET /transactions/:id/boleto_pdf

Path Parameters

Parameter	Description	Type	Required
id	The ID generated when a boleto transaction is created	string	true

Download Boleto PDF Sample

Checkout Page for cards

For Brazil we give the option to have a pre-built, hosted checkout page (HPP) for your customer pay with cards, if you don't wish to implement one yourself. Our system will generate a unique checkout URL and a corresponding checkout ID. You can share this checkout URL directly with your customers, allowing them to complete their payment through our secure payment page.

Once the payment is completed, we will notify you by sending a payment confirmation to your webhook endpoint along with the checkout ID, which can be used as a reference for tracking and managing the transaction within your system. The checkout URL will remain active until a payment is successfully processed, after that the checkout page will no longer be accessible.

If the payment attempt fails, we will also notify you via webhook. The checkout page will also remain active until a successful payment is made.

curl -X POST "https://api.facilitapay.com/api/v1/transactions/checkout" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "subject_id": "customer id",
  "value": "100.00",
  "currency": "BRL",
  "exchange_currency": "BRL",
  "to_bank_account_id": "your cash-in internal account BRL or USD"
}'

200OK

{
  "data": {
    "checkout_page_url": "https://app.sandbox.attrus.com/card/checkout?id=80c675cc-5a68-4023-87a3-faf13401d424",
    "id": "80c675cc-5a68-4023-87a3-faf13401d424"
  }
}

HTTP Request

POST /transactions/checkout

Body Parameters

Parameter	Description	Type	Required
subject_id	ID of one of the partner's customer	string	true
value	Transaction value with two decimal places in the original currency, e.g., 100.00	string	true
currency	Transaction currency (ISO 4217 format), e.g., BRL	string	true
exchange_currency	Destination bank account currency. It can be the local currency (BRL), or international currencies (USD/EUR)	string	true
to_bank_account_id	Id of the destination bank account. This bank account must have the same currency as the exchange_currency field	string	true

Payout (BRL)

After registering your customer bank account with us, you will be able to pay them locally using the following endpoint. If you registered only the PIX key, we will be using it, if you registered the Bank details and PIX Key we will prioritize to pay via TED.

The payout transactions are initiated within your foreign currency cash-out account

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": { 
    "currency": "USD", 
    "exchange_currency": "BRL", 
    "value": "500.00", 
    "from_bank_account_id": "your USD/EUR cash-out internal account id", 
    "to_bank_account_id": "the id of your customer bank account", 
    "subject_id": "your customer id"
  } 
}'

200OK

{
  "data": {
    "value": "500.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": {
        "type": "CNPJ",
        "key": "00.623.904/0001-73"
      },
      "owner_name": "Jose Bonifacio",
      "owner_document_type": "cpf",
      "owner_document_number": "27029324013",
      "nickname": null,
      "intermediary_bank_account_id": null,
      "id": "c41b7cf3-455c-46c1-bb6d-7fd0e1b83799",
      "iban": null,
      "currency": "BRL",
      "branch_number": null,
      "branch_country": "BRA",
      "bank": {
        "swift": "BCBPIXCNPJ000",
        "name": "PIX Key - CNPJ",
        "ispb": null,
        "id": "aa3bfacc-dd6b-4a68-b37a-7672b43b1c52",
        "country": "BRA",
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "01e0725b-b4f5-46b1-811a-a3cbcb314d10",
    "status": "identified",
    "source_name": "John Doe",
    "source_document_type": "cpf",
    "source_document_number": "05069869183",
    "meta": null,
    "inserted_at": "2025-07-10T14:50:16.805590",
    "id": "49330924-1284-418f-9d6f-3a22c13411a3",
    "from_credit_card_id": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Biriweb Serviços de Internet Ltd",
      "owner_document_type": null,
      "owner_document_number": "21958642819",
      "nickname": null,
      "internal": true,
      "intermediary_bank_account_id": null,
      "id": "6b1d3acf-42b7-4f5a-8d9b-1da2766e040b",
      "iban": null,
      "flow_type": "cash_out",
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "ispb": null,
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "country": "BRA",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "for_exchange": true,
    "exchange_under_request": false,
    "exchange_currency": "BRL",
    "estimated_value_until_exchange": false,
    "currency": "USD",
    "cleared": true,
    "bank_transaction": {
      "wire_id": null,
      "value": "500.0",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "TED-PRE",
      "source_name": "John Doe",
      "source_id": "49330924-1284-418f-9d6f-3a22c13411a3",
      "source_document_type": "cpf",
      "source_document_number": "05069869183",
      "source_description": "CREDITO POR TED ANTECIPADO",
      "source_branch": null,
      "source_bank_ispb": null,
      "source_bank": null,
      "source_account": null,
      "movement_date": "2025-07-10",
      "iof_value": null,
      "inserted_at": "2025-07-10T14:50:16.861725",
      "id": "54045ef6-95ae-4fff-96f4-f82f1442548b",
      "exchanged_value": null,
      "exchange_rate_spot": null,
      "exchange_rate": null,
      "exchange_id": null,
      "exchange_currency": "BRL",
      "exchange_approved": false,
      "currency": "USD"
    }
  }
}

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
transaction	An object containing all the required values	object	true
currency	Source currency for the transaction (ISO 4217 format)	string	true
exchange_currency	Currency to be exchanged (ISO 4217 format)	string	true
value	Value to be exchanged (in the source currency)	string	true
from_bank_account_id	ID of your cash-out internal account	string	true
to_bank_account_id	ID of your customer's bank account	string	true
subject_id	ID of your customer	string	true