Deposits

Convert local African currency payments into USD stablecoins using Direct Ramp deposits. This guide covers the complete deposit lifecycle, from initiation to settlement.

Deposit Flow

1. Get a valid ramp quote

2. Initiate deposit with quote

3. Share payment details with customer

4. Mark deposit as paid

5. Receive stablecoin settlement

Initiating a Deposit

Use initiateRampQuoteDeposit to create a new deposit request.

Arguments

Argument	Type	Required	Description
rampQuote	ID!	Yes	Quote ID from rampQuote query
reference	String	No	Your unique reference for reconciliation
phoneNumber	String	No	Customer's phone number if paying via MoMo
bankAccountNumber	String	No	Customer's bank account number if paying via bank
onchainTransferInfo	OnchainTransferInfo	No	If you want to deliver the stablecoins onchain, provide address, cryptocurrency, network

mutation {
  initiateRampQuoteDeposit(rampQuote: "quote_id", reference: "order_123", phoneNumber: "", bankAccountNumber: "", onchainTransferInfo: { address: "0x1234567890abcdef1234567890abcdef12345678", cryptocurrency: "usd_tether", network: "celo" }) {
    id
    status
    agent
    paymentDetails
    exchangeRate
    amountLocal
    amountUsd
    expiresAt
  }
}

Provide your customer's payment method information (phone number for MoMo payments or bank account number for bank transfers) to help our agents quickly verify and confirm payments.

Response

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

Status Lifecycle

Status	Description	Next Steps
pending	Initial state	Share payment details with customer
paid	Customer funds transferred & marked as paid	Await settlement
completed	Funds settled	-
canceled	Manually canceled	-

Marking as Paid

After your customer transfers the local currency to the payment instructions we provide, use the markDepositAsPaid mutation to begin the settlement process.

We recommend adding an "I've made the payment" button which triggers markDepositAsPaid.

Arguments

Argument	Type	Required	Description
paymentRequest	ID!	Yes	Deposit request ID
receipt	String	No	Payment proof URL

mutation {
  markDepositAsPaid(
    paymentRequest: "deposit_id"
    receipt: "https://example.com/receipt.png"
  )
}

Cancelling a Deposit

Cancel an initiated but unpaid deposit with cancelDeposit (only possible if the status is created).

mutation {
  cancelDeposit(paymentRequest: "deposit_id")
}