Ramp Partner developer API errors

Fetch Off Ramp Transaction

Documentation: Fetch Off Ramp Transaction.

Endpoint: GET /api/v1/merchants/off_ramp_transaction/:reference.

reference identifies the merchant_reference supplied at initiation, rather than an internal transaction identifier. A successful response can contain a transaction failure reason in data.error_message; see Introduction.

Fetch On Ramp Transaction

Documentation: Fetch On Ramp Transaction.

Endpoint: GET /api/v1/merchants/on_ramp_transaction/:reference.

reference identifies the merchant_reference supplied at initiation, rather than an internal transaction identifier. A successful response can contain a transaction failure reason in data.error_message; see Introduction.

Payment Methods

Documentation: Payment Methods.

Endpoint: GET /api/v1/merchants/payment_methods.

Send currency and side as query parameters. No default currency or side is applied.

Purchase Limits (BUY)

Documentation: Purchase Limits (BUY).

Endpoint: GET /api/v1/merchants/purchase_limits/buy.

Send currency_symbol as a query parameter. Supported values are ngn and ghs. Supply the parameter explicitly; omission does not guarantee a fixed validation response.

Purchase Limit (SELL)

Documentation: Purchase Limit (SELL).

Endpoint: GET /api/v1/merchants/purchase_limits/sell.

Send token_symbol as a query parameter. This endpoint accepts usdt and usdc. The linked reference also lists xaut/usat, which are not accepted by this endpoint. Supply the parameter explicitly; omission does not guarantee a fixed validation response.

Purchase Quotes (BUY)

Documentation: Purchase Quotes (BUY).

Endpoint: GET /api/v1/merchants/purchase_quotes/buy.

Use GET for this endpoint; the linked reference currently shows POST. Send currency, token, fiat_amount, and token_network as query parameters. A blockchain payout requires a network and blockchain fee. The amount is checked against your app’s applicable transaction limits.

Purchase Quotes (SELL)

Documentation: Purchase Quotes (SELL).

Endpoint: GET /api/v1/merchants/purchase_quotes/sell.

Send token, currency, token_amount, and token_network as query parameters. Blockchain transactions require a supported currency/network combination. The amount is checked against your app’s applicable transaction limits.

Fetch On Ramp Transactions

Documentation: Fetch On Ramp Transactions.

Endpoint: GET /api/v1/merchants/on_ramp_transactions.

No matching transactions returns a successful empty list. Blank pagination parameters use defaults; per_page is capped at 50. Accepts completed, pending, failed, and supported transaction lifecycle statuses. Error responses include status even where the linked examples omit it.

Fetch Off Ramp Transactions

Documentation: Fetch Off Ramp Transactions.

Endpoint: GET /api/v1/merchants/off_ramp_transactions.

No matching transactions returns a successful empty list. Blank pagination parameters use defaults; per_page is capped at 50. Accepts completed, pending, failed, and supported transaction lifecycle statuses. Error responses include status even where the linked examples omit it.

CUSTODIAL

Introduction

Documentation: Introduction.

Errors usually return JSON like this: {"status":"bad_request","message":"Invalid amount","data":null}. The tables show the HTTP status, exact API message, and what caused it.

Validation messages can be text, such as customer first_name is missing, or an object, such as {"phone_number":["is missing"]}. Several field errors can appear together. Nested field names use spaces and keep underscores. Send all required fields with the correct types; whitespace-only values may still be rejected. Optional nullable fields accept null.

Placeholders such as <exception_message> or <remaining_amount> change with the request. The amount placeholders use decimal numbers; currency placeholders are uppercase. Some provider errors and unexpected failures have no fixed message or response format.

Rate limits, when active, allow 600 merchant requests per API key per minute and 1,000 API requests per IP per minute. A 429 response includes Retry-After: wait that many seconds before retrying. Five invalid keys within 5 minutes block the IP for 1 hour. These checks can run before authentication.

A successful request does not mean the transaction is complete. Check transaction status and webhooks. A transaction query may return HTTP 200 with data.error_message describing a failed, cancelled, or needs_attention transaction. Messages include We had an issue processing the swap. Please contact support., We couldn’t complete the payout. Please contact support., Depositor name doesn’t match the account name., and We couldn’t complete this right now. Please contact support.

For mobile-money payments, HTTP 400 with message: {"error":"UNKNOWN_AUTH_MODEL"} means the provider returned an unsupported payment step. Read the error from message.error.

Initiate On Ramp Transaction

Documentation: Initiate On Ramp Transaction.

Endpoint: POST /api/v1/merchants/custodial/on_ramp_transactions/initiate.

Send complete transaction and customer details. Missing fields may have no fixed error message. Blockchain payout needs a wallet address. This endpoint does not accept destination_tag.

Refresh On Ramp Transaction

Documentation: Refresh On Ramp Transaction.

Endpoint: PUT /api/v1/merchants/custodial/on_ramp_transactions/:transaction_ref/refresh.

Use the original merchant reference and currencies. Send from_currency, to_currency, and from_amount. A missing transaction returns 400. Amount limits apply; daily usage is not checked again.

