Quick Start Guide

Welcome to BasicEx Pay! This guide will help you quickly integrate with our APIs. You can use these interfaces to create payment/invoice orders, initiate payout requests, process refunds, and retrieve real-time exchange rates.

We highly recommend using our Official SDKs for integration to avoid complex cryptographic signature processing.

1. Prerequisites

Before starting your integration, please ensure you have:

1. Registered and logged into the Merchant Portal.
2. Retrieved your Merchant ID.
3. Obtained your API Certificate or API Key, depending on the authentication method chosen for your business.
4. [Recommended] Downloaded the official SDK for your language (which already encapsulates all low-level signing and verification logic):
   • Java SDK & Demo

2. API Authentication & Signature Mechanism

To ensure the security of financial interactions, all core API requests require strong authentication. Currently, BasicEx Pay supports two signature methods:

• API Certificate Signature (Recommended): Uses a platform-issued certificate and the merchant's private key to perform asymmetric cryptographic signing. This offers the highest security and is suitable for core transactions in production environments.
• API Key Signature: Uses a unified API Key to calculate a hash-based signature. It has lower integration costs and is suitable for lightweight access.

Signature Tips

• If you use an SDK, regardless of the signature method above, you just need to configure the certificate path or API Key during initialization. The SDK will automatically sign outgoing requests and verify incoming callbacks.
• If you do not use an SDK and are making native HTTP requests, you must manually construct and calculate the X-Signature and other signature headers in the HTTP request. For detailed cryptographic algorithms and formatting rules, you MUST refer to: Signed Request & Underlaying Flow.

3. Core Business Integration Flows

Once the authentication configuration is complete, you can begin integrating the actual business flows.

Important: Prerequisites for Non-SDK Integration

If you are not using the official SDK but instead integrating via your own HTTP request code library, before reviewing the business APIs below, please be sure to understand the fundamental mechanisms that apply to every business interface:

1. How to Initiate a Request (Header requirements): 👉 API Request & Headers Specification
2. How to Sign a Request (Core algorithms and encoding for tamper-proofing): 👉 Signed Request & Underlaying Flow

Please read the relevant API documents based on your scenario:

Scenario A: Payment / Invoice

Implement the business loop of initiating an order within your platform or app and collecting the payment via BasicEx Pay.

1. Initiate Payment: Call the API to create a payment invoice 👉 Create an Invoice
2. Asynchronous Callback: Receive the async notification of successful user payment 👉 Invoice Webhook Notification
3. Active Query: (Optional) Actively retrieve the current status of the order 👉 Retrieve an Invoice

Scenario B: Payout

Implement the business loop of sending funds from your merchant balance to target users/merchants.

1. Initiate Payout: Submit a payout request 👉 Create a Payout
2. Asynchronous Callback: Receive the async notification of payout success or failure 👉 Payout Webhook Notification
3. Active Query: (Optional) Actively retrieve the processing status of the payout 👉 Retrieve a Payout

---

4. Webhook Callbacks & Signature Verification

Because real on-chain calls and confirmations take time, the outcomes of payments and payouts are asynchronous. Your system must not only be able to receive BasicEx Webhook notifications, but more crucially—to prevent forged "payment success" callbacks, you MUST perform strict signature verification on the received Webhook requests!

If you plan to perform manual verification (without SDK parsing), please carefully review the dedicated guide: 👉 Comprehensive Webhook Verification Tutorial & Principles

Webhook Integration Reminders

1. Do Not Use Parsed JSON Objects for Verification: The data source for verifying the signature must be the raw, unmanipulated HTTP Body text stream received by the server.
2. Correct Response: After successfully verifying the Webhook and completing your local business logic, you must return an HTTP 200 status code with an empty body to our system. If any other status is returned, the system will deem the push as a failure and trigger the subsequent exponential backoff retry mechanism.
3. Concurrency & Idempotency: Network jitter or retries may cause the same notification to arrive multiple times. Please use fields like the order number to implement idempotent updates in your local logic to prevent multiple crediting/deducting of funds.

5. Pre-launch Go-Live Checklist

Before officially deploying to production, developers and testers must finally verify:

• [ ] Are API requests being successfully initiated with correct Certificate or API Key signature verification?
• [ ] Has the asynchronous Webhook Certificate/Key verification logic been successfully tested and can it intercept invalid requests?
• [ ] Has the HTTP 200 Webhook response been correctly implemented?
• [ ] Are the corresponding business data processing lock mechanisms or concurrency prevention solutions in place?

6. Technical Support

If you encounter unknown issues during API calls, first check against the: 👉 Error Codes Reference Manual If you are blocked by environmental or other complex issues, please record your Merchant ID and capture critical logs such as request headers and response payloads, then contact our website customer service to be transferred to the technical support department, and we will quickly assist you.