This guide explains how to create, refresh, confirm, requery, and track an on-ramp transaction using the Quidax Ramp API.

An on-ramp transaction allows your customer to pay fiat currency, such as NGN, and receive cryptocurrency, such as USDT or USDC, into their wallet address.

Base URL

https://ramp-be.quidax.io

Transaction Flow

The on-ramp transaction flow works like this:

Create an on-ramp transaction.
Refresh the on-ramp transaction if you need to update or recalculate the quote.
Confirm the on-ramp transaction to generate a dynamic, single-use bank account.
Ask your customer to make the fiat deposit.
Listen to webhook events to track the transaction status.
Requery the buy transaction using the Fetch On-Ramp Transaction endpoint to confirm the latest transaction status.
Receive the final webhook when the transaction is successful or failed.

1. Create an On-Ramp Transaction

This endpoint is used to create an on-ramp transaction.

The merchant_reference must be unique for every new transaction. If the same merchant_reference is reused, the API will return a duplicate transaction error.

Endpoint

POST https://ramp-be.quidax.io/api/v1/merchants/custodial/on_ramp_transactions/initiate

Request

curl --request POST \
     --url https://ramp-be.quidax.io/api/v1/merchants/custodial/on_ramp_transactions/initiate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "from_currency": "ngn",
  "to_currency": "usdt",
  "from_amount": "3000",
  "merchant_reference": "xncbncvv",
  "customer": {
    "email": "[email protected]",
    "first_name": "test",
    "last_name": "user"
  },
  "wallet_address": {
    "address": "0xxx",
    "network": "bep20"
  }
}
'

Request Body Fields

Field	Type	Required	Description
`from_currency`	string	Yes	The fiat currency the customer is paying with. Example: `ngn`.
`to_currency`	string	Yes	The cryptocurrency the customer wants to receive. Example: `usdt`.
`from_amount`	string	Yes	The fiat amount the customer wants to pay.
`merchant_reference`	string	Yes	A unique transaction reference generated by the merchant. This must not be reused for another transaction.
`customer.email`	string	Yes	The customer’s email address.
`customer.first_name`	string	Yes	The customer’s first name.
`customer.last_name`	string	Yes	The customer’s last name.
`wallet_address.address`	string	Yes	The customer’s destination wallet address.
`wallet_address.network`	string	Yes	The blockchain network for the wallet address. Example: `bep20`.

Successful Response

{
  "status": "ok",
  "message": "Transaction successfully initiated",
  "data": {
    "public_id": "6a089a1a-7633-4e4c-b6e6-39da723dd4fa",
    "reference": "TRX-29U3YLYGC8",
    "merchant_reference": "ui79ffjbbnj-fftxnkfffbb12jj345",
    "from_currency": "ngn",
    "to_currency": "usdt",
    "from_amount": "2000.0",
    "to_amount": "1.23",
    "status": "pending",
    "created_at": "2025-05-16T13:17:30.212Z",
    "updated_at": "2025-05-16T13:17:33.292Z",
    "blockchain_fee": "1.0"
  }
}

Successful Response Fields

Field	Type	Description
`status`	string	The API response status. `ok` means the request was successful.
`message`	string	A human-readable message describing the result of the request.
`data`	object	Contains the transaction details.
`data.public_id`	string	The public unique identifier of the on-ramp transaction.
`data.reference`	string	The transaction reference generated by Quidax.
`data.merchant_reference`	string	The unique transaction reference provided by the merchant.
`data.from_currency`	string	The fiat currency the customer is paying with.
`data.to_currency`	string	The cryptocurrency the customer will receive.
`data.from_amount`	string	The fiat amount for the transaction.
`data.to_amount`	string	The estimated amount of cryptocurrency the customer will receive.
`data.status`	string	The current transaction status. `pending` means the transaction has been created but has not been completed.
`data.created_at`	string	The date and time the transaction was created.
`data.updated_at`	string	The date and time the transaction was last updated.
`data.blockchain_fee`	string	The blockchain or network fee applied to the transaction.

