General Transactions

Making transactions

Transactions can be registered by the customer by sending money via Regular Bank Transfer (TED), Pix, Boleto (bank slip), Credit Card or SPEI. Sometimes, creating transactions through this endpoint will not be needed, as when your customer makes a deposit to your exclusive account within Attrus, our API will notify you with a webhook and a transaction ID. However, if you intend to use Credit Card, Boleto or Dynamic Pix, this endpoint must be used.

After a transaction is created and the bank transfer is identified, our back-office team will close the exchange rate and the converted amount to be connected for each transaction. At the end of the day, a transfer is registered by our staff with the sum of the exchanged amount that will be transferred to the customer.

In the next sections separate examples for each transaction type will be provided, from the most common to more specific cases. Either way, all types of transactions use the same endpoint - as will be seen.

Bank Account IDs

The Bank Account IDs will be the ones which you will use for every transaction within Attrus's environment. Each ID has a use, and you can check the IDs in your Portal or in the credentials we sent you to access the API.

Every country has 3 IDs related to its account: a Local Currency cash-in ID, a Foreign Currency cash-in ID related to that local currency, and a Foreign Currency cash-out ID also related to that local currency.

from_bank_account_id will always be the sender account.

to_bank_account_id will always be the receiver account.

For Pay-in transactions, the field from_bank_account_id will be the ID of your Real bank account within Attrus, and to_bank_account_id will be the ID of the internal account you want to send that money to (BRL/MXN/COP/CLP or USD cash-in).

For Payout transactions, the field from_bank_account_id will be your internal cash-out account (BRL/MXN/COP/CLP or USD), and to_bank_account_id will be the account you have registered to pay the local customer.

For FX transactions, conversions, exchanges, and changes between internal accounts, from_bank_account_id will be the cash-in account ID (BRL/MXN/COP/CLP), and to_bank_account_id will be the foreign currency cash-in account ID (USD/EUR) related to that local currency cash-in.

For Settlements, the field from_bank_account_id will be the foreign currency cash-in ID (USD/EUR), and to_bank_account_id will be the ID of your account overseas, already registered by Attrus.

For Deposits and pre-funding, the field from_bank_account_id will be the ID of Attrus's international account – you can check it in “Attrus pay-in accounts” – and to_bank_account_id will be the ID of your cash-out account.

All types of transactions – Pay-ins, Payouts, Conversions, Settlements - use the same endpoint, the only changes are in the currencies, bank account and subject id parameters.

HTTP Request

POST /transactions

For Pay-in transactions this endpoint will be used for payment methods that require more information than of the mandatory customer registration. For example, a Pix payment done directly for the Pix key shared with the customer does not require to be created on your side, you only need to have the customer registered for us to reconcile the payment. The same with normal SPEI transactions, where you only share your bank details and the customer pays directly to that CLABE.

However, if you intend to use Credit Card, Boleto, Dynamic Pix, Dynamic Clabe and PSE this endpoint must be called.

Example 1: Pay-In - BRL to USD

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": "1000.00",
    "from_bank_account_id": "97313a02-bbbb-4341-bb2c-3602d185d926",
    "to_bank_account_id": "766eadfc-f020-4d2a-bed3-c9a95623ed24",
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21"
  }
}'

{
  "data": {
    "value": "1000.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "nome",
      "owner_document_type": null,
      "owner_document_number": "doc",
      "owner_company": {
        "social_name": "Company Test",
        "id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
        "document_type": "tax_id",
        "document_number": "21958642819"
      },
      "nickname": null,
      "intermediary_bank_account": null,
      "id": "766eadfc-f020-4d2a-bed3-c9a95623ed24",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": "swift test",
        "name": "International Bank Test",
        "ispb": null,
        "id": "dab1d4c3-a5a7-4ffa-bab9-b1cc155081c0",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "12356",
      "aba": null
    },
    "subject_is_receiver": false,
    "subject": {
      "updated_at": "2025-07-09T17:19:48.174209",
      "status": "approved",
      "social_name": "John Doe",
      "rfc_pf": null,
      "required_clearance_level": 1,
      "references": [],
      "phone_number": "99812-1212",
      "phone_country_code": "55",
      "phone_area_code": "18",
      "net_monthly_average_income": "4000.00",
      "inserted_at": "2021-03-11T20:13:17.729215",
      "id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
      "fiscal_country": "BR",
      "email": "[email protected]",
      "document_type": "cpf",
      "document_number": "01234567890",
      "clearance_level": 2,
      "birth_date": "2015-04-01",
      "address_street": "Rua Barão do Rio Branco",
      "address_state": "SP",
      "address_postal_code": "16201220",
      "address_number": "310",
      "address_neighborhood": null,
      "address_country": "BR",
      "address_complement": "Apt. 44 A",
      "address_city": "Birigui"
    },
    "status": "wired",
    "source_name": "John Doe",
    "source_document_type": "cpf",
    "source_document_number": "05069869183",
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
    "inserted_at": "2021-04-29T21:51:51.648253",
    "id": "00b8a279-38c0-4764-9c41-87cf0a8a529f",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "owner_name": "FACILITA PAGAMENTOS S/A",
      "owner_document_type": "cnpj",
      "owner_document_number": "10789035000105",
      "nickname": null,
      "intermediary_bank_account_id": null,
      "id": "97313a02-bbbb-4341-bb2c-3602d185d926",
      "iban": null,
      "currency": "BRL",
      "branch_number": "0001",
      "branch_country": "BRA",
      "bank": {
        "swift": "PLURBRRJ",
        "name": "Facilita Bank S.A.",
        "ispb": "10789035",
        "id": "292c1958-4926-4c7d-8550-6ce9c0952552",
        "country": "BRA"
      },
      "account_type": "conta-corrente",
      "account_number": "3467-3",
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "167.01",
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "BRL",
    "cleared": true,
    "bank_transaction": {
      "wire_id": "6fe36590-6c1a-4e86-9998-edcc4b54c94b",
      "value": "1000",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "WIRE",
      "source_name": "John Doe",
      "source_id": null,
      "source_document_type": "cpf",
      "source_document_number": "05069869183",
      "source_description": "CREDITO POR TED",
      "source_branch": "1142",
      "source_bank_ispb": null,
      "source_bank": "033",
      "source_account": "130013844",
      "movement_date": "2025-07-09",
      "iof_value": "3.80",
      "inserted_at": "2025-07-09T17:50:10.137550",
      "id": "6c763e54-d819-47b8-9d2b-a06380c1e4af",
      "exchanged_value": "167.01",
      "exchange_rate_spot": "5.906",
      "exchange_rate": "5.98773",
      "exchange_id": "7fc49fb2-40b0-4558-bb1b-89829fde0241",
      "exchange_currency": "USD",
      "exchange_approved": true,
      "currency": "BRL"
    }
  }
}

