Quick Start

Start building with UnblockPay API and make your first transaction

1️⃣ Getting your API Keys

API keys are generated through our dashboard.

To get access, contact our team at dev@unblockpay.com. You'll receive credentials to log into the dashboard, where you can generate your API keys.

Sandbox access is available immediately after receiving your credentials. Production access requires approval from our team.

2️⃣ Understanding your environments

UnblockPay has two environments.

Sandbox

Start with our sandbox environment for testing:

https://api.sandbox.unblockpay.com

Sandbox environment is fully simulated. Transactions are not processed on real networks. All data, balances, and statuses are mocked. Do not send real money to sandbox wallet addresses or bank accounts. Any funds sent will be permanently lost and cannot be recovered.

For mocked transaction states and webhooks, please visit our Sandbox mocks section.

Production

https://api.unblockpay.com

3️⃣ Onboarding your first customer

You're now ready to start using our APIs.

The first step is to create a Customer object to represent a user in your system.

Here's how to create a Customer object for an individual:

curl https://api.sandbox.unblockpay.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "type": "individual",
    "first_name": "Satoshi",
    "last_name": "Nakamoto",
    "email": "satoshi@email.com",
    "phone_number": "1234567890",
    "date_of_birth": "1990-01-01",
    "tin": "12345678900",
    "country": "BRA",
    "address": {
      "street_line_1": "123 Main St",
      "street_line_2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "USA"
    }
  }'

Here's the response format:

{
  "id": "0196c8cd-839a-7389-b5ce-0a0776023e55",
  "type": "individual",
  "status": "pending",
  "first_name": "Satoshi",
  "last_name": "Nakamoto",
  "email": "satoshi@email.com",
  "phone_number": "1234567890",
  "date_of_birth": "1990-01-01",
  "tin": "12345678900",
  "country": "BRA",
  "address": {
    "street_line_1": "123 Main St",
    "street_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "USA"
  },
  "partner_id": "partner_123",
  "verification": {
    "verification_link": "https://sumsub.com/...",
    "verification_type": "LIGHT"
  },
  "created_at": "2025-05-13T08:40:33.946Z",
  "updated_at": "2025-05-13T08:40:33.946Z"
}

When you create a customer, their initial status is pending and the response includes a verification_link. This link is generated because every customer must be identity-verified before they can transact.

Share this link with your customer. They can open it on desktop or mobile and complete the verification themselves by uploading the required documents and photos. Once submitted, the status moves to under_review and then to approved when verified.

We recommend this hosted flow. Alternatively, you can submit KYC documents directly via API. For more details on both flows, see the Customers section.

4️⃣ Registering your customer's external bank account

Next, create an External Account object that represents the bank account where your customer will receive their fiat funds. External Accounts can be either first-party or third-party bank accounts.

For this example, we'll create an External Account for a bank account in Brazil. You'll need to provide the account_name, payment_rail, and pix_key.

curl https://api.sandbox.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"
}'

Here's the response example:

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

Now that you've created an External Account, let's initiate a payout from USDC to BRL.

5️⃣ Moving USDC directly to a bank account in Brazil via Pix

First, create a quote to lock in the exchange rate:

curl https://api.sandbox.unblockpay.com/quote \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "symbol": "USDC/BRL"
}'

You will receive a response like:

{
  "id": "0a411450-013f-11f0-9a14-5b6e00793f09",
  "quotation": "5.7494",
  "symbol": "USDC/BRL",
  "expires_at": 1742003371
}

Second, use the quote ID to create a payout, along with amount, sender, and receiver information.

curl https://api.sandbox.unblockpay.com/payout \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "amount": 5,
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "sender": {
    "currency": "USDC",
    "payment_rail": "solana",
    "address": "3fFnisw8zsFhyQopBH1hLLshJEPs8tCysESSLTvTGjWk"
  },
  "receiver": {
    "external_account_id": "b11f8920-ece3-11ef-8e88-2d5fe9bab89b"
  }
}'

After initiating the payout, you'll receive a response with the transaction details and deposit instructions for the stablecoins.

{
  "id": "c6003140-040e-11f0-975f-5db311bbdd36",
  "status": "awaiting_deposit",
  "type": "off_ramp",
  "partner_id": "b30578dc-20a4-4332-9eac-4643dc4ebbf0",
  "quotation": "5.6689",
  "sender_deposit_instructions": {
    "amount": 5,
    "currency": "USDC",
    "payment_rail": "solana",
    "deposit_address": "7PWWVJ3qLTacd4ucxpKXyfoZt39thmbzrnKqA9NnoGn5"
  },
  "sender": {
    "currency": "USDC",
    "payment_rail": "solana",
    "address": "GvjfJUVea4fEyprqsDUaAvbJ6riFcgoh2v8qqjLJbJU5"
  },
  "receiver": {
    "amount": 28.34,
    "currency": "BRL",
    "payment_rail": "pix",
    "pix_key": "12311112312",
    "pix_key_type": "CPF",
    "pix_end_to_end_id": "E3513612020250217162700000888283",
    "bank_account": {
      "bank_name": "TESTE BANCO S.A",
      "bank_code": null,
      "bank_account_number": null,
      "beneficiary": {
        "document": "12311112312",
        "name": "Testando Teste"
      }
    }
  },
  "receipt": {
    "initial_crypto_amount": 5,
    "final_fiat_amount": 28.34,
    "unblockpay_fee": 0.15
  },
  "created_at": "2025-03-18T15:36:34.644Z",
  "updated_at": "2025-03-18T15:36:34.644Z",
  "finished_at": null
}

Upon successful deposit, the fiat payout will be processed and the receiver will get the funds in their bank account.

Sandbox environment is fully simulated. Transactions are not processed on real networks – all data, balances, and statuses are mocked. Do not send real money to sandbox wallet addresses or bank accounts. Any funds sent will be permanently lost and cannot be recovered.

For more information about Payouts, please visit our Stablecoin to Fiat (Payout) section.

Welcome to UnblockPay

Authentication