# API Integration Guide Complete step-by-step instructions for accepting crypto payments, verifying customers, and sending payouts. `Version 1.0` · Last updated March 2026 · API `v1` · Partner Documentation --- ## Contents ### 🔧 [Getting Started →](#getting-started) Environment setup, authentication, and API keys ### 👥 [KYC & Compliance →](#kyc--compliance) Verification levels, thresholds, and requirements ### 💰 [Accepting Payments →](#accepting-payments) Create payment requests and process crypto transactions ### 📤 [Sending Payouts →](#sending-payouts) Cryptocurrency disbursements to external wallets ### 🔗 [Webhook Integration →](#webhook-integration) Real-time payment notifications and event handling ### ✅ [Go-Live Checklist →](#go-live-checklist) Production readiness requirements --- ## Getting Started Environment setup, authentication, and API keys > **Quick summary:** Get your API keys from the dashboard, use staging for development, and never expose keys in frontend code. ### Step 1: Log Into Your Dashboard 1. Go to `https://staging.overchain.io` (for testing) or `https://app.overchain.io` (for production) 2. Log in with your merchant credentials 3. You'll land on the main dashboard ### Step 2: Create Your API Keys 1. In the dashboard, navigate to the product you want to use (Acquiring, Send Crypto, or Settings) 2. Click on the **API Keys** tab 3. Create the **API key** with name and your server's **IP** address — only requests from this IP will be accepted 4. Copy your Bearer token and store it securely (environment variable, secrets manager, etc.) > **IP Whitelisting is mandatory.** API requests from non-whitelisted IPs will be rejected. Make sure to add the IP address of every server that will call the Overchain API. > **Tip:** Start with **Staging** to test your integration. No real money is involved, so you can experiment freely. ### Step 3: Make Your First API Call Test your setup by making a simple authenticated request: ```bash curl -X GET "https://staging.overchain.io/api/merchant/acquiring/v1/payments" \ -H "Authorization: Bearer YOUR_API_KEY" ``` If you get a response (even an empty list), your API key is working! ### Environments | Environment | Base URL | Purpose | |---|---|---| | **Staging** | `https://staging.overchain.io` | Development & testing - sample fiat transfers and mainnet blockchains associated | | **Production** | `https://app.overchain.io` | Live transactions with real funds | > Production actions involve real funds and cannot be reversed. Testing environments may occasionally be unstable due to active development done by our team. ### API Keys Each product has its own API key. Find them in your dashboard: | Product | Dashboard Path | Token Name | |---|---|---| | **Acquiring** | Dashboard → Acquiring → API Keys | `AcquiringBearer` | | **Send Crypto** | Dashboard → Send Crypto → API Keys | `SendCryptoBearer` | | **KYC / KYB** | Dashboard → Settings → API Keys | `CustomerApiBearer` | ### Authentication All API requests require a Bearer token in the Authorization header: ```http Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json ``` > **Security:** Never expose API keys in frontend code or commit them to version control. Use environment variables. --- ## KYC & Compliance Verification levels, thresholds, and requirements > **Quick summary:** Payments and KYC are independent. KYC only needed when volume exceeds CAD $10,000/24hrs. **Integration Flow:** `Create Customer` → `Create Payment` → `Listen for Webhook` > **Key Concept:** Payments work anytime. KYC is only triggered based on transaction volume thresholds. Customers are linked by email. ### Do I Need KYC? KYC verification is required when: - A single customer transacts over **CAD $10,000 in 24 hours** - You want to pre-verify customers before they hit limits > **Recommended for Everyone:** Pre-populating customer data is recommended for **all integrations** to create a frictionless experience. When customers hit verification thresholds, their information is already on file — no interruptions. ### Integration Approaches #### KYC Document Flow When verification is required, documents can be supplied through two paths: **Flow:** `Customer Transacts` → `Threshold Reached (CAD $10k/24hrs)` → `KYC Required` **Path A: Merchant Supplies** 1. Webhook received 2. Merchant collects ID + selfie 3. Upload via API 4. ✓ Verified **Path B: Customer Supplies** 1. Customer in widget 2. Widget prompts for docs 3. Customer uploads directly 4. ✓ Verified | Approach | Who Supplies | How It Works | Best For | |---|---|---|---| | **Merchant-supplied** | Merchant (via API) | Merchant collects customer documents (ID + selfie) and uploads via API | White-label UX, full control | | **Customer-supplied** | End Customer (via Widget) | Customer uploads documents directly in Overchain widget | Simpler integration, less dev work | ### Step 1: Pre-populate Customer Data Pre-fill customer information so verification is seamless when needed: 1. Collect customer details (name, email, address, DOB) 2. Call the pre-populate API with their info 3. Save the `clientReferenceId` you receive back 4. Use this ID in payment requests to link transactions to this customer #### Pre-populate Customer `POST` `/api/merchant/customer/pre-populate` #### Individual Required Fields (KYC) | Field | Type | Description | |---|---|---| | `email` | string | Customer's email | | `customerType` | string | "individual" | | `firstName` | string | First name | | `lastName` | string | Last name | | `dob` | string | Date of birth (YYYY-MM-DD) | | `country` | string | ISO alpha-3 (e.g., CAN, USA, DEU) | | `street` | string | Street address | | `subStreet` | string | Building/unit number | | `town` | string | City | | `postCode` | string | Postal code | | `state` | string | State/province | #### Company Required Fields (KYB) | Field | Type | Description | |---|---|---| | `email` | string | Company contact email | | `customerType` | string | "company" | | `businessName` | string | Legal business name | | `tradingName` | string | Trading/DBA name | | `businessNumber` | string | Registration number | | `countryOfIncorporation` | string | ISO alpha-3 (e.g., CAN, USA, DEU) | | `incorporatedOn` | string | Incorporation date (YYYY-MM-DD) | | `natureOfBusiness` | string | Business type/industry | | `street` | string | Business street address | | `subStreet` | string | Building/unit number | | `town` | string | City | | `postCode` | string | Postal code | | `state` | string | State/province | #### Example Request (Individual) ```bash curl -X POST "https://staging.overchain.io/api/merchant/customer/pre-populate" \ -H "Authorization: Bearer YOUR_ACQUIRING_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "john.doe@example.com", "customerType": "individual", "firstName": "John", "lastName": "Doe", "dob": "1990-05-15", "street": "Hauptstraße", "subStreet": "123", "town": "Berlin", "postCode": "10115", "country": "DEU" }' ``` #### Example Request (Company) ```bash curl -X POST "https://staging.overchain.io/api/merchant/customer/pre-populate" \ -H "Authorization: Bearer YOUR_ACQUIRING_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "company@example.com", "customerType": "company", "businessName": "Acme Tech GmbH", "businessNumber": "123456789RC0001", "tradingName": "Acme Tech GmbH Trading", "countryOfIncorporation": "DEU", "incorporatedOn": "2010-03-15", "natureOfBusiness": "information_technology", "street": "Corporate Straße", "subStreet": "100", "town": "Munich", "postCode": "80331", "state": "Bavaria" }' ``` #### Response ```json { "id": 140, "email": "john.doe@example.com", "customerType": "individual", "firstName": "John", "lastName": "Doe", "businessName": null, "businessAddress": null, "businessNumber": null, "metadata": null, "createdAt": "2026-02-24T16:14:18+00:00", "expiresAt": "2026-08-25T11:25:38+00:00", "used": false, "usedAt": null, "sumsubApplicantId": null, "sumsubExternalUserId": null, "sumsubReviewStatus": null, "verificationLevel": "PARTIAL", "verificationStatus": "pending", "clientReferenceId": null, "message": null, "street": "Hauptstraße", "subStreet": "123", "town": "Berlin", "postCode": "10115", "state": null } ``` > **Next Step:** Use the `clientReferenceId` in your payment requests to link transactions to this customer. ### Step 2: Upload Documents (When Required) If a customer hits the verification threshold: 1. Collect a photo of their government ID (passport, national ID, or driver's license) 2. Collect a selfie OR Proof of Address (POA) 3. Convert images to base64 4. Call the document upload API 5. Wait for verification #### Upload Documents `POST` `/api/merchant/customer/documents/{clientReferenceId}` #### Individual Documents (KYC) Submit ONE of these ID combinations plus a SELFIE: - `PASSPORT` — Single passport photo - `ID_FRONT` + `ID_BACK` — National ID card - `DRIVERS_FRONT` + `DRIVERS_BACK` — Driver's license #### Company Documents (KYB) Must satisfy all 4 document groups: | Group | Purpose | Accepted Documents | |---|---|---| | **Company Details** | Business identity | `INCORPORATION_CERT`, `STATE_REGISTRY`, `GOOD_STANDING_CERT` | | **Legal Presence** | Legal registration | `INCORPORATION_CERT`, `INCORPORATION_ARTICLES`, `STATE_REGISTRY` | | **Ownership** | Ownership proof | `SHAREHOLDER_REGISTRY`, `STATE_REGISTRY`, `TRUST_AGREEMENT` | | **Control** | Management proof | `DIRECTORS_REGISTRY`, `STATE_REGISTRY`, `TRUST_AGREEMENT` | #### Example Request ```bash curl -X POST "https://staging.overchain.io/api/merchant/customer/documents/65f43a44db7dd58b69005319" \ -H "Authorization: Bearer YOUR_ACQUIRING_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "documents": [ { "type": "PASSPORT", "content": "base64_encoded_image_data..." }, { "type": "SELFIE", "content": "base64_encoded_image_data..." } ] }' ``` #### Response ```json { "clientReferenceId": "65f43a44db7dd58b69600319", "documentsUploaded": 2, "verificationStatus": "pending" } ``` ### Step 3: Check Verification Status 1. Poll the customer list API or wait for a webhook 2. Check the `verificationStatus` field 3. If `approved`, the customer can continue transacting 4. If `rejected`, they need to resubmit documents ### Verification Statuses | Status | Description | |---|---| | `pending` | Documents submitted, under review | | `approved` | Verification successful | | `rejected` | Verification failed — resubmit required | ### Verification Levels | Level | Threshold | Requirements | |---|---|---| | **PARTIAL** | Initial level | Email OTP via widget | | **BASE** | Up to CAD $10,000/24hrs | Basic verification | | **FULL** | Above CAD $10,000/24hrs | Government ID + Selfie | ### List Customers `GET` `/api/merchant/customer/list` | Parameter | Type | Description | |---|---|---| | `customer_type` | string | Filter: "individual" or "company" | | `verification_level` | string | Filter: PARTIAL, BASE, or FULL | | `search` | string | Search by email | | `limit` | integer | Max results (1-100, default: 50) | | `offset` | integer | Results to skip | [Full Verification Guide →](./02-verification-guide.md) --- ## Accepting Payments Create payment requests and process transactions > **Quick summary:** Create payment → redirect to `widget_link` → wait for webhook → fulfill order. ### Step 1: Create a Payment When a customer is ready to pay, call the API to create a payment request: 1. Collect the order details (amount, currency, your order ID) 2. Make a POST request to create the payment (see code below) 3. You'll receive a `widget_link` in the response #### Create a Payment `POST` `/api/merchant/acquiring/v1/payment` #### Request Parameters | Field | Type | Required | Description | |---|---|---|---| | `payment_code` | string | Yes | Your unique order identifier | | `order_amount` | string | Yes | Amount to charge (e.g., "149.99") | | `order_currency` | string | Yes | Fiat currency: EUR, USD, CAD, GBP | | `title` | string | No | Payment title shown to customer | | `description` | string | No | Payment description | | `back_url` | string | No | Redirect URL after payment (HTTPS only) | | `payment_currency` | string | No | Lock to specific crypto (e.g., BTC, ETH) | | `settlement_currency` | string | No | Currency to settle in (defaults to dashboard default) | | `client_reference_id` | string | No | Link to pre-populated customer for KYC tracking | | `client_params` | object | No | Custom metadata key-value pairs | #### Example Request ```bash curl -X POST "https://staging.overchain.io/api/merchant/acquiring/v1/payment" \ -H "Authorization: Bearer YOUR_ACQUIRING_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "payment_code": "INV-12345", "order_amount": "149.99", "order_currency": "EUR", "title": "Order #12345", "description": "Checkout invoice", "settlement_currency": "USD", "payment_currency": null, "back_url": "https://merchant.example.com/return", "client_params": null, "client_reference_id": "6985b4be064fpbfb86021851" }' ``` #### Response ```json { "id": "D600A886", "status": "waiting", "payment_code": "INV-12345", "order_amount": "149.99", "order_currency": "EUR", "pay_amount_total": null, "pay_currency": null, "transactions": [], "title": "Order #12345", "description": "Checkout invoice", "back_url": "https://merchant.example.com/return", "payment_address": null, "widget_link": "https://staging.overchain.io/widget/acquiring/payment/7b71fe3b-4ee1-4caf-92b4-26aaa42e0a45", "expire_at": null, "created_at": "2026-02-26T14:07:45+00:00", "updated_at": "2026-02-26T14:07:45+00:00", "order_amount_paid": null, "order_amount_pending": null, "order_amount_remaining": null, "receiver_amount_paid": null, "receiver_amount_pending": null, "receiver_amount_remaining": null, "receiver_currency": "USD", "pay_amount_paid": "0", "pay_amount_pending": "0", "pay_amount_remaining": null, "pay_method": "crypto", "payment_amount": null, "payment_currency": null, "payment_uri": null, "blockchain": null, "client_params": {}, "client_reference_id": null } ``` ### Step 2: Redirect the Customer 1. Take the `widget_link` from the response 2. Redirect your customer to that URL (or open it in a new tab/iframe) 3. The customer will see a payment page where they choose their crypto and pay ### Step 3: Wait for Payment Confirmation 1. The customer pays using their crypto wallet 2. Overchain waits for blockchain confirmations 3. Once confirmed, Overchain sends a webhook to your server (see Webhooks section) ### Step 4: Fulfill the Order 1. Your webhook handler receives the payment notification 2. Verify the payment status and fulfill the order (ship product, grant access, etc.) 3. Return HTTP 200 to acknowledge the webhook **Payment Flow:** `Create Payment` → `Customer Pays` → `Webhook` → `Fulfill Order` ### Payment Statuses | Status | Description | Action | |---|---|---| | `new` | Payment created, awaiting customer | Show payment page | | `pending` | Crypto received, awaiting confirmations | Show processing status | | `completed` | Payment confirmed | Fulfill order | | `cancelled` | Payment cancelled | No action | ### Get Payment `GET` `/api/merchant/acquiring/v1/payment/{id}` ```bash curl -X GET "https://staging.overchain.io/api/merchant/acquiring/v1/payment/D600A886" \ -H "Authorization: Bearer YOUR_ACQUIRING_TOKEN" ``` ### List Payments `GET` `/api/merchant/acquiring/v1/payments` | Parameter | Type | Default | Description | |---|---|---|---| | `limit` | integer | 50 | Max results (1-100) | | `offset` | integer | 0 | Results to skip | ### Cancel Payment `PUT` `/api/merchant/acquiring/v1/payment/{id}/cancel` [Full Payments Guide →](./05-acquiring-guide.md) --- ## Sending Payouts Cryptocurrency disbursements to external wallets > **Quick summary:** Create payout → wait for webhook confirmation. ### When Do I Need Payouts? Use payouts when you need to send cryptocurrency to external wallets: - Paying affiliates or partners - Processing customer withdrawals - Disbursing rewards or refunds ### Step 1: Create the Payout You can specify the payout amount in two ways: - **Fiat equivalent** — specify a fiat amount (e.g., $100 USD) and Overchain converts to crypto - **Exact crypto** — specify the exact crypto amount to send (e.g., 0.05 BTC) 1. Get the recipient's wallet address 2. Double-check the address matches the crypto network (e.g., ETH address for USDT-ERC20) 3. Call the create payout endpoint 4. Save the payout ID from the response > **Critical:** Always verify wallet addresses carefully. Crypto sent to the wrong address cannot be recovered. #### Create Payout `POST` `/api/customer/v1/crypto-payout` #### Request Parameters | Field | Type | Required | Description | |---|---|---|---| | `send_currency_code` | string | No* | Source currency (e.g., EUR) | | `send_amount` | string | No* | Amount to send in source currency | | `receive_currency_code` | string | Yes | Crypto to send (e.g., BTC) | | `receive_amount` | string | No* | Amount of crypto to send | | `receive_address` | string | Yes | Recipient wallet address | | `code` | string | No | Your unique payout identifier | | `description` | string | No | Internal description | | `party` | object | Yes | Recipient party details | *Provide either `send_amount` OR `receive_amount`, not both.* #### Party Object | Field | Type | Description | |---|---|---| | `type` | string | "individual" or "company" | | `individual.full_name` | string | Full name (if individual) | | `individual.date_of_birth` | string | DOB in YYYY-MM-DD format | | `company.name` | string | Company name (if company) | | `company.registration_number` | string | Registration number | | `address` | object | Country, city, street, building_number, zip_postcode | #### Example Request ```bash curl -X POST "https://staging.overchain.io/api/customer/v1/crypto-payout" \ -H "Authorization: Bearer YOUR_SENDCRYPTO_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "send_currency_code": "EUR", "send_amount": null, "receive_currency_code": "BTC", "receive_amount": "0.001", "receive_address": "1A1zP1eP5QGefi2DMPTfTL533ov7DivfNa", "code": "PAYOUT-001", "description": "Customer withdrawal", "party": { "type": "individual", "individual": { "full_name": "Jane Doe", "date_of_birth": "1990-05-15" }, "address": { "country": "DEU", "city": "Berlin", "street": "Hauptstraße", "building_number": "10", "zip_postcode": "10115" } } }' ``` > **Critical:** Always verify wallet addresses carefully. Crypto sent to the wrong address cannot be recovered. #### Response ```json { "uuid": "3fa85f64-5717-4562-b3fc-2c003f66afa6", "send_currency_code": "EUR", "send_amount": "100.00", "receive_currency_code": "BTC", "receive_amount": "0.0020", "status": "New", "created_at": "2025-09-29T12:00:00Z" } ``` ### Step 2: Monitor the Payout 1. The payout starts with status `Pending` 2. It moves to `Processing` when submitted to the blockchain 3. Finally, it becomes `Done` when confirmed 4. You can poll the Get Payout endpoint or wait for a webhook **Payout Flow:** `Create Payout` → `Processing` → `Done` ### Payout Statuses | Status | Description | Final? | |---|---|---| | `Pending` | Payout queued for processing | No | | `Processing` | Transaction submitted to blockchain | No | | `Done` | Transaction confirmed | Yes | | `Failed` | Payout failed | Yes | | `Cancelled` | Payout was cancelled | Yes | ### List Payouts `GET` `/api/customer/v1/crypto-payout` ```bash curl -X GET "https://staging.overchain.io/api/customer/v1/crypto-payout" \ -H "Authorization: Bearer YOUR_SENDCRYPTO_TOKEN" \ -H "Accept: application/json" ``` #### Response ```json [ { "uuid": "095be615-a8ad-4c33-8e9c-c761200f6c9f", "status": "New", "amount": "0.002", "currency": "TRX", "address": "1A1zP1..." } ] ``` ### Get Payout `GET` `/api/customer/v1/crypto-payout/{uuid}` ```bash curl -X GET "https://staging.overchain.io/api/customer/v1/crypto-payout/3fa85f64-5717-4562-b3fc-2c968866afa6" \ -H "Authorization: Bearer YOUR_SENDCRYPTO_TOKEN" \ -H "Accept: application/json" ``` #### Response ```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f600fa6", "receive_currency_code": "TRX", "receive_amount": "0.0020", "status": "Confirmed", "created_at": "2025-09-29T12:00:00Z" } ``` [Full Send Crypto Guide →](./06-send-crypto-guide.md) --- ## Webhook Integration Real-time payment notifications and event handling > **Quick summary:** Configure webhook URL → receive payment events → verify signature → process payment. ### What Are Webhooks? Webhooks are automatic notifications that Overchain sends to your server when something happens (like a payment completing). Instead of constantly checking "is the payment done yet?", Overchain tells you when it's done. ### Step 1: Create a Webhook Endpoint You need a URL on your server that can receive POST requests: 1. Create an endpoint (e.g., `https://yoursite.com/webhooks/overchain`) 2. Make sure it's publicly accessible (not localhost) 3. It must use HTTPS (not HTTP) 4. It should return HTTP 200 quickly (process async if needed) ### Step 2: Configure in Dashboard Webhooks can be configured in **two places** depending on your integration: | Product | Location | Events | |---|---|---| | **Acquiring** | Dashboard → Acquiring → Settings | Payment events, KYC events | | **Send Crypto** | Dashboard → Send Crypto → Settings | Payout events | 1. Go to the appropriate Settings page for your product 2. Find the **Webhook URL** field 3. Paste your endpoint URL 4. Save your settings > **KYC Webhooks:** KYC/verification events are sent via the **Acquiring webhook**. If no response is received within 60 seconds, the system will prompt the end user to provide their documents directly. ### Step 3: Handle Incoming Webhooks 1. Parse the JSON body of incoming POST requests 2. Check the `event_type` field to see what happened 3. Verify the payment is completed 4. Fulfill the order 5. Return HTTP 200 to acknowledge receipt ### Webhook Payload Example ```json { "event_type": "payment.completed", "event_id": "f74c0cc5-de66-485d-b6cc-5933337ac682", "occurred_at": "2026-02-26T14:39:45+00:00", "payment": { "id": "86330346", "code": "TEST-1772116033243", "widget_link": "https://staging.overchain.io/widget/acquiring/payment/..." }, "order": { "amount": "10.02", "currency": "EUR" }, "coverage": { "is_fully_covered": true, "is_overpaid": false }, "source": { "tx_ids": ["0xcca5501201fa0c39c07ca4c18f0b8e93c7756a9269c1425fac8c83336f8b88b"], "currency": "USDT-ERC20", "amount_total": "11.817" }, "destination": { "amount": "10.373862", "currency": "USDT-ERC20" }, "fees": [ { "amount": "1.443138", "currency": "USDT-ERC20" } ] } ``` ### Handle the Webhook ```javascript app.post('/webhook/overchain', (req, res) => { const { event_type, payment, coverage } = req.body; if (event_type === 'payment.completed') { fulfillOrder(payment.code); } res.status(200).send('OK'); }); ``` > **Pro Tip:** Always process webhooks asynchronously. Accept the webhook immediately (return 200), then process in the background. This prevents timeouts. ### Step 4: Whitelist Overchain's IPs For security, only accept webhooks from Overchain's servers: | Environment | IP Addresses | |---|---| | **Staging** | `63.35.114.89` | | **Production** | `54.154.8.174`, `34.250.208.12`, `34.255.33.124` | --- ## Supported Cryptocurrencies | Code | Name | Network | |---|---|---| | `BTC` | Bitcoin | Bitcoin | | `ETH` | Ethereum | Ethereum | | `USDT-ERC20` | Tether | Ethereum | | `USDC` | USD Coin | Ethereum | | `USDT-TRC20` | Tether | Tron | | `TRX` | Tron | Tron | | `USDT-BEP20` | Tether | BNB Chain | | `BNB` | BNB | BNB Chain | | `LTC` | Litecoin | Litecoin | --- ## Rate Limits | Endpoint | Limit | |---|---| | Create Payment | 100 req/min | | Get Payment | 200 req/min | | Pre-populate Customer | 100 req/min | | Document Upload | 30 req/min | | List Customers | 60 req/min | --- ## Error Handling All API errors return a consistent JSON structure. See the [Error Handling Guide](./04-error-handling.md) for status codes, retry strategies, and common troubleshooting scenarios. --- ## Go-Live Checklist > **Quick summary:** Complete all items before switching from staging to production. - [ ] Tested all payment flows on staging - [ ] Tested KYC/KYB verification flow on staging - [ ] Tested payout flow on staging (if applicable) - [ ] Generated **production** API keys - [ ] Updated all API base URLs to `https://app.overchain.io` - [ ] Configured production webhook URLs in Dashboard - [ ] Whitelisted production webhook IPs in your firewall - [ ] Implemented idempotent webhook handling - [ ] Verified error handling and retry logic > **Need Help?** Contact your account manager or email [support@overchain.io](mailto:support@overchain.io) to activate production access and get support.