Solution: Provide accounts with matching currencies as in the request.

Example 2: Pay-Out - USD to BRL

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": "a2474d90-eca9-47ac-90f2-0487d51b4bef",
    "to_bank_account_id": "c41b7cf3-455c-46c1-bb6d-7fd0e1b83799",
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21"
  }
}'

{
  "data": {
    "value": "500.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": {
        "type": "CNPJ",
        "key": "00.623.904/0001-73"
      },
      "owner_name": null,
      "owner_document_type": "cpf",
      "owner_document_number": null,
      "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": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
    "subject": {
      "updated_at": "2021-04-29T22:15:10.988964",
      "status": "approved",
      "social_name": "John Doe",
      "required_clearance_level": 1,
      "references": [],
      "phone_number": null,
      "net_monthly_average_income": "15000.00",
      "inserted_at": "2021-03-08T19:56:22.628081",
      "id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
      "fiscal_country": "Brasil",
      "email": null,
      "document_type": "cpf",
      "document_number": "05069869183",
      "clearance_level": 1,
      "birth_date": "1965-04-06",
      "address_street": "Rua Barão do Rio Branco",
      "address_state": "SP",
      "address_postal_code": "16201220",
      "address_number": "2252",
      "address_country": "BR",
      "address_complement": "Apt 101",
      "address_city": "Washington"
    },
    "status": "wired",
    "source_name": "John Doe",
    "source_document_type": "cpf",
    "source_document_number": "05069869183",
    "inserted_at": "2021-04-29T22:21:38.938318",
    "id": "6da07cf4-1ea2-4c92-bb0d-b690b067dad6",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "FACILITA PAY",
      "owner_document_type": null,
      "owner_document_number": "N/A",
      "nickname": null,
      "intermediary_bank_account_id": null,
      "id": "a2474d90-eca9-47ac-90f2-0487d51b4bef",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": "swift-facilitapay-test",
        "name": "Test Bank",
        "ispb": null,
        "id": "9e56957c-47d9-4762-a544-eed567bf1a71",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "1017",
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "2688.08",
    "exchange_under_request": false,
    "exchange_currency": "BRL",
    "estimated_value_until_exchange": false,
    "currency": "USD",
    "cleared": true,
    "bank_transaction": {
      "wire_id": null,
      "value": "500",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "WIRE",
      "source_name": "John Doe",
      "source_id": null,
      "source_document_type": "cpf",
      "source_document_number": "05069869183",
      "source_description": "CREDITO POR TED",
      "source_branch": "1142",
      "source_bank_ispb": null,
      "source_bank": "033",
      "source_account": "130013844",
      "movement_date": "2025-07-09",
      "iof_value": "11.22",
      "inserted_at": "2025-07-09T18:38:25.219175",
      "id": "e7e08097-75ae-4ee5-b55d-1c970b8b4109",
      "exchanged_value": "2912.36",
      "exchange_rate_spot": "5.906",
      "exchange_rate": "5.82472",
      "exchange_id": "68df160f-ff84-4f3b-b26b-e8535fe65048",
      "exchange_currency": "BRL",
      "exchange_approved": true,
      "currency": "USD"
    }
  }
}

Solution: Provide accounts with matching currencies as in the request.

Transaction List

You can list all the transactions made; it will be ordered from the most recent ones. You can use some parameters to filter the transactions of this list, like customer, day and time, status, currency and others.

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

200OK

{
  "data": [
    {
      "value": "1250.00",
      "to_bank_account_id": "c3d8b7e8-4022-4ce6-9d45-c4666ea53653",
      "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-09T19:25:27.114588",
      "id": "4835d070-2042-4e95-8771-48fd46d6fa6b",
      "from_credit_card": null,
      "from_bank_account_id": "a2474d90-eca9-47ac-90f2-0487d51b4bef",
      "for_exchange": true,
      "exchanged_value": "7280.90",
      "exchange_under_request": true,
      "exchange_currency": "BRL",
      "estimated_value_until_exchange": false,
      "currency": "USD",
      "cleared": true
    }
  ]
}

Note that the API can return the maximum of 100 entries in this list.

Query Parameters

Parameter	Description	Type	Required
`last_id`	Last transaction UUID for pagination	string	false
`per_page`	Number of elements per page	string	false
`id`	Transaction UUID	string	false
`status`	Filter only transaction based on status	string	false
`from`	Filter from date/time, e.g.: 2022-05-01T03%3A00%3A00.000Z	iso datetime	false
`to`	Filter to date/time, e.g.: 2022-05-30T03%3A00%3A00.000Z	iso datetime	false
`currency`	Filter to match only the selected currency	string	false
`exchange_currency`	Filter to match only the selected currency as exchanged	string	false
`subject_id`	subject_id used in the transactions	string	false

Transaction Details

To check the details of a transaction, who paid, the value, the ids, date of payment, currency and more, you can check this endpoint:

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

200OK

{
  "data": {
    "value": "500.00",
    "currency": "USD",
    "to_bank_account": {
      "owner_name": "Daniels de Paolo",
      "owner_document_number": "01010101099",
      "owner_company": {
        "social_name": "Dagny Taggart",
        "id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
        "document_type": "passport",
        "document_number": "J83579487346"
      },
      "id": "9fbdea6a-40a7-463c-9912-bb737e2d9722",
      "currency": "BRL",
      "branch_number": "5198",
      "bank": {
        "id": "f9dcd833-a4a8-4595-8f5a-b63b0a98292d",
        "code": "031",
        "name": "Banco do Estado de Minas Gerais"
      },
      "account_type": "conta-corrente",
      "account_number": "04378-9"
    },
    "subject_is_receiver": false,
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
    "status": "wired",
    "source_name": "Dagny Taggart",
    "source_document_type": "passport",
    "source_document_number": "J83579487346",
    "inserted_at": "2021-04-29T22:21:38.938318",
    "id": "6da07cf4-1ea2-4c92-bb0d-b690b067dad6",
    "from_credit_card": null,
    "from_bank_account": {
      "id": "74b66fcf-5b16-473e-8eb3-3ef5d2f74036",
      "owner_name": "FACILITA FX MERCANTIL FINANCEIRO LTDA",
      "currency": "USD",
      "bank": {
        "id": "292c1958-4926-4c7d-8550-6ce9c0952552",
        "swift": "PLURBRRJ",
        "name": "BRASIL PLURAL S.A. BANCO MÚLTIPLO"
      },
      "account_type": "conta-corrente",
      "account_number": "8901304468"
    },
    "for_exchange": true,
    "exchange_currency": "BRL",
    "exchanged_value": "2688.08",
    "exchange_under_request": false,
    "estimated_value_until_exchange": false,
    "cleared": true
  }
}

