Coins.ph Ramp Callback API
Webhook callbacks sent to the merchant's configured callback URL when order status changes
OpenAPI Specification
openapi: 3.0.0
info:
title: TRADING Account Ramp Callback API
version: 1.0.0
description: API reference for Account management — Coins.ph
servers:
- url: https://api.pro.coins.ph
description: Production
- url: https://api.9001.pl-qa.coinsxyz.me
description: Sandbox
tags:
- name: Ramp Callback
description: Webhook callbacks sent to the merchant's configured callback URL when order status changes
paths:
/openapi/ramp/callback:
post:
tags:
- Ramp Callback
summary: Ramp Callback API
description: 'A POST request will be sent to the callback URL configured by the merchant whenever the order status changes. This is NOT an endpoint you call — it documents the payload Coins.ph sends TO your server.
## Order Status Values
- `CREATE` - Order created
- `RISK_REVIEW` - Risk review in progress
- `FUND_TRANSFER_PROCESSING` - Fund transfer in progress
- `QUOTE_ACCEPT_PROCESSING` - Quote acceptance in progress
- `REFUNDED_TRANSFER_PROCESSING` - Refund transfer in progress
- `QUOTE_ACCEPTED` - Quote accepted
- `WAITING_TX_ID` - Waiting for transaction ID from merchant
- `CRYPTO_DISBURSE_PENDING` - Crypto disbursement pending
- `CRYPTO_PENDING` - Waiting for crypto deposit
- `CRYPTO_SENT` - Crypto sent
- `CRYPTO_CONFIRMING` - Crypto confirming on chain
- `CRYPTO_CONFIRMED` - Crypto confirmed
- `CRYPTO_REFUND_PENDING` - Crypto refund pending
- `CRYPTO_REFUND` - Crypto refunded
- `PAYOUT_PROCESSING` - Payout processing
- `PAYOUT_FAILED` - Payout failed
- `REFUND_FAILED` - Refund failed
- `PAYOUT_CONFIRMED` - Payout confirmed
- `MANUAL_REVIEW` - Manual review required
- `FUND_TRANSFER_BACK` - Fund transferred back
- `EXPIRED` - Order expired
- `PROCESSING` - Processing
- `SUCCEEDED` - Succeeded (terminal)
- `FAILED` - Failed (terminal)
- `CANCELLED` - Cancelled (terminal)
- `REFUNDED` - Refunded (terminal)'
operationId: rampOrderStatusCallback
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RampCallbackRequest'
example:
id: '2199397325237953280'
rampType: OFF_RAMP
orderId: '2199397325237953280'
orderStatus: QUOTE_ACCEPT_PROCESSING
txId: ''
errorCode: ''
errorMessage: ''
moreInfo:
createdAt: '2026-04-23T06:09:53Z'
quoteId: d20eaa5ecde942eeb48b5f40fe981a76
status: QUOTE_ACCEPT_PROCESSING
sourceAmount:
amount: 1.2
currency: USDT
zero: false
positive: true
targetAmount:
amount: 1.196
currency: USDC
zero: false
positive: true
sourceCurrency: USDT
targetCurrency: USDC
targetWalletAddress: rKrDJLGiSrKsRRtEQVgnWJnKALp5NJeDkC
targetUserId: '2142216666787644416'
targetWalletAddressTag: ''
errorCode: ''
errorMessage: ''
txId: ''
withdrawId: ''
orderId: '2199397325237953280'
rampTypeCode: OFF_RAMP
callbackKey: null
merchantId: null
timestamp: 1776924592732
responses:
'200':
description: Merchant acknowledges receipt of the callback
content:
application/json:
schema:
$ref: '#/components/schemas/RampCallbackResponse'
example:
code: '0'
message: success
data: {}
components:
schemas:
RampCallbackRequest:
type: object
description: Callback payload sent to the merchant's configured callback URL when order status changes.
required:
- rampType
- orderId
- orderStatus
properties:
id:
type: string
description: Unique callback event identifier.
example: '2199397325237953280'
rampType:
type: string
enum:
- ON_RAMP
- OFF_RAMP
description: Type of ramp operation.
example: OFF_RAMP
orderId:
type: string
description: The order ID.
example: '2199397325237953280'
orderStatus:
type: string
enum:
- CREATE
- RISK_REVIEW
- FUND_TRANSFER_PROCESSING
- QUOTE_ACCEPT_PROCESSING
- REFUNDED_TRANSFER_PROCESSING
- QUOTE_ACCEPTED
- WAITING_TX_ID
- CRYPTO_DISBURSE_PENDING
- CRYPTO_PENDING
- CRYPTO_SENT
- CRYPTO_CONFIRMING
- CRYPTO_CONFIRMED
- CRYPTO_REFUND_PENDING
- CRYPTO_REFUND
- PAYOUT_PROCESSING
- PAYOUT_FAILED
- REFUND_FAILED
- PAYOUT_CONFIRMED
- MANUAL_REVIEW
- FUND_TRANSFER_BACK
- EXPIRED
- PROCESSING
- SUCCEEDED
- FAILED
- CANCELLED
- REFUNDED
description: 'Current order status. Terminal statuses: SUCCEEDED, FAILED, CANCELLED, REFUNDED.'
example: QUOTE_ACCEPT_PROCESSING
txId:
type: string
description: On-chain transaction ID (if applicable).
example: ''
errorCode:
type: string
description: Error code (if any).
example: ''
errorMessage:
type: string
description: Error message (if any).
example: ''
moreInfo:
type: object
description: Additional order information.
properties:
createdAt:
type: string
format: date-time
description: Order creation time in ISO 8601 format.
example: '2026-04-23T06:09:53Z'
quoteId:
type: string
description: Quote identifier.
example: d20eaa5ecde942eeb48b5f40fe981a76
status:
type: string
description: Status within moreInfo context.
example: QUOTE_ACCEPT_PROCESSING
sourceAmount:
type: object
properties:
amount:
type: number
example: 1.2
currency:
type: string
example: USDT
zero:
type: boolean
example: false
positive:
type: boolean
example: true
targetAmount:
type: object
properties:
amount:
type: number
example: 1.196
currency:
type: string
example: USDC
zero:
type: boolean
example: false
positive:
type: boolean
example: true
sourceCurrency:
type: string
example: USDT
targetCurrency:
type: string
example: USDC
targetWalletAddress:
type: string
description: Target wallet address for the transaction.
example: rKrDJLGiSrKsRRtEQVgnWJnKALp5NJeDkC
targetUserId:
type: string
description: Target user identifier.
example: '2142216666787644416'
targetWalletAddressTag:
type: string
description: Wallet address tag (if applicable).
example: ''
errorCode:
type: string
example: ''
errorMessage:
type: string
example: ''
txId:
type: string
description: On-chain transaction ID.
example: ''
withdrawId:
type: string
description: Withdrawal ID.
example: ''
orderId:
type: string
example: '2199397325237953280'
rampTypeCode:
type: string
enum:
- ON_RAMP
- OFF_RAMP
example: OFF_RAMP
callbackKey:
type: string
nullable: true
description: Callback key (if configured).
merchantId:
type: string
nullable: true
description: Merchant ID (if configured).
timestamp:
type: integer
format: int64
description: Callback timestamp (epoch millis).
example: 1776924592732
RampCallbackResponse:
type: object
description: Expected response from merchant after receiving the callback.
properties:
code:
type: string
description: Response code. '0' indicates success.
example: '0'
message:
type: string
description: Response message.
example: success
data:
type: object
description: Response data (can be empty).
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-COINS-APIKEY
x-readme:
proxy-enabled: false