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/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.

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

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "account_name": "Conta Principal PIX",
    "payment_rail": "pix",
    "pix": {
      "key": "joao.silva@example.com"
    }
  }'

Response example:

{
  "id": "c1d2e3f4-0000-7000-8000-aabbccddeeff",
  "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
  "account_name": "Conta Principal PIX",
  "payment_rail": "pix",
  "status": "approved",
  "is_third_party": false,
  "pix": {
    "key": "joao.silva@example.com",
    "bank_name": "Banco Itaú S.A.",
    "beneficiary_name": "João Silva"
  },
  "created_at": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-15T14:30:00Z"
}

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.

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "account_name": "Conta Bancária PIX",
    "payment_rail": "pix_account",
    "pix_account": {
      "bank_code": "60701190",
      "branch_code": "0001",
      "bank_account_number": "123456",
      "account_type": "checking",
      "beneficiary_document": "123.456.789-00",
      "beneficiary_name": "João Silva"
    }
  }'

Response example:

{
  "id": "c1d2e3f4-0000-7000-8000-aabbccddeeff",
  "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
  "account_name": "Conta Bancária PIX",
  "payment_rail": "pix_account",
  "status": "approved",
  "is_third_party": false,
  "pix_account": {
    "bank_code": "60701190",
    "branch_code": "0001",
    "bank_account_number": "123456",
    "account_type": "checking",
    "beneficiary_document": "123.456.789-00",
    "beneficiary_name": "João Silva"
  },
  "created_at": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-15T14:30:00Z"
}

🇲🇽 External Account in Mexico

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

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "account_name": "Satoshi Account in Mexico",
    "payment_rail": "spei",
    "spei": {
      "beneficiary_name": "Satoshi Nakamoto",
      "protocol": "clabe",
      "bank_code": "40012",
      "clabe": "012180001977647665",
      "bank_name": "BBVA México"
    }
  }'

Response example:

{
  "id": "c1d2e3f4-0000-7000-8000-aabbccddeeff",
  "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
  "account_name": "Satoshi Account in Mexico",
  "payment_rail": "spei",
  "status": "approved",
  "is_third_party": false,
  "spei": {
    "beneficiary_name": "Satoshi Nakamoto",
    "protocol": "clabe",
    "bank_code": "40012",
    "clabe": "012180001977647665",
    "bank_name": "BBVA México"
  },
  "created_at": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-15T14:30:00Z"
}

🇺🇸 External Account in the United States

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

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "account_name": "Satoshi US Account",
    "payment_rail": "wire",
    "wire": {
      "beneficiary_name": "Satoshi Nakamoto",
      "beneficiary_type": "individual",
      "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"
      }
    }
  }'

Response example:

{
  "id": "c1d2e3f4-0000-7000-8000-aabbccddeeff",
  "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
  "account_name": "Satoshi US Account",
  "payment_rail": "wire",
  "status": "approved",
  "is_third_party": false,
  "wire": {
    "beneficiary_name": "Satoshi Nakamoto",
    "beneficiary_type": "individual",
    "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": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-15T14:30:00Z"
}

🇪🇺 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):

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "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):

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "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

For CVU, provide exactly one of cvu.cvu or cvu.cbu — they are mutually exclusive.

curl https://api.sandbox.unblockpay.com/v1/external-accounts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
    "account_name": "Satoshi Account in Argentina",
    "payment_rail": "cvu",
    "cvu": {
      "beneficiary_name": "Satoshi Nakamoto",
      "cvu": "0000003100012345678901"
    }
  }'

How to list External Accounts

GET /v1/external-accounts

Returns a paginated list of all external accounts associated with the authenticated partner. Use limit, after, and before to paginate through results. Use customer_id to filter accounts belonging to a specific customer. Use start_date and end_date to filter by creation date.

Note: The shape of each result varies by payment_rail.

curl 'https://api.sandbox.unblockpay.com/v1/external-accounts?limit=20&amp;after=eyJw...' \
  --header 'Authorization: YOUR_SECRET_TOKEN'

Response — 200 OK:

{
  "items": [
    {
      "id": "c1d2e3f4-0000-7000-8000-aabbccddeeff",
      "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
      "account_name": "Conta Principal PIX",
      "created_at": "2024-03-15T14:30:00Z",
      "updated_at": "2024-03-15T14:30:00Z",
      "status": "approved",
      "is_third_party": false,
      "payment_rail": "pix",
      "pix": {
        "key": "joao.silva@example.com",
        "bank_name": "Banco Itaú S.A.",
        "beneficiary_name": "João Silva"
      }
    }
  ],
  "cursor": {
    "after": "eyJwYXJhbXMiOiJ7ImxpbWl0IjoyMH19...",
    "before": null,
    "limit": 20,
    "page_count": 2
  }
}

How to get an External Account

GET /v1/external-accounts/{id}

curl https://api.sandbox.unblockpay.com/v1/external-accounts/c1d2e3f4-0000-7000-8000-aabbccddeeff \
  --header 'Authorization: YOUR_SECRET_TOKEN'

Response — 200 OK:

{
  "id": "c1d2e3f4-0000-7000-8000-aabbccddeeff",
  "customer_id": "019d7904-ec72-7754-b5f5-443defb20da0",
  "account_name": "Conta Principal PIX",
  "created_at": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-15T14:30:00Z",
  "status": "approved",
  "is_third_party": false,
  "payment_rail": "pix",
  "pix": {
    "key": "joao.silva@example.com",
    "bank_name": "Banco Itaú S.A.",
    "beneficiary_name": "João Silva"
  }
}

External Accounts API endpoints

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

Method	Endpoint	Description
`POST`	`/v1/external-accounts`	Create a new external account
`GET`	`/v1/external-accounts`	List all external accounts
`GET`	`/v1/external-accounts/{id}`	Get details for a specific external account

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

Wallets

Virtual accounts