HTTP Request

GET /transactions/:id

Path Parameters

Parameter	Description	Type	Required
`id`	Transaction UUID	string	true

Transaction Status

All transactions will change their status along the payment flow. This section will clarify their statuses and their meaning.

Pay-In Transaction Status

These are the different statuses a pay-in transaction can have.

Status	Description
`pending`	No payment was made by the customer.
`identified` (from local currency to foreign currency)	The funds from the transaction were received in the local currency, but were not yet converted to the foreign currency.
`identified` (from local currency to local currency)	The funds from the transaction were received in the local currency and are now available on your internal account. This is a final status for this scenario
`exchanged`	The money was converted to the foreign currency. If the destination account is an internal, this will be the final status
`wired`	It is the final status for pay-in done to your external international bank account, means the payment was successfully made
`canceled`	When for any reason the transaction cannot be concluded or need to be reversed, it is canceled.

Pay-Out Transaction Status

These are the different statuses a pay-out transaction can have. In the staging environment, all registered transactions will be automatically processed (status: wired), if there is enough balance in the internal cash-out bank account.

Important: If you register a payout without enough available balance in the internal cash-out account, that payout transaction will block any subsequent payouts using the same account. These other payouts will remain in a pending status, even if there's enough balance for them, until sufficient funds are available to complete the first pending payout.

Example: You create a payout of 10,000.00, but your internal cash-out account has only 5,000.00. This transaction will remain in a pending status. If you then create another payout of 2,000.00, even though you have enough balance for it, it will also remain pending, blocked by the first payout.

To resolve this, you can either add more funds to the internal cash-out account or contact our production team to cancel the first payout transaction.

Status	Description
`pending`	This status will occur if you didn't not have enough balance in the cash-out bank account to cover the transaction.
`identified`	This means there was sufficient balance to cover the transaction, and the funds have already been allocated to the payout, however the wire transfer has not been executed yet.
`exchanged`	This is an intermediate status indicating that the funds have been converted, but the payment has not yet been completed. It only applies to payouts involving a conversion from foreign currency to local currency and occurs after the `identified` status.
`wired`	This is the final status for payouts. It means the payment was successfully completed, and the funds have already been sent to the destination bank account.
`canceled`	When for any reason the transaction cannot be concluded or need to be reversed, it is canceled.

Exchange/Conversion Transaction Status

For exchange/conversion transactions, the status indicates the progress of the exchange/conversion.

Status	Description
`exchanged`	the conversion rate has been closed, and therefore, the exchanged value is defined - when the destination is to an internal bank account, this is the final state.

Settlement Transaction Status

For settlements, the status indicates the progress of the wire transfer to your external international bank account.

Status	Description
`wired`	The exchanged value has been wired to its destination – your external international bank account overseas - that is also the final state.

Getting Exchange Rates (FX)

This endpoint will return 3 rates, for the foreign currencies we offer (USD, EUR, AUD, CAD, CHF, JPY, CNY, GBP) and the local currencies (BRL, MXN, COP), and you can check the values for that moment, where:

brlusd is the rate for BRL –> USD operations (already including the IOF and FX margin negotiated)

usdbrl is the rate for USD –> BRL operations (already including IOF and FX margin negotiated)

brlusdspot is the current spot rate (without margin or IOF).

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

200OK

{
  "data": {
    "brlusd": "5.70243",
    "brlusdspot": "5.62460000",
    "usdbrl": "5.54719"
  }
}

HTTP Request

GET /exchange_rates

Conversion between Internal Accounts

info

Example of a Conversion Between Cash-in Accounts

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": "1000.00",
    "from_bank_account_id": "your internal cash-in BRL",
    "to_bank_account_id": "your internal cash-in USD",
    "subject_id": "your partner_id"
  }
}'

info

Example of a Conversion Between Cash-out Accounts

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 internal cash-out USD",
    "to_bank_account_id": "your internal cash-out BRL",
    "subject_id": "your partner ID"
  }
}'

200OK

{
  "data": {
    "value": "1000.00",
    "to_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": "74416779-ad7b-4b7c-918e-21598700effd",
      "iban": null,
      "flow_type": "cash_in",
      "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
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "status": "exchanged",
    "source_name": "Biri Web",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "meta": null,
    "inserted_at": "2025-05-13T18:28:38.188522",
    "id": "748d8794-64dc-4a72-9f84-13b4f01addf4",
    "from_credit_card": 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": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "BRL",
      "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,
    "exchanged_value": "176.05",
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "cleared": true
  }
}

This request should be used when you need to convert funds held in your internal accounts. Conversions are only allowed between accounts of the same flow type — that is, Cash-in to Cash-in and Cash-out to Cash-out.

The payload is the same for conversions in Brazil, Mexico, Colombia and any other local currencies. Only the field's currency and from_bank_account_id will need to change to match the country's currency used.

For conversion in Chile, the value field should not contain decimal places for cents. E.g.: 15000 (instead of 15000.00)

For the correct bank account to be used in this call, check the Bank Accounts in the upper menu of your portal or in and look for the section named "Attrus pay-in accounts" to find an account that matches the same currency you are using.

Conversions between your internal cash-out accounts allow you to convert funds into local currencies, making them readily available for future payouts. As a result, the payout process becomes faster and more seamless, with minimal friction, since the currency conversion has already been handled in advance.

This is the same flow for all other countries such as Brazil, Mexico, Colombia and Chile. Always remember to replace the exchange_currency and the to_bank_account_id with the appropriate values to match the country you are sending the money to.

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": "1000.00",
    "from_bank_account_id": "your internal cash-in BRL",
    "to_bank_account_id": "your internal cash-in USD",
    "subject_id": "your partner_id",
    "exchange_under_request": true
  }
}'

To proceed with exchanges with a locked FX rate, you will use the exchange_under_request flag. When setting it to true, the rate shown in that moment will be the one used for the conversion later.

