Withdrawals

Convert USD stablecoins to local African currencies using Direct Ramp withdrawals. This guide covers the complete withdrawal lifecycle, from initiation to settlement.

Withdrawal Flow

1. Get a valid ramp quote

2. Initiate withdrawal with quote

3. Wait for withdrawal to be processed

4. Mark withdrawal as received

Initiating a Withdrawal

Use initiateRampQuoteWithdrawal to create a new withdrawal request.

Arguments

Argument	Type	Required	Description
rampQuote	ID!	Yes	Quote ID from rampQuote query
paymentMethod	ID!	Yes	Your customer's payment method ID (Add a Payment Method)
reference	String	No	Your unique reference for reconciliation

mutation {
  initiateRampQuoteWithdrawal(
    rampQuote: "quote_id"
    paymentMethod: "payment_method_id"
    reference: "order_123"
  ) {
    id
    status
    agent
    paymentDetails
    exchangeRate
    amountUsd
    amountLocal
  }
}

Response

Field	Type	Description
id	ID!	Global ID for the deposit request
status	String!	Current status (see Status Lifecycle)
agent	String!	Assigned payout agent
paymentDetails	String!	User's payout instructions (bank details, mobile money number)
exchangeRate	Decimal!	Locked FX rate for this withdrawal
amountLocal	Decimal!	Amount in local currency
amountUsd	Decimal!	Amount in USD stablecoins

Status Lifecycle

Status	Description	Next Steps
accepted	Initial state	Awaiting payout
paid	Local currency payout completed	Customer received funds
completed	Transaction settled	-
canceled	Manually canceled	-

Marking as Received

Use markWithdrawalAsReceived to allow your customer to indicate that they have received the funds.

We recommend adding a "I've received the payment" button which triggers markWithdrawalAsReceived .

Arguments

Argument	Type	Required	Description
paymentRequest	ID!	Yes	Withdrawal request ID

mutation {
  markWithdrawalAsReceived(paymentRequest: "withdrawal_id")
}