Error Responses

Invalid Amount

{
  "status": "bad_request",
  "message": "Invalid amount",
  "data": null
}

Duplicate Transaction

{
  "status": "bad_request",
  "message": "Transaction with reference already exists",
  "data": null
}

Invalid Address Format

{
  "status": "bad_request",
  "message": "Invalid address format",
  "data": null
}

Invalid Network

{
  "status": "bad_request",
  "message": "Invalid network",
  "data": null
}

Forbidden

{
  "status": "forbidden",
  "message": "Invalid private key",
  "data": null
}

2. Refresh an On-Ramp Transaction

This endpoint is used to refresh an existing on-ramp transaction.

You must provide the same merchant_reference that was used when initiating the original on-ramp transaction.

Refreshing the transaction can be used to recalculate the quote or update the transaction amount before confirmation.

Endpoint

PUT https://ramp-be.quidax.io/api/v1/merchants/custodial/on_ramp_transactions/{merchant_reference}/refresh

Replace {merchant_reference} with the merchant reference used when the transaction was created.

Request

curl --request PUT \
     --url https://ramp-be.quidax.io/api/v1/merchants/custodial/on_ramp_transactions/merchant_reference/refresh \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "from_currency": "ngn",
  "to_currency": "usdt",
  "from_amount": "2000"
}
'

Request Body Fields

Field	Type	Required	Description
`from_currency`	string	Yes	The fiat currency the customer is paying with. Example: `ngn`.
`to_currency`	string	Yes	The cryptocurrency the customer wants to receive. Example: `usdt`.
`from_amount`	string	Yes	The updated fiat amount for the transaction.

Successful Response

{
  "status": "ok",
  "message": "Transaction successfully initiated",
  "data": {
    "public_id": "6a089a1a-7633-4e4c-b6e6-39da723dd4fa",
    "reference": "TRX-29U3YLYGC8",
    "merchant_reference": "ui79ffjbbnj-fftxnkfffbb12jj345",
    "from_currency": "ngn",
    "to_currency": "usdt",
    "from_amount": "2000.0",
    "to_amount": "1.23",
    "status": "pending",
    "created_at": "2025-05-16T13:17:30.212Z",
    "updated_at": "2025-05-16T13:17:33.292Z",
    "blockchain_fee": "1.0"
  }
}

Successful Response Fields

Field	Type	Description
`status`	string	The API response status. `ok` means the request was successful.
`message`	string	A human-readable message describing the result of the request.
`data`	object	Contains the refreshed transaction details.
`data.public_id`	string	The public unique identifier of the on-ramp transaction.
`data.reference`	string	The transaction reference generated by Quidax.
`data.merchant_reference`	string	The merchant reference originally provided when the transaction was initiated.
`data.from_currency`	string	The fiat currency the customer is paying with.
`data.to_currency`	string	The cryptocurrency the customer will receive.
`data.from_amount`	string	The refreshed fiat amount for the transaction.
`data.to_amount`	string	The recalculated estimated amount of cryptocurrency the customer will receive.
`data.status`	string	The current transaction status.
`data.created_at`	string	The date and time the transaction was created.
`data.updated_at`	string	The date and time the transaction was last updated.
`data.blockchain_fee`	string	The blockchain or network fee applied to the transaction.

Error Responses

Invalid Currency Pair

{
  "status": "bad_request",
  "message": "Currency swap not allowed: ngn -> usdtg",
  "data": null
}

Failed to Refresh On-Ramp Transaction

{
  "status": "bad_request",
  "message": "Failed to refresh on-ramp transaction",
  "data": null
}

3. Confirm an On-Ramp Transaction

This endpoint is used to confirm an existing on-ramp transaction and generate a dynamic, single-use bank account for the NGN fiat deposit.

The customer must send the exact amount_expected to the generated bank account. Do not send more or less than the expected amount, as overpayment or underpayment will prevent the provider from processing the deposit.