curl -X POST "https://api.facilitapay.com/api/v1/transactions/exchange_under_request" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
    "exchange": {
      "transaction_ids": [
        "d8af89f2-7888-4357-b5e2-3ca5ddc80c92"
      ]
    }
  }'

{
  "data": {
    "value": "1250.00",
    "user": {
      "name": "Partner Test",
      "id": "dc6630a3-43c7-4286-bb47-4ebeb39c4b18",
      "email": "[email protected]"
    },
    "to_bank_account": {
      "routing_number": null,
      "pix_info": {
        "type": "EMAIL",
        "key": "[email protected]"
      },
      "owner_name": "André Freitas Lopes",
      "owner_document_type": "cpf",
      "owner_document_number": "01472583691",
      "nickname": null,
      "intermediary_bank_account_id": null,
      "id": "c3d8b7e8-4022-4ce6-9d45-c4666ea53653",
      "iban": null,
      "currency": "BRL",
      "company": {
        "social_name": "John Doe",
        "phone_number": "99812-1212",
        "id": "01e0725b-b4f5-46b1-811a-a3cbcb314d10",
        "fiscal_country": "BR",
        "document_type": "cpf",
        "document_number": "05069869183",
        "company_name": "Company & CIA"
      },
      "branch_number": null,
      "branch_country": "BR",
      "bank": {
        "swift": "BCBPIXEMAIL000",
        "name": "PIX Key - EMAIL",
        "ispb": null,
        "id": "979657bc-494f-4642-849a-7e171ebc742b",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "iof_value": "28.05",
    "iof_rate": "0.0038",
    "inserted_at": "2025-07-09T19:27:17.891325",
    "id": "dd5e4988-66b3-457d-8024-fc3f094bb1fc",
    "fx_value": "101.6",
    "fx_rate": "0.01",
    "exchanged_value": "7280.9",
    "exchange_rate_spot": "5.90600000",
    "exchange_rate": "5.82472",
    "exchange_currency": "BRL",
    "currency": "USD",
    "bank_transactions": [
      {
        "wire_id": null,
        "value": "1250",
        "source_type": "WIRE",
        "source_name": "John Doe",
        "source_id": null,
        "source_document_type": "cpf",
        "source_document_number": "05069869183",
        "source_description": "CREDITO POR TED",
        "source_branch": "1142",
        "source_bank_ispb": null,
        "source_bank": "033",
        "source_account": "130013844",
        "movement_date": "2025-07-09",
        "iof_value": "28.05",
        "id": "7c7203c8-a1e3-4a7d-996f-600e80939c02",
        "fx_value": "101.60",
        "exchanged_value": "7280.90",
        "exchange_rate": "5.82472",
        "exchange_id": "dd5e4988-66b3-457d-8024-fc3f094bb1fc",
        "exchange_currency": "BRL",
        "exchange_approved": false,
        "currency": "USD",
        "company_name": "Gustavo Rodrigues Paludetto",
        "company_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2"
      }
    ],
    "approved_by": null
  }
}

Solution: Provide a transaction that is in identified status.

Example 3: Conversion/transfers between Internal Accounts

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": "4096.00",
    "from_bank_account_id": "your BRL cash-in account",
    "to_bank_account_id": "Your USD cash-in account",
    "subject_id": "your partner_id"
  }
}'

200OK

{
  "data": {
    "value": "4096.00",
    "to_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": "74416779-ad7b-4b7c-918e-21598700effd",
      "iban": null,
      "flow_type": "cash_in",
      "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
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "subject": {
      "updated_at": "2025-02-19T19:28:37.690718",
      "status": "approved",
      "social_name": "Biri Web",
      "rfc_pf": null,
      "required_clearance_level": 1,
      "references": [],
      "phone_number": "+55 (18) 99812-1212",
      "phone_country_code": null,
      "phone_area_code": null,
      "net_monthly_average_income": "4000.00",
      "inserted_at": "2020-01-29T05:54:23.518616",
      "id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
      "fiscal_country": "Brasil",
      "email": "[email protected]",
      "document_type": "cpf",
      "document_number": "21958642819",
      "clearance_level": 1,
      "birth_date": "1977-10-13",
      "address_street": "Rua Antonio Pontes Filho",
      "address_state": "SP",
      "address_postal_code": "16201220",
      "address_number": "310",
      "address_neighborhood": null,
      "address_country": "Brasil",
      "address_complement": null,
      "address_city": "Birigui",
      "activity_type": null
    },
    "status": "exchanged",
    "source_name": "Biri Web",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "meta": null,
    "inserted_at": "2025-05-13T18:28:38.188522",
    "id": "748d8794-64dc-4a72-9f84-13b4f01addf4",
    "from_credit_card": 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": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "BRL",
      "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,
    "exchanged_value": "684.95",
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "cleared": true,
    "bank_transaction": {
      "wire_id": null,
      "value": "4096.00",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "TED-PRE",
      "source_name": "Biri Web",
      "source_id": "8f95353c-700a-4b9e-95f4-c18cfea54844",
      "source_document_type": "cpf",
      "source_document_number": "21958642819",
      "source_description": "CREDITO POR TED ANTECIPADO",
      "source_branch": null,
      "source_bank_ispb": null,
      "source_bank": null,
      "source_account": null,
      "movement_date": "2025-07-09",
      "iof_value": "3.80",
      "inserted_at": "2025-07-09T19:06:37.868022",
      "id": "a0da1066-3990-4570-8fea-7087e5c644fe",
      "exchanged_value": "167.01",
      "exchange_rate_spot": "5.906",
      "exchange_rate": "5.98773",
      "exchange_id": "b04c546b-2ac1-4520-82db-b9574741f459",
      "exchange_currency": "USD",
      "exchange_approved": false,
      "currency": "BRL"
    }
  }
}

When you need to convert the money from the your local currency cash-in account, to the foreign currency cash-in account, you will create a internal transaction for conversion.

Body Parameters

Parameter	Description	Type	Required
`transaction`	Transaction data containing at least the following required values:	`object`	true
`currency`	Currency of the local currency cash-in account	`string`	true
`value`	Amount to be sent to the foreign currency cash-in account	`string`	true
`exchange_currency`	The "destination" currency also in (ISO 4217 format). When `currency` and `exchange_currency` are the same, no conversion will be performed and the destination would be an internal bank account	`string`	true
`from_bank_account_id`	Your local currency cash-in account ID	`string`	true
`to_bank_account_id`	Your foreign currency cash-in account ID	`string`	true
`subject_id`	Your ID with Attrus. Check it under your Registration, in the portal	`string`	true

