GuideReference

External Accounts

Understading External Accounts

External Accounts represent bank accounts not managed by UnblockPay where customers can send their fiat funds. These bank accounts are the destinations to which UnblockPay transfers fiat money.

External Accounts can be either first-party or third-party bank accounts. For example, a customer named "Nick" can add an External Account belonging to "Satoshi".

For sending money through Pix, creating an External Account is not mandatory. You can simply pass the pix_key on the payout request.

For all other fiat currencies, you must create an External Account before initiating payout.

For example, when a customer wants to send USDCs to a bank account in Mexico, they must first register that account through our External Accounts endpoint. After registration, they simply include the External Account ID when initiating a payout.

External Accounts API endpoints

Here are the endpoints you'll need to create or list an External Account

  • POST /customers/{customer_id}/external-accounts: Create a new external account

  • GET /customers/{customer_id}/external-accounts: List all external accounts from one customer

  • GET /customers/{customer_id}/external-accounts/{id}: Get specific details for one external account

How to create an External Account?

POST /customers/{customer_id}/external-accounts

This endpoint creates a new External Account linked to a customer's bank account. You can create External Accounts in Brazil, Mexico, USA and Europe.

🇧🇷 External Account in Brazil

Here's a request example for creating an External Account in Brazil:

curl https://api.unblockpay.com/customers/{customer_id}/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "account_name": "Satoshi Bank Account in Brazil",
    "payment_rail": "pix",
    "pix_key": "sathosi@email.com",
    "document": "12345678900"
}

Here is a response example for an External Account in Brazil:

{
  "id": "bfc36f00-ed1f-11ef-9fe4-378e29e1083"
  "account_name": "Satoshi Bank Account in Brazil",
  "payment_rail": "pix",
  "pix_key": "sathosi@email.com",
  "bank_name": "Bank XYZ",
  "beneficiary_name": "Satoshi Nakamoto",
  "created_at": "2025-05-13T08:40:33.946Z",
  "updated_at": "2025-05-13T12:26:53.405Z"
}

🇲🇽 External Account in Mexico

Here's a request example for creating an External Account in Mexico:

curl https://api.unblockpay.com/customers/{customer_id}/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "account_name": "Satoshi Account in Mexico",
    "payment_rail": "spei",
    "beneficiary_name": "Satoshi Nakamoto",
    "spei_bank_code": "012",
    "spei_protocol": "clabe",
    "spei_clabe": "012180001977647665"
}'

Here is a response example for an External Account in Mexico:

{
    "id": "0d045280-ed3f-12ef-80a0-99ef27c9f123",
    "account_name": "Satoshi Account in Mexico",
    "payment_rail": "spei",
    "beneficiary_name": "Satoshi Nakamoto",
    "spei_bank_code": "012",
    "spei_protocol": "clabe",
    "spei_clabe": "012180001977647665",
    "created_at": "2025-05-13T08:40:33.946Z",
    "updated_at": "2025-05-13T12:26:53.405Z"
}'

🇺🇸 External Account in the United States

Here's a request example for creating an External Account in the United States:

curl https://api.unblockpay.com/customers/{customer_id}/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "account_name": "Conta Pedro Nomad Local",
    "type": "individual",
    "payment_rail": "wire",
    "beneficiary_name": "Pedro Henrique Braz Campo",
    "routing_number": "026073008",
    "bank_name": "Commmunity Federal Savings Bank",
    "bank_account_number": "652112475791",
    "address": {
        "street_line_1": "8916 Jamaica Ave",
        "city": "Woodhaven",
        "state": "NY",
        "postal_code": "11421",
        "country": "US"
    }
}

Here is a response example for an External Account in the United States:

{
    "id": "0d045280-ed3f-12ef-80a0-99ef27c9f123",    
    "account_name": "Conta Pedro Nomad Local",
    "type": "individual",
    "payment_rail": "wire",
    "beneficiary_name": "Pedro Henrique Braz Campo",
    "routing_number": "026073008",
    "bank_name": "Commmunity Federal Savings Bank",
    "bank_account_number": "652112475791",
    "address": {
        "street_line_1": "8916 Jamaica Ave",
        "city": "Woodhaven",
        "state": "NY",
        "postal_code": "11421",
        "country": "US"
    }
    "created_at": "2025-05-13T08:40:33.946Z",
    "updated_at": "2025-05-13T12:26:53.405Z"
}
© 2025 UnblockPay