Initiate GHS Momo deposit

Documentation: Initiate GHS Momo deposit.

Endpoint: POST /api/v1/merchants/custodial/on_ramp_transactions/initiate_mobile_money.

Send merchant_reference, phone_number, and network_provider. Supported institution names include MTN, AIRTEL, and VODAFONE. An unknown institution returns Invalid bank code. The customer may then need to enter a PIN or OTP.

Validation fields: merchant_reference, phone_number, network_provider.

Verify Mobile Money Otp

Documentation: Verify Mobile Money Otp.

Endpoint: POST /api/v1/merchants/custodial/on_ramp_transactions/verify_mobile_money_otp.

Send merchant_reference and token. The linked reference uses otp, but sending only otp returns {"token":["is missing"]}. A missing transaction returns 404. This action does not check daily usage again.

Validation fields: merchant_reference, token.

Confirm On Ramp Transaction

Documentation: Confirm On Ramp Transaction.

Endpoint: POST /api/v1/merchants/custodial/on_ramp_transactions/:reference/confirm.

Use the original merchant_reference in the URL. If you also send merchant_reference in the request, keep it identical to the URL reference. This endpoint also returns the HTTP 400 failures below, although the linked reference lists only 403/404.

Initiate Off Ramp Transaction

Documentation: Initiate Off Ramp Transaction.

Endpoint: POST /api/v1/merchants/custodial/off_ramp_transactions/initiate.

Send currencies, amount, merchant reference, network, and customer details. Use a supported currency/network combination for the crypto deposit. A nonnumeric amount may return Unexpected error rather than Invalid amount.

Validation fields: from_currency, to_currency, from_amount, merchant_reference, customer email, customer first_name, customer last_name.

Refresh Off Ramp Transaction

Documentation: Refresh Off Ramp Transaction.

Endpoint: PUT /api/v1/merchants/custodial/off_ramp_transactions/:transaction_ref/refresh.

Use PUT with the original merchant_reference in the URL. Keep both currencies unchanged and provide from_currency, to_currency, and from_amount. Validation occurs before transaction lookup; a missing transaction returns HTTP 400.

Validation fields: from_currency, to_currency, from_amount.

Confirm Off Ramp Transaction

Documentation: Confirm Off Ramp Transaction.

Endpoint: POST /api/v1/merchants/custodial/off_ramp_transactions/:transaction_ref/confirm.

Use the original merchant reference in the URL. Missing transactions return 400; invalid keys return 403. Confirmation generates or reuses a crypto deposit address for the selected currency and network.

Banks Off Ramp

Documentation: Banks Off Ramp.

Endpoint: GET /api/v1/merchants/custodial/banks.

country defaults to NG. An unsupported or blank country returns a successful empty list. Unexpected retrieval failures have no fixed message.

Add Bank Account Offramp

Documentation: Add Bank Account Offramp.

Endpoint: POST /api/v1/merchants/custodial/off_ramp_transactions/:transaction_ref/bank_account.

Use the original merchant_reference in the URL. Send account_number and bank_code; currency_code defaults to ngn. The resolved account name must match the customer’s name. The linked Failed to create account example is not a fixed error message for this endpoint.

Validation fields: account_number, bank_code, currency_code.

Verify a bank account

Documentation: Verify a bank account.

Endpoint: POST /api/v1/merchants/refunds/:reference/verify_account.

Use the original buy transaction’s merchant_reference to verify the bank account details. currency_code defaults to ngn.

Validation fields: account_number, bank_code. Optional nullable strings: currency_code.

Create an Auto Swap

Auto Swap returns a static bank account for a customer. Each eligible deposit into that account automatically starts a crypto purchase and sends the crypto to the configured wallet.

Documentation: Create an Auto Swap.

Endpoint: POST https://ramp-be.quidax.io/api/v1/merchants/custodial/auto_swap/initiate_onramp.

Send a JSON body containing customer, coin_deposit, and bank_account. merchant_reference is optional; if supplied, it must be a nonempty string unique to this setup within your app. Repeating the same customer, fiat currency, crypto destination, and direction returns the existing Auto Swap and static bank account. A reference can be attached to an existing setup that has none; an assigned reference cannot be replaced through this endpoint. This endpoint does not accept a destination tag or memo.

Validation fields: customer email, customer first_name, customer last_name, coin_deposit address, coin_deposit network, coin_deposit currency, bank_account bvn, bank_account bank_code, and bank_account currency. All are required strings. Validation errors are returned as a string in message; multiple errors can be joined with commas.

Success response: HTTP 200, status: "ok", and message: "Auto swap successfully created". data contains the complete Auto Swap object, including customer and static bank account details.

HTTP 400 — multiple validation errors:

{
  "status": "bad_request",
  "message": "customer email is missing, customer first_name must be filled",
  "data": null
}

HTTP 400 — merchant reference conflict:

{
  "status": "bad_request",
  "message": "Auto swap already exists with a different merchant reference",
  "data": null
}