Settlements and Deposit/Pre-funding

Example of a Settlement Transaction

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": "USD",
    "value": "10000.00",
    "from_bank_account_id": "cash-in USD",
    "to_bank_account_id": "id of your account abroad",
    "subject_id": "your partner_id"
  }
}'

200OK

{
  "data": {
    "value": "100000.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": null,
      "owner_document_type": null,
      "owner_document_number": null,
      "nickname": null,
      "intermediary_bank_account_id": null,
      "id": "bce84c35-01df-4d5d-bbcd-474bb31c50c4",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": "BOFAUS3N",
        "name": "Bank of America",
        "ispb": null,
        "id": "d66395c6-697f-4fa5-8c75-65901d5c5ae3",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "0139410341923409",
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "status": "wired",
    "source_name": "Biri Web",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "meta": null,
    "inserted_at": "2025-05-13T18:46:10.623774",
    "id": "299febc9-6420-47e8-947d-ffbabdf2768e",
    "from_credit_card": 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": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "BRL",
      "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,
    "exchanged_value": null,
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "BRL",
    "cleared": true
  }
}

To initiate a settlement transaction and send money abroad, you need to select a bank_account_id from an internal cash_in account, which will be the source of the funds, and specify your foreign account as the destination.

Example 4: Making transfers between accounts in USD

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": "USD",
    "value": "200.00",
    "from_bank_account_id": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
    "to_bank_account_id": "bce84c35-01df-4d5d-bbcd-474bb31c50c4",
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2"
  }
}'

200OK

{
  "data": {
    "value": "200.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": null,
      "owner_document_type": null,
      "owner_document_number": null,
      "nickname": null,
      "intermediary_bank_account_id": null,
      "id": "bce84c35-01df-4d5d-bbcd-474bb31c50c4",
      "iban": null,
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": "BOFAUS3N",
        "name": "Bank of America",
        "ispb": null,
        "id": "d66395c6-697f-4fa5-8c75-65901d5c5ae3",
        "country": null,
        "code": null
      },
      "account_type": "conta-corrente",
      "account_number": "0139410341923409",
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "subject": {
      "updated_at": "2025-02-19T19:28:37.690718",
      "status": "approved",
      "social_name": "Biri Web",
      "rfc_pf": null,
      "required_clearance_level": 1,
      "references": [],
      "phone_number": "+55 (18) 99812-1212",
      "phone_country_code": null,
      "phone_area_code": null,
      "net_monthly_average_income": "4000.00",
      "inserted_at": "2020-01-29T05:54:23.518616",
      "id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
      "fiscal_country": "Brasil",
      "email": "[email protected]",
      "document_type": "cpf",
      "document_number": "21958642819",
      "clearance_level": 1,
      "birth_date": "1977-10-13",
      "address_street": "Rua Antonio Pontes Filho",
      "address_state": "SP",
      "address_postal_code": "16201220",
      "address_number": "310",
      "address_neighborhood": null,
      "address_country": "Brasil",
      "address_complement": null,
      "address_city": "Birigui"
    }
  },
  "status": "wired",
  "source_name": "Biri Web",
  "source_document_type": "cpf",
  "source_document_number": "21958642819",
  "meta": null,
  "inserted_at": "2025-05-13T18:46:10.623774",
  "id": "299febc9-6420-47e8-947d-ffbabdf2768e",
  "from_credit_card": 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": "3686155e-f5f6-4e5b-97e7-60473a506b8c",
    "iban": null,
    "flow_type": "cash_in",
    "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,
  "exchanged_value": null,
  "exchange_under_request": false,
  "exchange_currency": "USD",
  "estimated_value_until_exchange": false,
  "currency": "USD",
  "cleared": true,
  "bank_transaction": {
    "wire_id": null,
    "value": "200",
    "spei_reference": null,
    "spei_concepto_de_pago": null,
    "source_type": "TED-PRE",
    "source_name": "Biri Web",
    "source_id": "60a83ac2-acfa-41e9-b25c-5b4abbcf7612",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "source_description": "CREDITO POR TED ANTECIPADO",
    "source_branch": null,
    "source_bank_ispb": null,
    "source_bank": null,
    "source_account": null,
    "movement_date": "2025-07-09",
    "iof_value": null,
    "inserted_at": "2025-07-09T20:55:57.659105",
    "id": "880eec38-a0f5-4821-871c-876ed9eee652",
    "exchanged_value": null,
    "exchange_rate_spot": null,
    "exchange_rate": null,
    "exchange_id": null,
    "exchange_currency": "USD",
    "exchange_approved": false,
    "currency": "USD"
  }
}

This example is a transaction that is similar to the previous that we just seen, in which the partner transfers an amount from his internal Attrus account to one of his USD bank account. Like the one in BRL, no exchange is made.

Body Parameters

Parameter	Description	Type	Required
`transaction`	Transaction data containing at least the following required values:	`object`	true
`currency`	Source currency	`string`	true
`value`	Amount to be sent to the foreign currency cash-in account	`string`	true
`exchange_currency`	Destination currency	`string`	true
`from_bank_account_id`	The ID of your internal bank account	`string`	true
`to_bank_account_id`	In this example is the ID of your physical USD Bank Account.	`string`	true
`subject_id`	Your ID with Attrus. Check it under your Registration, in the portal	`string`	true

Calculation of Exchange Rates

curl -X POST "https://api.facilitapay.com/api/v1/exchanges/calculate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "exchange": {
    "transaction_ids": [
      "9bdf8f35-23c0-4b28-b74e-756d17318e71"
    ]
  }
}'

warning

Common mistakes

422Unprocessable Entity

{
  "error": [
    {
      "error": "not_for_exchange_under_request",
      "description": "All transactions must be for exchange under request"
    },
    {
      "error": "transaction_not_identified",
      "description": "All transactions must have been identified before exchanged"
    },
    {
      "error": "transaction_already_exchanged",
      "description": "All transactions must have not been exchanged"
    },
    {
      "error": "transaction_already_wired",
      "description": "All transactions must have not been wired"
    }
  ]
}

Be sure the status of the transaction is identified and ready to be exchanged (under your request).

You will use this endpoint to check exchange rates and values for one or more transactions, so you can check how the exchanged value would be if the FX operation for that transaction was done at that specific time.

HTTP Request

POST /exchanges/calculate

Body Parameters

Parameter	Description	Type	Required
`exchange`	Exchange data containing at least the following required values:	`object`	true
`exchange.transaction_ids`	An array of transaction IDs you're requesting to be exchanged	`array`	true

