External Accounts

Understading External Accounts

An External Account represent a bank account not managed by UnblockPay where a customer can receive fiat funds. It is the destination for payout transactions — the bank account where UnblockPay sends fiat money after converting stablecoins.

External Accounts are tied to a customer and must be registered before initiating a payout (except for Pix in Brazil, where you can pass the pix_key and document directly in the payout request).

External Accounts can be first-party or third-party. Use the is_third_party field to indicate when the bank account belongs to someone other than the customer. For example, a customer named "Nick" can register a bank account belonging to "Satoshi" by setting is_third_party: true.

Supported payment rails

UnblockPay supports the following rails for External Accounts:

Rail	Country / Region	Notes
`pix`	🇧🇷 Brazil	Via Pix key (CPF, CNPJ, email, phone, or random key)
`pix_account`	🇧🇷 Brazil	Via full bank account details, when a Pix key is unavailable
`spei`	🇲🇽 Mexico	Via CLABE, debit card, or phone number
`wire`	🇺🇸 United States	Via routing number and bank account number
`sepa`	🇪🇺 Europe (SEPA zone)	Via IBAN and BIC
`cvu`	🇦🇷 Argentina	Via CVU or CBU

How to create an External Account

POST v1/customers/{customer_id}/external-accounts

This endpoint registers a new External Account linked to a customer. Each request must include the account_name, the payment_rail, and the corresponding rail-specific object (e.g. pix, wire, sepa).

You can also include is_third_party: true when the bank account belongs to someone other than the customer.

🇧🇷 External Account in Brazil

UnblockPay supports two Pix methods for Brazilian accounts: a Pix key (simpler, recommended for most cases) and a full bank account via pix_account (for cases where a Pix key is not available).

Via Pix key

Here's a request example:

curl https://api.unblockpay.com/v1/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": "satoshi@email.com"
    }
  }'

Here's a response example:

{
   "id": "bfc36f00-ed1f-11ef-9fe4-378e29e1083a",
   "account_name": "Satoshi Bank Account in Brazil",
   "payment_rail": "pix",
   "pix": {
       "key": "satoshi@email.com"
   },
   "created_at": "2025-05-13T08:40:33.946Z",
   "updated_at": "2025-05-13T12:26:53.405Z"
}

Via full bank account (pix_account)

Use this method when a Pix key is unavailable and you need to register the full bank account details.

Here's a request example:

bash

curl https://api.unblockpay.com/v1/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_account",
    "pix_account": {
      "bank_code": "60701190",
      "branch_code": "0001",
      "bank_account_number": "123456",
      "account_type": "checking",
      "beneficiary_document": "12345678900",
      "beneficiary_name": "Satoshi Nakamoto"
    }
  }'

🇲🇽 External Account in Mexico

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

curl https://api.unblockpay.com/v1/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",
    "spei": {
      "beneficiary_name": "Satoshi Nakamoto",
      "protocol": "clabe",
      "bank_code": "012",
      "clabe": "012180001977647665"
    }
  }'

Here is a response example:

{
    "id": "0d045280-ed3f-12ef-80a0-99ef27c9f123",
    "account_name": "Satoshi Account in Mexico",
    "payment_rail": "spei",
    "spei": {
        "beneficiary_name": "Satoshi Nakamoto",
        "protocol": "clabe",
        "bank_code": "012",
        "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/v1/customers/{customer_id}/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "account_name": "Satoshi US Account",
    "payment_rail": "wire",
    "wire": {
      "beneficiary_type": "individual",
      "beneficiary_name": "Satoshi Nakamoto",
      "bank_name": "Community Federal Savings Bank",
      "bank_account_number": "652112475791",
      "routing_number": "026073008",
      "beneficiary_address": {
        "street_line_1": "8916 Jamaica Ave",
        "city": "Woodhaven",
        "state": "NY",
        "postal_code": "11421",
        "country": "USA"
      }
    }
  }'

Here is a response example:

{
    "id": "0d045280-ed3f-12ef-80a0-99ef27c9f123",
    "account_name": "Satoshi US Account",
    "payment_rail": "wire",
    "wire": {
        "beneficiary_type": "individual",
        "beneficiary_name": "Satoshi Nakamoto",
        "bank_name": "Community Federal Savings Bank",
        "bank_account_number": "652112475791",
        "routing_number": "026073008",
        "beneficiary_address": {
            "street_line_1": "8916 Jamaica Ave",
            "city": "Woodhaven",
            "state": "NY",
            "postal_code": "11421",
            "country": "USA"
        }
    },
    "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",
    "payment_rail": "sepa",
    "sepa": {
        "beneficiary_type": "individual",
        "beneficiary_name": "Satoshi Nakamoto",
        "bank_name": "Euro Bank",
        "iban": "ES9121000418450200012345",
        "bic": "BSCHESMM123",
        "country": "ESP",
        "beneficiary_address": {
            "street_line_1": "Calle Gran Via, 1",
            "city": "Madrid",
            "state": "Madrid",
            "postal_code": "28013",
            "country": "ESP"
        }
    }
}

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",
    "payment_rail": "sepa",
    "sepa": {
        "beneficiary_type": "business",
        "beneficiary_name": "Satoshi Company S.L.",
        "bank_name": "Euro Bank",
        "iban": "ES9121000418450200012345",
        "bic": "BSCHESMM123",
        "country": "ESP",
        "beneficiary_address": {
            "street_line_1": "Calle Gran Via, 1",
            "city": "Madrid",
            "state": "Madrid",
            "postal_code": "28013",
            "country": "ESP"
        }
    }
}

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

🇦🇷 External Account in Argentina

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

{
    "account_name": "Satoshi Account in Argentina",
    "payment_rail": "cvu",
    "cvu": {
        "beneficiary_name": "Satoshi Nakamoto",
        "cvu": "0000003100012345678901"
    }
}

External Accounts API endpoints

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

POST /v1/customers/{customer_id}/external-accounts — Create a new external account
GET /v1/customers/{customer_id}/external-accounts — List all external accounts for a customer
GET /v1/customers/{customer_id}/external-accounts/{id} — Get details for a specific external account

For the full schema and request/response details, see the API Reference.

Wallets

Fiat to Stablecoin (Pay-in)