Quick Start

Start building with UnblockPay API and make your first transaction

Step 1: Get your API KeysCopied!

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

Start with our sandbox environment for testing:

https://api.sandbox.unblockpay.com

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

Step 3: Onboard your first customerCopied!

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

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

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.

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

Congratulations! You've successfully completed your first stablecoin-to-fiat payout. Explore our additional guides to deepen your understanding about our API.