Refund Transactions

You can refund 2 types of transactions, a non-processed or an already processed transaction. The difference between them is that the first one still did not get in your internal account, so you can use this endpoint to refund it. This payment will be taken out of the real local currency account.

Example refunding a non-processed transaction

{
  "data": {
    "id": "b3c5e4a6-26fc-4e3f-bb8c-91a7a8be68d5",
    "reason": null,
    "inserted_at": "2023-11-10T13:22:31.100380",
    "status": "identified",
    "transaction_kind": "2",
    "bank_transaction": {
      "id": "40ec25fa-59fd-4fac-a012-2091b16d34a3",
      "value": "184.73",
      "currency": "USD",
      "iof_value": null,
      "fx_value": null,
      "exchange_rate": null,
      "exchange_currency": "BRL",
      "exchanged_value": "1000",
      "exchange_approved": false,
      "wire_id": null,
      "exchange_id": null,
      "movement_date": "2023-11-10",
      "source_name": "Person Name",
      "source_document_number": "67645727390",
      "source_document_type": "cpf",
      "source_id": "6a9045ac-1f24-4cd9-bc88-2547d52b88d3",
      "source_type": "TED-PRE",
      "source_description": "CREDITO POR TED ANTECIPADO",
      "source_bank": null,
      "source_branch": null,
      "source_account": null,
      "source_bank_ispb": null,
      "company_id": "company-uuid",
      "company_name": "Company Name"
    }
  }
}

Solution: Provide a valid transaction ID

HTTP Request

GET /transactions/:id/refund

For an already processed transaction

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

200OK

{
  "data": {
    "bank_transaction": {
      "currency": "USD",
      "estimated_value": "184.73",
      "estimated_value_until_exchange": true,
      "exchange_approved": false,
      "exchange_currency": "BRL",
      "exchange_id": null,
      "exchange_rate": null,
      "exchange_rate_spot": null,
      "exchanged_value": "1000",
      "id": "40ec25fa-59fd-4fac-a012-2091b16d34a3",
      "inserted_at": "2023-11-10T13:22:31.100380",
      "iof_value": null,
      "movement_date": "2023-11-10",
      "source_account": null,
      "source_bank": null,
      "source_branch": null,
      "source_description": "CREDITO POR TED ANTECIPADO",
      "source_document_number": "67645727390",
      "source_document_type": "cpf",
      "source_id": "6a9045ac-1f24-4cd9-bc88-2547d52b88d3",
      "source_name": "Person Name",
      "source_type": "TED-PRE",
      "spei_concepto_de_pago": null,
      "spei_reference": null,
      "value": "184.73",
      "wire_id": null
    },
    "cleared": true,
    "currency": "USD",
    "estimated_value_until_exchange": true,
    "exchange_currency": "BRL",
    "exchange_under_request": false,
    "exchanged_value": "1000",
    "for_exchange": true,
    "from_bank_account": {
      "aba": "000000016",
      "account_number": "000016",
      "account_type": "conta-corrente",
      "bank": {
        "code": "123",
        "id": "ae7f2a66-6c09-4356-bc47-a94c17852f46",
        "name": "Bank 123",
        "swift": null
      },
      "branch_country": "Brasil",
      "branch_number": "0016",
      "currency": "USD",
      "iban": "000000016",
      "id": "c44fe69d-3316-43f3-be8e-89975c35be3a",
      "intermediary_bank_account_id": null,
      "internal": true,
      "nickname": null,
      "owner_document_number": "12345678901",
      "owner_name": "Account owner name",
      "pix_info": {
        "key": "[email protected]",
        "type": "EMAIL"
      },
      "routing_number": null
    },
    "from_credit_card": null,
    "id": "6a9045ac-1f24-4cd9-bc88-2547d52b88d3",
    "inserted_at": "2023-11-10T13:22:31.078388",
    "meta": null,
    "source_document_number": "1111111111",
    "source_document_type": "cpf",
    "source_name": "Person Name",
    "status": "identified",
    "subject": {
      "address_city": "São Paulo",
      "address_complement": "Apt 20",
      "address_country": "Brasil",
      "address_neighborhood": "Bairro",
      "address_number": "999",
      "address_postal_code": "0000000",
      "address_state": "SP",
      "address_street": "Rua X",
      "birth_date": "1989-04-01",
      "clearance_level": 1,
      "document_number": "1111111111",
      "document_type": "cpf",
      "email": "[email protected]",
      "fiscal_country": "Brasil",
      "id": "b9235120-bebd-49ba-beb5-f173a7c16e97",
      "inserted_at": "2023-11-10T13:22:30.874817",
      "net_monthly_average_income": "4000.00",
      "phone_number": "+55 (18) 99854-9234",
      "references": [],
      "required_clearance_level": 1,
      "rfc_pf": null,
      "social_name": "Person Name",
      "status": "approved",
      "updated_at": "2023-11-10T13:22:31.026744"
    },
    "subject_id": "b9235120-bebd-49ba-beb5-f173a7c16e97",
    "subject_is_receiver": true,
    "to_bank_account": {
      "aba": null,
      "account_number": "28319-0",
      "account_type": "conta-corrente",
      "bank": {
        "code": "001",
        "id": "f9ccd2c3-a83c-4548-b9c9-0eb00e1fd436",
        "name": "Banco do Brasil S.A.",
        "swift": null
      },
      "branch_country": null,
      "branch_number": "2718",
      "currency": "BRL",
      "iban": null,
      "id": "18421642-ce13-4d7e-9cb8-64cf2beb362d",
      "intermediary_bank_account": null,
      "nickname": null,
      "owner_company": {
        "document_number": "67645727390",
        "document_type": "cpf",
        "id": "b9235120-bebd-49ba-beb5-f173a7c16e97",
        "social_name": "Person Name"
      },
      "owner_document_number": "67645727390",
      "owner_name": "Person Name",
      "pix_info": null,
      "routing_number": null
    },
    "value": "184.73"
  }
}

For an already processed transaction, you will pay using your cash-out account, as it already got in your internal cash-in account. It will work like a pay-out.

HTTP Request

GET /transactions/:id/refund_received_transaction

Listing refunded transactions

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

200OK