Merchants should inform their customers to send the exact amount_expected. If the customer sends more or less than the expected amount, the payment will be rejected.

Also, ensure that the name on the customer’s bank account used for the fiat deposit matches the name they provided when initiating the transaction. The system does not support third-party deposits. If the names do not match, the system will reject the fiat deposit and issue a refund to the customer.

Endpoint

POST /api/v1/merchants/custodial/on_ramp_transactions/{reference}/confirm

Replace {reference} with the transaction reference to be confirmed.

Request

curl --request POST \
     --url https://ramp-be.quidax.io/api/v1/merchants/custodial/on_ramp_transactions/text-reference/confirm \
     --header 'accept: application/json'

Successful Response

{
  "status": "ok",
  "message": "Transaction successfully confirmed",
  "data": {
    "public_id": "7047c360-4ef6-404d-835d-b41dc832ed49",
    "account_name": "test json",
    "account_number": "0565084270",
    "bank_name": "Test Bank",
    "reference": "BANK_ACCOUNT_8f8102c76be41979",
    "amount": "2000.0",
    "amount_expected": "2053.75",
    "created_at": "2025-05-16T14:12:11.419Z",
    "updated_at": "2025-05-16T14:12:11.419Z",
    "processor_fee": "50.0",
    "vat": "3.75"
  }
}

Successful Response Fields

Field	Type	Description
`status`	string	The API response status. `ok` means the request was successful.
`message`	string	A human-readable message describing the result of the request.
`data`	object	Contains the generated bank account and payment details.
`data.public_id`	string	The public unique identifier for the confirmed transaction or generated payment instruction.
`data.account_name`	string	The account name of the generated dynamic bank account.
`data.account_number`	string	The account number the customer should pay into.
`data.bank_name`	string	The name of the bank where the dynamic account was generated.
`data.reference`	string	The bank account or payment reference generated for the deposit.
`data.amount`	string	The original transaction amount before processor fees and VAT.
`data.amount_expected`	string	The exact total amount the customer must deposit. This includes the original amount, processor fee, and VAT.
`data.created_at`	string	The date and time the bank account or payment instruction was created.
`data.updated_at`	string	The date and time the bank account or payment instruction was last updated.
`data.processor_fee`	string	The payment processor fee added to the transaction.
`data.vat`	string	The VAT charged on the processor fee.

Error Responses

Invalid API Key

{
  "status": "forbidden",
  "message": "Invalid private key",
  "data": null
}

Transaction Not Found

{
  "status": "not_found",
  "message": "Transaction does not exist",
  "data": null
}

4. Requery the Buy Transaction

This endpoint is used to fetch or requery a buy transaction.

Merchants can use this endpoint to confirm the latest status of an on-ramp transaction, especially after receiving a webhook or when they need to verify whether the transaction status has changed.

Webhooks should be used as the source of truth for final transaction status updates. However, merchants can also requery the transaction using this endpoint to confirm the latest transaction status.

Endpoint

GET https://ramp-be.quidax.io/api/v1/merchants/on_ramp_transaction/{reference}

Replace {reference} with the transaction reference you want to fetch.

Request

curl --request GET \
     --url https://ramp-be.quidax.io/api/v1/merchants/on_ramp_transaction/reference \
     --header 'accept: application/json' \
     --header 'x-private-key: sk_test'

Request Header Fields

Header	Required	Description
`accept`	Yes	The response format expected from the API. Use `application/json`.
`x-private-key`	Yes	Your merchant secret key.

Successful Response

