GuideReference

Quick Start

Start building with UnblockPay API and make your first transaction

Step 1: Get your API Keys

Before you begin, you'll need API keys to authenticate your requests.

Contact our team to receive:

  • Your API keys

  • The complete Postman collection for testing our API

Step 2: Setting up your environment

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.

Step 3: Onboard 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/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "first_name": "Satoshi",
  "last_name": "Nakamoto",
  "email": "satoshi@email.com",
  "phone": "1234567890",
  "type": "individual",
  "date_of_birth": "1990-01-01",
  "identity_documents": [
    {
      "type": "national_id",
      "value": "11111111111",
      "country": "BR"
    }
  ],
  "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",
  "status": "approved",
  "first_name": "Satoshi",
  "last_name": "Nakamoto",
  "email": "satoshi@email.com",
  "phone": "1234567890",
  "type": "individual",
  "date_of_birth": "1990-01-01",
  "identity_documents": [
    {
      "type": "national_id",
      "value": "12345678900",
      "country": "BR"
    }
  ],
  "address": {
    "street_line_1": "123 Main St",
    "street_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "USA"
  }
  "created_at": "2025-05-13T08:40:33.946Z",
  "updated_at": "2025-05-13T12:26:53.405Z"
}

When you create a customer, UnblockPay handles all KYC verification and returns a status field indicating their KYC status. Note that in the sandbox environment, customers will always have an approved status.

Step 4: Register your customer's 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.

Step 5: Move 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.

© 2025 UnblockPay