{
  "data": [
    {
      "transaction_kind": 2,
      "status": "wired",
      "reason": "Some reason for refund",
      "inserted_at": "2025-04-07T18:31:18.208487",
      "id": "3a6a9ca1-b7a1-40c1-b0cf-af0f733da7bd",
      "bank_transaction": {
        "wire_id": "39afb77b-5483-4934-b3b1-033e9d5cb785",
        "value": "10000.00",
        "spei_reference": null,
        "spei_concepto_de_pago": null,
        "source_type": "PIX",
        "source_name": "Company Ltda.",
        "source_id": null,
        "source_document_type": "cnpj",
        "source_document_number": "93535445000157",
        "source_description": "CREDITO POR TED",
        "source_branch": "5052",
        "source_bank_ispb": "23273917",
        "source_bank": null,
        "source_account": "1251058725246183",
        "movement_date": "2025-04-07",
        "iof_value": "0.00",
        "inserted_at": "2025-04-07T16:20:32.197678",
        "id": "1676ae9b-bc08-416f-ae2e-56d28f9a9e52",
        "exchanged_value": "10000.00",
        "exchange_rate_spot": null,
        "exchange_rate": "1.0",
        "exchange_id": "e5ba4a1a-6566-465d-8986-ab7e326a3830",
        "exchange_currency": "BRL",
        "exchange_approved": true,
        "currency": "BRL"
      }
    }
  ]
}

Query Parameters

Parameter	Description	Type	Required
`last_id`	Last transaction UUID for pagination	string	false
`per_page`	Number of elements to return per page	string	false

To check the transactions which were refunded, you can use this other endpoint:

HTTP Request

GET /bank_transactions/refunded

Reverse Exchange

This request will be made when you want to pay an exact value in the final currency. For example, you want to pay from your USD account to a Brazilian customer in BRL, so you can put the final value in BRL without worrying about the amount that will be funded in USD. Notice there is no value field, only the exchanged_value is present.

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",
    "exchanged_value": "500.00",
    "from_bank_account_id": "your USD cash-out id",
    "to_bank_account_id": "the customer´s account id",
    "subject_id": "Customer id"
  }
}'

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`transaction`	An object containing all the required values	object	true
`currency`	Currency from the internal account you would like to subtract	string	true
`exchange_currency`	Currency you would like to pay	string	true
`exchanged_value`	Value you would like to charge in the same currency as the `exchange_currency` field	string	true
`from_bank_account_id`	ID of the internal account the funds will come from, it must be in the same currency as the `currency` field	string	true
`to_bank_account_id`	ID of the physical/internal bank account that the funds will go to; must be in the same currency as the `exchange_currency` field	string	true
`subject_id`	ID of the person or company involved in the transaction	string	true

Non-wired Transactions

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

200OK

{
  "data": [
    {
      "wire_id": null,
      "value": "10000",
      "spei_reference": null,
      "spei_concepto_de_pago": null,
      "source_type": "TED",
      "source_name": "Gustavo Rodrigues Paludetto",
      "source_id": null,
      "source_document_type": "cpf",
      "source_document_number": "21958642819",
      "source_description": "CREDITO POR TED",
      "source_branch": "1142",
      "source_bank_ispb": null,
      "source_bank": "033",
      "source_account": "130013844",
      "movement_date": "2020-07-24",
      "iof_value": "0.00",
      "inserted_at": "2020-07-24T04:57:41.400266",
      "id": "41ffbab7-0caa-42cd-8bda-4835b0a6971c",
      "exchanged_value": "10000.00",
      "exchange_rate_spot": null,
      "exchange_rate": "1.0",
      "exchange_id": "7cedd106-6e54-4ff4-9af3-f0ec725fb83d",
      "exchange_currency": "BRL",
      "exchange_approved": true,
      "currency": "BRL"
    }
  ]
}

To check the transactions which were not wired yet, you can use this other endpoint.

HTTP Request

GET /transactions/not_wired

Transaction Limits

Webhook example:

{
  "notification": {
    "type": "subject_reproved",
    "subject_id": "UUID",
    "items": [
      "tax_declaration_required",
      "proof_of_address_missing"
    ],
    "secret": "some-secret"
  }
}

Once a customer reaches its limits, Attrus will send a webhook requesting that customer's Tax Declaration for raising this customer's limit. The transaction will stay on hold until the required info/documentation is sent and processed by our back-office staff. On the side there is an example of a webhook that is triggered if a customer needs to provide his/her Tax Decaration and a document proving his/her address is where he/she lives or has ownership (Proof of address).

Workflow for a transaction exceeding its limits

Listing Transactions and details

Request

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

200OK

{
  "data": [
    {
      "value": "1250.00",
      "to_bank_account_id": "c3d8b7e8-4022-4ce6-9d45-c4666ea53653",
      "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-09T19:25:27.114588",
      "id": "4835d070-2042-4e95-8771-48fd46d6fa6b",
      "from_credit_card": null,
      "from_bank_account_id": "a2474d90-eca9-47ac-90f2-0487d51b4bef",
      "for_exchange": true,
      "exchanged_value": "7280.90",
      "exchange_under_request": true,
      "exchange_currency": "BRL",
      "estimated_value_until_exchange": false,
      "currency": "USD",
      "cleared": true,
      "bank_transaction": {
        "wire_id": null,
        "value": "1250",
        "spei_reference": null,
        "spei_concepto_de_pago": null,
        "source_type": "WIRE",
        "source_name": "John Doe",
        "source_id": null,
        "source_document_type": "cpf",
        "source_document_number": "05069869183",
        "source_description": "CREDITO POR TED",
        "source_branch": "1142",
        "source_bank_ispb": null,
        "source_bank": "033",
        "source_account": "130013844",
        "movement_date": "2025-07-09",
        "iof_value": "28.05",
        "inserted_at": "2025-07-09T19:27:07.077907",
        "id": "7c7203c8-a1e3-4a7d-996f-600e80939c02",
        "exchanged_value": "7280.90",
        "exchange_rate_spot": "5.90600000",
        "exchange_rate": "5.82472",
        "exchange_id": "dd5e4988-66b3-457d-8024-fc3f094bb1fc",
        "exchange_currency": "BRL",
        "exchange_approved": false,
        "currency": "USD"
      }
    }
  ]
}

HTTP Request

GET /transactions

Note that the API can return the maximum of 100 in this list.

Example: You can use the query parameters, as: /transactions?last_id=a5c69e9e-8d84-4b0b-9af8-dcfb5be35093&per_page=1.

This will return the last transaction after the transaction with ID a5c69e9e-8d84-4b0b-9af8-dcfb5be35093.

Query Parameters