HTTP 429 — request rate exceeded:

Read the Retry-After response header and wait that many seconds before retrying. For example, Retry-After: 60 accompanies this body:

{
  "status": "too_many_requests",
  "message": "Too many requests. Try again later.",
  "data": null
}

List Auto Swaps

Return your app's Auto Swaps, including each customer's details and static bank account.

Documentation: List Auto Swaps.

Endpoint: GET https://ramp-be.quidax.io/api/v1/merchants/custodial/auto_swaps.

Optional query parameters: currency, start_date, end_date, page, and per_page. currency filters by the fiat deposit currency. Supply both dates together in YYYY-MM-DD format. page must be a positive integer no greater than 1,000,000. per_page defaults to 25 and is capped at 50.

Success response: HTTP 200, status: "ok", and message: "Auto swaps fetched successfully". data is an array of complete Auto Swap objects, with pagination in meta. No matches returns an empty array.

HTTP 400 — invalid page:

{
  "status": "bad_request",
  "message": "page must be a positive integer",
  "data": null
}

Retrieve an Auto Swap

Return one Auto Swap using its merchant reference, including the customer's details and static bank account.

Documentation: Retrieve an Auto Swap.

Endpoint: GET https://ramp-be.quidax.io/api/v1/merchants/custodial/auto_swap/{merchant_reference}.

Use the setup's merchant_reference, URL-encoded in the path. The setup must belong to the app identified by your private key. An unknown reference or one belonging to another app returns HTTP 404. Unexpected server failures can have a variable response body.

Success response: HTTP 200, status: "ok", and message: "Auto swap found". data is the complete Auto Swap object.

HTTP 404 — setup not found:

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

List an Auto Swap's transactions

Return the crypto purchase transactions created from deposits into an Auto Swap's static bank account, including their status, converted amounts, and payout details.

Documentation: List an Auto Swap's transactions.

Endpoint: GET https://ramp-be.quidax.io/api/v1/merchants/custodial/auto_swap/{merchant_reference}/transactions.

Optional query parameters: status, from_currency, to_currency, start_date, end_date, page, and per_page. Use the setup's merchant reference in the URL; each buy transaction has a separately generated merchant reference. The setup is checked before filters. Supply both dates together, and use positive integers for pagination; per_page defaults to 25 and is capped at 50.

The grouped filters are completed, pending (includes pending, processing, failed_aml, needs_attention, swap_reversed, and assigned_bank_account), and failed (includes failed, abandoned, cancelled, and account_expired). Individual statuses such as processing and needs_attention are also accepted. Use lowercase values.

Success response: HTTP 200, status: "ok", and message: "Auto swap transactions fetched successfully". data contains complete transaction objects, including the nested Auto Swap, deposit details, and payout details when available. Pagination is in meta; no matches returns an empty array.

HTTP 400 — unsupported status:

{
  "status": "bad_request",
  "message": "status is invalid",
  "data": null
}

HTTP 404 — setup not found:

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

HTTP 200 can include a transaction whose status is needs_attention or failed. Inspect each record's status and error_message to determine the payment outcome.

List rejected Auto Swap deposits

Return deposits into your app's Auto Swap static bank accounts that could not proceed with a crypto purchase. Each record includes its amount, rejection reason, and resolution status.

Documentation: List rejected Auto Swap deposits.

Endpoint: GET https://ramp-be.quidax.io/api/v1/merchants/custodial/auto_swap/rejected_deposits.

Optional query parameters: status, currency, start_date, end_date, page, and per_page. status filters by the deposit’s resolution state; currency filters by the fiat deposit currency. Supply both dates together. page must be a positive integer no greater than 1,000,000; per_page defaults to 25 and is capped at 50.

Success response: HTTP 200, status: "ok", and message: "Rejected auto swap deposits fetched successfully". data is an array of complete rejected deposit objects, with pagination in meta. No matches returns an empty array.

HTTP 400 — unsupported rejected deposit status:

{
  "status": "bad_request",
  "message": "status is invalid",
  "data": null
}

Rejected deposits are separate from buy transaction history. auto_swap.deposit.rejected reports a rejected deposit.

Retrieve a rejected Auto Swap deposit

Return one rejected Auto Swap deposit by its public ID, including the payment details, rejection reason, and resolution status.

Documentation: Retrieve a rejected Auto Swap deposit.

Endpoint: GET https://ramp-be.quidax.io/api/v1/merchants/custodial/auto_swap/rejected_deposits/{public_id}.

Use the rejected deposit's public_id, rather than the Auto Swap ID or a buy transaction ID. The record must belong to your app. Unexpected server failures can have a variable response body.

Success response: HTTP 200, status: "ok", and message: "Rejected auto swap deposit found". data includes public_id, status, reason, amount, currency, deposit_reference, auto_swap_public_id, customer_email, account_number, created_at, and updated_at. The amount is a decimal string.

HTTP 404 — rejected deposit not found:

{
  "status": "not_found",
  "message": "Rejected auto swap deposit not found",
  "data": null
}