GuideAPI Reference

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

🇪🇺 External Account in Europe (SEPA Countries)

Individual Bank Account

Here's a request example for creating an External Account for an individual in the Single Euro Payments Area (SEPA):

{
    "account_name": "Individual Europe Account",
    "type": "individual",
    "payment_rail": "sepa",
    "bank_name": "Euro Bank",
    "iban": "ES9121000418450200012345",
    "bic": "BSCHESMM123",
    "sepa_country": "ESP",
    "first_name": "Satoshi",
    "last_name": "Nakamoto",
}

Business Bank Account

Here's a request example for creating an External Account for a business in the Single Euro Payments Area (SEPA):

{
    "account_name": "Business Europe Account",
    "type": "business",
    "payment_rail": "sepa",
    "bank_name": "Euro Bank",
    "iban": "ES9121000418450200012345",
    "bic": "BSCHESMM123",
    "sepa_country": "ESP",
    "business_legal_name": "Satoshi Company"
}

Here's a response example for creating an External Account in the Single Euro Payments Area (SEPA):

{
    "id": "0d045280-ed3f-12ef-80a0-99ef27c9f123",
    "account_name": "Individual Europe Account",
    "type": "individual",
    "payment_rail": "sepa",
    "bank_name": "Euro Bank",
    "iban": "ES9121000418450200012345",
    "bic": "BSCHESMM123",
    "sepa_country": "ESP",
    "first_name": "Satoshi",
    "last_name": "Nakamoto",
    "created_at": "2025-05-13T08:40:33.946Z",
    "updated_at": "2025-05-13T12:26:53.405Z"
}

SEPA Countries List:

Country

Code

🇦🇩 Andorra

AND

🇦🇹 Austria

AUT

🇧🇪 Belgium

BEL

🇧🇬 Bulgaria

BGR

🇭🇷 Croatia

HRV

🇨🇾 Cyprus

CYP

🇨🇿 Czechia

CZE

🇩🇰 Denmark

DNK

🇪🇪 Estonia

EST

🇫🇮 Finland

FIN

🇫🇷 France

FRA

🇩🇪 Germany

DEU

🇬🇷 Greece

GRC

🇭🇺 Hungary

HUN

🇮🇸 Iceland

ISL

🇮🇪 Ireland

IRL

🇮🇹 Italy

ITA

🇱🇻 Latvia

LVA

🇱🇮 Liechtenstein

LIE

🇱🇹 Lithuania

LTU

🇱🇺 Luxembourg

LUX

🇲🇹 Malta

MLT

🇲🇨 Monaco

MCO

🇳🇱 Netherlands

NLD

🇳🇴 Norway

NOR

🇵🇱 Poland

POL

🇵🇹 Portugal

PRT

🇷🇴 Romania

ROU

🇸🇲 San Marino

SMR

🇸🇰 Slovakia

SVK

🇸🇮 Slovenia

SVN

🇪🇸 Spain

ESP

🇸🇪 Sweden

SWE

🇨🇭 Switzerland

CHE

🇬🇧 United Kingdom

GBR

🇻🇦 Vatican City

VAT
© 2025 UnblockPay