Parameter	Description	Type	Required
`last_id`	Last transaction UUID for pagination	`string`	false
`per_page`	Number of elements per page	`string`	false
`id`	Transaction UUID	`string`	false
`from`	Filter from date/time, e.g.: 2022-05-01T03%3A00%3A00.000Z	`iso datetime`	false
`to`	Filter to date/time, e.g.: 2022-05-30T03%3A00%3A00.000Z	`iso datetime`	false
`status`	Transaction status	`string`	false
`currency`	Filter to match only the selected currency	`string`	false
`exchange_currency`	Filter to match only the selected currency as exchanged	`string`	false
`subject_id`	Filter by subject UUID	`string`	false

Transaction Details

Returns a single transaction details.

HTTP Request

GET /transactions/:id

Path Parameters

Parameter	Description	Type	Required
`id`	Transaction UUID	string	true

Listing Bank Transfers (Wires)

Return the bank transfers list.

Example: You can use the path parameters, as: /wires?last_id=a5c69e9e-8d84-4b0b-9af8-dcfb5be35093&per_page=1.

This will return the last wire after the transaction with ID a5c69e9e-8d84-4b0b-9af8-dcfb5be35093.

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

200OK

{
  "data": [
    {
      "value": "574.84",
      "unretryable": null,
      "to_bank_account": {
        "routing_number": null,
        "pix_info": null,
        "owner_name": "André Freitas Lopes",
        "owner_document_type": null,
        "owner_document_number": "01472583691",
        "nickname": null,
        "intermediary_bank_account": null,
        "id": "102518ca-5d8a-443f-b131-e47d99bc4d0d",
        "iban": null,
        "currency": "BRL",
        "company": {
          "social_name": "John Doe",
          "phone_number": "99812-1212",
          "id": "01e0725b-b4f5-46b1-811a-a3cbcb314d10",
          "fiscal_country": "BR",
          "document_type": "cpf",
          "document_number": "05069869183",
          "company_name": "Company & CIA"
        },
        "branch_number": "0031",
        "branch_country": "BR",
        "bank": {
          "swift": null,
          "name": "Código Banco Beg S.A.",
          "ispb": null,
          "id": "f9dcd833-a4a8-4595-8f5a-b63b0a98292d",
          "country": "BRA",
          "code": "031"
        },
        "account_type": "conta-corrente",
        "account_number": "85296",
        "aba": null
      },
      "status": "success",
      "inserted_at": "2025-02-05T16:25:07.062903",
      "id": "e027fc20-42d0-4da6-92d8-60893509b531",
      "currency": "BRL"
    }
  ]
}

HTTP Request

GET /wires

Query Parameters

Parameter	Description	Type	Required
`last_id`	Last transaction UUID for pagination	`string`	false
`per_page`	Number of elements per page	`string`	false
`pending`	Filter only transactions that are pending	`boolean`	false
`from`	Filter from date/time, e.g.: `2022-05-01T03%3A00%3A00.000Z`	`iso datetime`	false
`to`	Filter to date/time, e.g.: `2022-05-30T03%3A00%3A00.000Z`	`iso datetime`	false
`company_id`	Filter by partner (company) UUID	`string`	false
`subject_id`	Filter by subject UUID	`string`	false
`transaction_type`	Filter by transaction type automatic or manual	`string`	false
`currency`	Filter to match only the selected currency	`string`	false

Wire Details

Returns the bank transfer details.

HTTP Request

GET /wires/:id

Path Parameters

Parameter	Description	Type	Required
`id`	Wire UUID	`string`	true

Transactions in a Wire

Returns the transactions associated to a specific bank transfer (wire).

HTTP Request

GET /wires/:id/transactions

Path Parameters

Parameter	Description	Type	Required
`id`	Wire UUID	`string`	true

Making transactions​

Bank Account IDs​

HTTP Request​

Example 1: Pay-In - BRL to USD​

Example 2: Pay-Out - USD to BRL​

Transaction List​

Query Parameters​

Transaction Details​

HTTP Request​

Path Parameters​

Transaction Status​

Pay-In Transaction Status​

Pay-Out Transaction Status​

Exchange/Conversion Transaction Status​

Settlement Transaction Status​

Getting Exchange Rates (FX)​

HTTP Request​

Conversion between Internal Accounts​

Example 3: Conversion/transfers between Internal Accounts​

Body Parameters​

Settlements and Deposit/Pre-funding​

Example of a Settlement Transaction​

Example 4: Making transfers between accounts in USD​

Body Parameters​

Calculation of Exchange Rates​

HTTP Request​

Body Parameters​

Refund Transactions​

Example refunding a non-processed transaction​

HTTP Request​

For an already processed transaction​

HTTP Request​

Listing refunded transactions​

Query Parameters​

HTTP Request​

Reverse Exchange​

HTTP Request​

Body Parameters​

Non-wired Transactions​

HTTP Request​

Transaction Limits​

Listing Transactions and details​

HTTP Request​

Query Parameters​

Transaction Details​

HTTP Request​

Path Parameters​

Listing Bank Transfers (Wires)​

HTTP Request​

Query Parameters​

Wire Details​

HTTP Request​

Path Parameters​

Transactions in a Wire​

HTTP Request​

Path Parameters​

Making transactions

Bank Account IDs

HTTP Request

Example 1: Pay-In - BRL to USD

Example 2: Pay-Out - USD to BRL

Transaction List

Query Parameters

Transaction Details

HTTP Request

Path Parameters

Transaction Status

Pay-In Transaction Status

Pay-Out Transaction Status

Exchange/Conversion Transaction Status

Settlement Transaction Status

Getting Exchange Rates (FX)

HTTP Request

Conversion between Internal Accounts

Example 3: Conversion/transfers between Internal Accounts

Body Parameters

Settlements and Deposit/Pre-funding

Example of a Settlement Transaction

Example 4: Making transfers between accounts in USD

Body Parameters

Calculation of Exchange Rates

HTTP Request

Body Parameters

Refund Transactions

Example refunding a non-processed transaction

HTTP Request

For an already processed transaction

HTTP Request

Listing refunded transactions

Query Parameters

HTTP Request

Reverse Exchange

HTTP Request

Body Parameters

Non-wired Transactions

HTTP Request

Transaction Limits

Listing Transactions and details

HTTP Request

Query Parameters

Transaction Details

HTTP Request

Path Parameters

Listing Bank Transfers (Wires)

HTTP Request

Query Parameters

Wire Details

HTTP Request

Path Parameters

Transactions in a Wire

HTTP Request

Path Parameters