UnblockPayGuideReference

External Accounts

Understading External AccountsCopied!

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 endpointsCopied!

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?Copied!

Step 1: Create an External AccountCopied!

POST /customers/{customer_id}/external-accounts

This endpoint creates a new External Account linked to a customer's bank account.

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

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

© 2025 UnblockPay