{
  "status": "ok",
  "message": "Transaction found",
  "data": {
    "public_id": "11fbee44-eef0-4d27-b21c-b2d0070aa3bb",
    "status": "completed",
    "mode": "buy",
    "from_currency": "ngn",
    "to_currency": "usdc",
    "from_amount": "3000.0",
    "to_amount": "1.927314",
    "network": "solana",
    "merchant_reference": "rhhhhfffbbfffrrrrr",
    "error_message": null,
    "blockchain_fee": "0.025",
    "crypto_payout": {
      "public_id": "656b176e-9e33-48ec-bf8b-b5f119ef05ac",
      "transaction_hash": "5WCENqT47Qs3aGz2yghSvDMYK2KBCmxEShaPWeyiLgP1Y5V7QXRHuQwkFa83HZwUbyUckQV9RUV4WfEaSBhQrrTi",
      "status": "completed",
      "amount": "1.927314",
      "processor_fee": "0.025",
      "address": "FQw1J6qke2JDgjzLmdzeU7mxKgNDePK2Stf81XGpUZog",
      "network": "solana",
      "currency": "usdc",
      "created_at": "2026-05-29T16:57:24.982Z",
      "updated_at": "2026-05-29T16:58:21.729Z"
    },
    "fiat_deposit": {
      "public_id": "d0dbc26b-3937-4d09-87ef-9a1a231d60d1",
      "status": "success",
      "currency": "ngn",
      "amount": "3000.0",
      "fee": "80.63",
      "created_at": "2026-05-29T16:57:19.983Z",
      "updated_at": "2026-05-29T16:57:20.008Z"
    },
    "mobile_money_deposit": null,
    "created_at": "2026-05-29T16:53:50.733Z",
    "updated_at": "2026-05-29T16:58:21.755Z"
  }
}

Successful Response Fields

Field	Type	Description
`status`	string	The API response status. `ok` means the transaction was found.
`message`	string	A human-readable message describing the result of the request.
`data`	object	Contains the on-ramp transaction details.
`data.public_id`	string	The public unique identifier of the on-ramp transaction.
`data.status`	string	The current status of the on-ramp transaction. Example: `completed`.
`data.mode`	string	The transaction mode. For on-ramp transactions, this will be `buy`.
`data.from_currency`	string	The fiat currency the customer paid with. Example: `ngn`.
`data.to_currency`	string	The cryptocurrency the customer received or will receive. Example: `usdc`.
`data.from_amount`	string	The fiat amount for the transaction.
`data.to_amount`	string	The cryptocurrency amount for the transaction.
`data.network`	string	The blockchain network used for the crypto payout.
`data.merchant_reference`	string	The unique transaction reference provided by the merchant.
`data.error_message`	string or null	The error message for the transaction, if any. This will be `null` when there is no error.
`data.blockchain_fee`	string	The blockchain fee charged for the crypto payout.
`data.crypto_payout`	object or null	Contains the crypto payout details. This can be `null` if the payout has not been created yet.
`data.fiat_deposit`	object or null	Contains the fiat deposit details. This can be `null` if no fiat deposit has been received yet.
`data.mobile_money_deposit`	object or null	Contains mobile money deposit details, where applicable. This can be `null` when mobile money was not used.
`data.created_at`	string	The date and time the on-ramp transaction was created.
`data.updated_at`	string	The date and time the on-ramp transaction was last updated.

Crypto Payout Fields

Field	Type	Description
`data.crypto_payout.public_id`	string	The public unique identifier of the crypto payout.
`data.crypto_payout.transaction_hash`	string	The blockchain transaction hash for the crypto payout.
`data.crypto_payout.status`	string	The status of the crypto payout. Example: `completed`.
`data.crypto_payout.amount`	string	The crypto amount sent to the customer.
`data.crypto_payout.processor_fee`	string	The processor fee charged for the crypto payout.
`data.crypto_payout.address`	string	The wallet address where the cryptocurrency was sent.
`data.crypto_payout.network`	string	The blockchain network used for the payout.
`data.crypto_payout.currency`	string	The cryptocurrency sent to the customer.
`data.crypto_payout.created_at`	string	The date and time the crypto payout was created.
`data.crypto_payout.updated_at`	string	The date and time the crypto payout was last updated.

Fiat Deposit Fields

