BlindPay Integration

Overview

BlindPay is a global payment infrastructure that enables worldwide money transfers using both traditional fiat currencies and stablecoins.

Key Capabilities:

Important: BlindPay is non-custodial. Funds remain under user control throughout the process. Failed transactions are automatically returned to the originating wallet.

Quick Start

Authentication

All API calls require:

• API Key: Passed as Authorization: Bearer YOUR_API_KEY
• Instance ID: Included in the URL path

curl --request GET \
  --url https://api.blindpay.com/v1/instances/in_000000000000/receivers \
  --header 'Authorization: Bearer YOUR_API_KEY'

Payout Flow (Stablecoin → Fiat)

1. Accept Terms of Service → Get tos_id
2. Create Receiver → KYC verification, get receiver_id
3. Add Bank Account → Get bank_account_id
4. Create Payout Quote → Get quote_id (valid for 5 minutes)
5. Approve Tokens → ERC20 approval for BlindPay contract
6. Execute Payout → Stablecoins collected, fiat sent to bank

See references/getting-started/stable-to-fiat.md for complete guide.

Payin Flow (Fiat → Stablecoin)

1. Accept Terms of Service → Get tos_id
2. Create Receiver → KYC verification, get receiver_id
3. Add Blockchain Wallet → Get blockchain_wallet_id
4. Create Payin Quote → Get payin_quote_id (valid for 5 minutes)
5. Execute Payin → Get payment instructions (PIX code, CLABE, etc.)
6. Send Fiat → Once received, stablecoins sent to wallet

See references/getting-started/fiat-to-stable.md for complete guide.

Payment Rails

Supported Networks

Development vs Production

Testing Scenarios

Use first name "Fail" when creating receivers to simulate KYC rejection.

Error Handling

Always check API responses for errors:

{
  "error": {
    "message": "please_accept_terms_of_service",
    "code": "TERMS_NOT_ACCEPTED"
  }
}

Common errors:

• please_accept_terms_of_service - Receiver needs to accept updated TOS
• quote_expired - Quote older than 5 minutes, create a new one
• insufficient_balance - Wallet doesn't have enough tokens
• kyc_not_approved - Receiver KYC still pending or rejected

Reference Documentation

Getting Started

• Overview - What is BlindPay
• Stable to Fiat - Payout quick start
• Fiat to Stable - Payin quick start

Essentials

• Instances - Dev vs production environments
• Terms of Service - TOS acceptance flow
• Receivers - KYC/KYB for individuals and businesses
• Bank Accounts - ACH, Wire, PIX, SPEI, SWIFT
• Virtual Accounts - US bank account generation
• Blockchain Wallets - External wallet management
• Offramp Wallets - Auto-convert stablecoins
• Payout Quotes - Quote creation for payouts
• Payouts - Executing stablecoin → fiat transfers
• Payin Quotes - Quote creation for payins
• Payins - Executing fiat → stablecoin transfers
• API Keys - Authentication setup
• Webhooks - Real-time event notifications
• Partner Fees - Revenue sharing configuration
• Upload - Secure file uploads for KYC

Guides

• Smart Contracts - Contract addresses
• Cut-off Times - Processing windows
• Supported Countries - Country and payment rail coverage
• Prohibited Activities - Compliance requirements
• Payout Descriptor - Bank statement display names
• KYC Best Practices - Document submission tips
• On Hold Transactions - Handling flagged transactions
• SWIFT Deliverability - International transfer requirements