Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

GatePay OTC provides two closely related settlement flows under one business domain:
  • On-ramp: use fiat to buy crypto and credit assets to the merchant account
  • Off-ramp: sell crypto and settle fiat to an approved bank account
Both flows share the same integration model:
  • signed server-side API calls
  • quote retrieval before order creation
  • bank account governance
  • status tracking through active queries and callback notifications
From an integration perspective, OTC is closer to a settlement product than to a retail checkout product. Merchants typically manage order creation, bank account selection, callback consumption, and reconciliation from the server side. As a result, a successful integration depends not only on calling the right API, but also on understanding the business flow around quote timing, remittance, settlement tracking, and callback processing.

​
Shared Integration Requirements

Before using OTC APIs, make sure that:
  1. The merchant account has completed the required KYC or compliance review.
  2. API credentials and signing logic are already available in the merchant backend.
  3. At least one bank account has been created and approved for OTC settlement.
  4. The merchant operates in a supported country or region.
See: In addition to technical readiness, merchants should also prepare their business process before going live:
  • define how bank account onboarding is managed
  • define how quote expiry and order retry are handled
  • define how callback events are persisted and replayed
  • define how OTC settlements are reconciled

​
Shared Quote API

OTC on-ramp and off-ramp both depend on quote retrieval. Use the following page to understand quote meaning, validity, and usage: Use type to distinguish the business direction:
  • BUY: OTC on-ramp
  • SELL: OTC off-ramp
Operationally, the quote API should be treated as a short-lived pricing input rather than as a persistent contract. The safest pattern is:
  1. request a quote immediately before the user or operator is ready to proceed
  2. persist the quote token and validity period
  3. create the order within the validity window
  4. discard and refresh the quote if timing or amount changes

​
OTC / On-ramp

​
Business Goal

OTC on-ramp allows a merchant to remit fiat by bank transfer and receive cryptocurrency in the GatePay merchant account. Typical use cases include treasury top-up, institutional inventory purchase, and merchant-side fiat funding before using assets for further payment or settlement activities.

​
Typical Flow

Get Quote -> Create Deposit Order -> Receive Gate Collection Bank Info -> Complete Offline Remittance -> Confirm Payment -> Track Settlement -> Assets Credited

​
Core APIs

​
Minimum Integration Path

For a first OTC on-ramp integration, it is best to validate quote retrieval, order creation, payment confirmation, and settlement tracking through the smallest possible flow:
  1. request a BUY quote
  2. create the on-ramp order
  3. complete the offline bank remittance with the returned bank details
  4. call the payment-confirmation endpoint after remittance is completed
  5. track the final settlement result through callbacks and queries

​
Integration Notes

  • The quote must be used within its validity period.
  • The deposit order must carry a unique clientOrderId.
  • The merchant must transfer funds according to the returned Gate collection bank information.
  • The remittance reference must be preserved exactly.
  • Payment confirmation should be sent only after remittance is actually completed.
For on-ramp, merchants should understand “confirm payment” as a confirmation that the real bank remittance has already been made, rather than as a simple front-end acknowledgement action. For on-ramp, the most common issue is usually not the API itself, but a mismatch between the payment instruction and the actual bank remittance. Merchants should therefore preserve returned bank details exactly and keep enough order context for later reconciliation.

​
Common Callback States

  • RECHARGE_SUCCESS
  • RECHARGE_FAIL
In many integrations, callback events may arrive before all related downstream records are fully updated. It is therefore recommended to separate:
  • callback ingestion
  • business status confirmation
  • accounting or ledger posting

​
OTC / Off-ramp

​
Business Goal

OTC off-ramp allows a merchant to sell crypto and settle fiat to an approved bank account. Typical use cases include treasury withdrawal, merchant-side fiat liquidation, and operational settlement to external banking rails.

​
Typical Flow

Get Quote -> Create Withdrawal Order -> Wait for Processing -> Bank Dispatch -> Track Result -> Final Settlement Confirmation

​
Minimum Integration Path

For a first OTC off-ramp integration, validate one SELL flow from end to end:
  1. request a SELL quote
  2. choose an approved bank account
  3. create the off-ramp order
  4. process callbacks and query as fallback
  5. reconcile the platform result against the bank payout outcome

​
Core APIs

​
Integration Notes

  • Use a fresh quote token before creating the withdrawal order.
  • Keep clientOrderId globally unique.
  • Reconcile against both expected fiat amount and final settled fiat amount when provided.
  • Use callback plus detail query together as the reliable source of truth.
For off-ramp, settlement visibility is especially important because the business event spans both crypto disposal and bank-side payout. Merchants should avoid treating the workflow as complete too early. In most cases, the safest confirmation point is the final successful order state together with the returned payout metadata.

​
Common Callback States

  • WITHDRAW_DISPATCHED
  • WITHDRAW_SUCCESS
  • WITHDRAW_FAIL
When using WITHDRAW_DISPATCHED, it is helpful to treat it as a dispatch milestone rather than as the final settlement result. This makes it easier to distinguish “bank payout initiated” from “business fully completed”.

​
Bank Account Management

​
Operation flow

  1. Submit the bank account holder name, account number, bank name, SWIFT code, and other account details required for registration.
  2. Submit supporting documents such as the company operating certificate, shareholder proof, and shareholding structure chart (include whatever materials your onboarding case requires).
  3. Allow about two days for manual review. During this period, poll the Bank Account List API on a schedule; once verification succeeds, the account can be used for settlement.
Bank account governance should usually follow a stricter process than normal application configuration, because an incorrect bank account can lead to delays, review escalation, or settlement risk.

​
Callbacks and Reconciliation

OTC integrations should not rely on a single confirmation mechanism. Recommended pattern:
  1. Create and persist the quote and order on the backend.
  2. Store clientOrderId, orderId, and settlement metadata.
  3. Process callback notifications first.
  4. Use detail queries as the fallback source of truth.
  5. Reconcile bank settlement records with OTC order results.
For larger implementations, it is also useful to maintain separate business checkpoints such as:
  • quote acquired
  • order created
  • callback received
  • detail verified
  • finance reconciled
This approach makes it easier to understand settlement progress without overloading the API-level order state with additional business meaning. See: If this is your first OTC integration, the most practical reading order is:
  1. Read this OTC guide for the business model.
  2. Read Merchant Access and Authentication.
  3. Read the shared OTC Quote page.
  4. Read the order creation and query pages for the specific flow you are implementing.
  5. Finish with callback and reconciliation pages before launch.