Field	Type	Description
`data.fiat_deposit.public_id`	string	The public unique identifier of the fiat deposit.
`data.fiat_deposit.status`	string	The status of the fiat deposit. Example: `success`.
`data.fiat_deposit.currency`	string	The fiat deposit currency. Example: `ngn`.
`data.fiat_deposit.amount`	string	The fiat amount received from the customer.
`data.fiat_deposit.fee`	string	The fee charged on the fiat deposit.
`data.fiat_deposit.created_at`	string	The date and time the fiat deposit was created.
`data.fiat_deposit.updated_at`	string	The date and time the fiat deposit was last updated.

Error Response

Transaction Not Found

{
  "status": "not_found",
  "message": "Transaction not found",
  "data": null
}

5. On-Ramp Transaction Webhooks

After your customer makes a fiat deposit, the system will send webhook notifications to your configured webhook URL.

These webhooks help you track the transaction from fiat deposit confirmation to crypto payout completion.

You should listen for the following webhook events:

Event	Description
`buy_transaction.processing`	Sent while the transaction is being processed. This can happen after the fiat deposit is received and when the crypto payout is being processed.
`buy_transaction.successful`	Sent when the transaction has been completed successfully.
`buy_transaction.failed`	Sent when the transaction fails or requires attention.

Buy Transaction Processing

This event is dispatched during the transaction processing phase.

It is sent from the moment the system receives and confirms the fiat deposit, through to the initiation and processing of the crypto payout.

Fiat Deposit Processing Webhook

This webhook is sent after the customer’s fiat deposit has been received and confirmed.

At this stage, fiat_deposit will contain the deposit details, while crypto_payout may still be null because the crypto payout has not started yet.

{
  "event": "buy_transaction.processing",
  "data": {
    "mode": "buy",
    "status": "processing",
    "network": "trc20",
    "public_id": "a0f80737-f542-49f2-81dc-303be971839e",
    "to_amount": "1.85",
    "created_at": "2025-04-14T08:41:12.696Z",
    "updated_at": "2025-04-15T17:39:59.837Z",
    "from_amount": "3000.0",
    "to_currency": "usdt",
    "fiat_deposit": {
      "fee": "9.99",
      "amount": "9.99",
      "status": "success",
      "currency": "ngn",
      "public_id": "ffbd4fc9-ed12-4df4-91b9-869c097990fc",
      "created_at": "2025-04-15T17:35:58.120Z",
      "updated_at": "2025-04-15T17:35:58.120Z"
    },
    "crypto_payout": null,
    "from_currency": "ngn",
    "blockchain_fee": "1.0",
    "merchant_reference": "usebr-gtextccnv"
  }
}

Crypto Payout Processing Webhook

This webhook is sent when the fiat deposit has been confirmed and the crypto payout is being processed.

At this stage, both fiat_deposit and crypto_payout will be present in the webhook payload.

{
  "event": "buy_transaction.processing",
  "data": {
    "mode": "buy",
    "status": "processing",
    "network": "trc20",
    "public_id": "a0f80737-f542-49f2-81dc-303be971839e",
    "to_amount": "1.85",
    "created_at": "2025-04-14T08:41:12.696Z",
    "updated_at": "2025-04-15T17:39:59.837Z",
    "from_amount": "3000.0",
    "to_currency": "usdt",
    "fiat_deposit": {
      "fee": "9.99",
      "amount": "9.99",
      "status": "success",
      "currency": "ngn",
      "public_id": "ffbd4fc9-ed12-4df4-91b9-869c097990fc",
      "created_at": "2025-04-15T17:35:58.120Z",
      "updated_at": "2025-04-15T17:35:58.120Z"
    },
    "crypto_payout": {
      "amount": "9.99",
      "status": "processing",
      "address": "0xfjjkfjnmfn",
      "network": "trc20",
      "currency": "usdt",
      "public_id": "0594ea31-8d0b-4691-8b95-b4ae9057ab1b",
      "created_at": "2025-04-15T17:37:37.125Z",
      "updated_at": "2025-04-15T17:37:37.125Z",
      "processor_fee": 1,
      "transaction_hash": "xdkkdlf"
    },
    "from_currency": "ngn",
    "blockchain_fee": "1.0",
    "merchant_reference": "usebr-gtextccnv"
  }
}

Buy Transaction Successful

This event is dispatched when the transaction has been completed successfully.

At this stage, the fiat deposit has been received, the crypto payout has been completed, and the transaction status will be completed.

{
  "event": "buy_transaction.successful",
  "data": {
    "mode": "buy",
    "status": "completed",
    "network": "trc20",
    "public_id": "a0f80737-f542-49f2-81dc-303be971839e",
    "to_amount": "1.85",
    "created_at": "2025-04-14T08:41:12.696Z",
    "updated_at": "2025-04-15T17:39:59.837Z",
    "from_amount": "3000.0",
    "to_currency": "usdt",
    "fiat_deposit": {
      "fee": "9.99",
      "amount": "9.99",
      "status": "success",
      "currency": "ngn",
      "public_id": "ffbd4fc9-ed12-4df4-91b9-869c097990fc",
      "created_at": "2025-04-15T17:35:58.120Z",
      "updated_at": "2025-04-15T17:35:58.120Z"
    },
    "crypto_payout": {
      "amount": "9.99",
      "status": "completed",
      "address": "0xfjjkfjnmfn",
      "network": "trc20",
      "currency": "usdt",
      "public_id": "0594ea31-8d0b-4691-8b95-b4ae9057ab1b",
      "created_at": "2025-04-15T17:37:37.125Z",
      "updated_at": "2025-04-15T17:37:37.125Z",
      "processor_fee": 1,
      "transaction_hash": "xdkkdlf"
    },
    "from_currency": "ngn",
    "blockchain_fee": "1.0",
    "merchant_reference": "usebr-gtextccnv"
  }
}

Buy Transaction Failed

This event is dispatched when the transaction fails or requires attention.

This can happen after the fiat deposit has been received but the crypto payout fails. or fiat deposit faile, In this case, the transaction status may be needs_attention, and the crypto_payout.status will be failed.

{
  "event": "buy_transaction.failed",
  "data": {
    "mode": "buy",
    "status": "needs_attention",
    "network": "trc20",
    "public_id": "a0f80737-f542-49f2-81dc-303be971839e",
    "to_amount": "1.85",
    "created_at": "2025-04-14T08:41:12.696Z",
    "updated_at": "2025-04-15T17:39:59.837Z",
    "from_amount": "3000.0",
    "to_currency": "usdt",
    "fiat_deposit": {
      "fee": "9.99",
      "amount": "9.99",
      "status": "success",
      "currency": "ngn",
      "public_id": "ffbd4fc9-ed12-4df4-91b9-869c097990fc",
      "created_at": "2025-04-15T17:35:58.120Z",
      "updated_at": "2025-04-15T17:35:58.120Z"
    },
    "crypto_payout": {
      "amount": "9.99",
      "status": "failed",
      "address": "0xfjjkfjnmfn",
      "network": "trc20",
      "currency": "usdt",
      "public_id": "0594ea31-8d0b-4691-8b95-b4ae9057ab1b",
      "created_at": "2025-04-15T17:37:37.125Z",
      "updated_at": "2025-04-15T17:37:37.125Z",
      "processor_fee": 1,
      "transaction_hash": "xdkkdlf"
    },
    "from_currency": "ngn",
    "blockchain_fee": "1.0",
    "merchant_reference": "usebr-gtextccnv"
  }
}

Webhook Response Fields

Main Payload Fields

Field	Type	Description
`event`	string	The webhook event name. Possible values include `buy_transaction.processing`, `buy_transaction.successful`, and `buy_transaction.failed`.
`data`	object	Contains the transaction details.
`data.mode`	string	The transaction mode. For on-ramp transactions, this will be `buy`.
`data.status`	string	The current status of the on-ramp transaction.
`data.network`	string	The blockchain network for the crypto payout.
`data.public_id`	string	The public unique identifier of the on-ramp transaction.
`data.to_amount`	string	The amount of cryptocurrency the customer is expected to receive.
`data.created_at`	string	The date and time the on-ramp transaction was created.
`data.updated_at`	string	The date and time the on-ramp transaction was last updated.
`data.from_amount`	string	The fiat amount for the on-ramp transaction.
`data.to_currency`	string	The cryptocurrency the customer will receive.
`data.fiat_deposit`	object	Contains details of the fiat deposit.
`data.crypto_payout`	object or null	Contains details of the crypto payout. This can be `null` when the crypto payout has not started.
`data.from_currency`	string	The fiat currency used for the deposit.
`data.blockchain_fee`	string	The blockchain fee for the crypto payout.
`data.merchant_reference`	string	The unique transaction reference provided by the merchant when the transaction was initiated.

Fiat Deposit Fields

Field	Type	Description
`data.fiat_deposit.fee`	string	The fee charged on the fiat deposit.
`data.fiat_deposit.amount`	string	The fiat deposit amount received.
`data.fiat_deposit.status`	string	The status of the fiat deposit. Example: `success`.
`data.fiat_deposit.currency`	string	The fiat deposit currency. Example: `ngn`.
`data.fiat_deposit.public_id`	string	The public unique identifier of the fiat deposit.
`data.fiat_deposit.created_at`	string	The date and time the fiat deposit was created.
`data.fiat_deposit.updated_at`	string	The date and time the fiat deposit was last updated.

Crypto Payout Fields

Field	Type	Description
`data.crypto_payout.amount`	string	The crypto payout amount.
`data.crypto_payout.status`	string	The status of the crypto payout. Examples: `processing`, `completed`, or `failed`.
`data.crypto_payout.address`	string	The wallet address where the cryptocurrency is being sent.
`data.crypto_payout.network`	string	The blockchain network used for the payout.
`data.crypto_payout.currency`	string	The cryptocurrency being sent.
`data.crypto_payout.public_id`	string	The public unique identifier of the crypto payout.
`data.crypto_payout.created_at`	string	The date and time the crypto payout was created.
`data.crypto_payout.updated_at`	string	The date and time the crypto payout was last updated.
`data.crypto_payout.processor_fee`	number or string	The processor fee charged for the crypto payout.
`data.crypto_payout.transaction_hash`	string	The blockchain transaction hash for the crypto payout.

General API Response Structure

All API responses follow this structure:

{
  "status": "ok",
  "message": "Human-readable response message",
  "data": {}
}

General Response Fields

Field	Type	Description
`status`	string	Indicates the result of the request. Possible values include `ok`, `bad_request`, `forbidden`, and `not_found`.
`message`	string	A human-readable explanation of the result.
`data`	object or null	Contains response data when the request is successful. For errors, this is usually `null`.

Common Status Values

Status	Meaning
`ok`	The request was successful.
`bad_request`	The request was invalid, incomplete, duplicated, or could not be processed.
`forbidden`	Authentication failed, usually because the private key is invalid.
`not_found`	The requested transaction could not be found.

Important Integration Notes

Always generate a unique merchant_reference when creating a new on-ramp transaction.
Save both the merchant reference and the Quidax transaction reference returned in the response.
Use the same merchant_reference when refreshing an existing transaction.
Confirm the transaction only when the customer is ready to make payment.
After confirmation, instruct the customer to pay the exact amount_expected.
Do not allow overpayment or underpayment. Merchants should inform their customers to send the exact amount_expected. If the customer sends more or less than the expected amount, the payment will be rejected.
Ensure that the name on the customer’s bank account matches the name used when initiating the transaction.
The system does not support third-party deposits. If the names do not match, the system will reject the fiat deposit and issue a refund to the customer.
Validate the wallet address and network before creating the transaction.
Ensure the selected currency pair is supported before calling the API.
Store the public_id, reference, merchant_reference, and transaction status for reconciliation and support purposes.
Use webhooks as the source of truth for final transaction status updates.
Merchants can also requery the buy transaction using the Fetch On-Ramp Transaction endpoint to confirm the latest transaction status.