Skip to main content

​
Overview

Custodial corridor remittance is separate from the P2P-style POST /api/v1/auth/remittance/off-ramp/orders path. The customer already holds USDT or USDC in a custodial platform wallet. They enter how much KES the beneficiary should receive. The app resolves pricing and FX. The backend creates a draft with a unique escrow address. On Confirm, the server creates an order with order_subtype = custodial_remittance_offramp, then broadcasts the priced stablecoin (USDT or USDC) from the custodial wallet to that escrow. After confirmations, mobile money B2C pays beneficiary_phone.

​
Prerequisites

  1. Run database migration 000031_corridors_custodial_remittance on your environment.
  2. Create offramp pricing_profiles and fx_rate_quotes for USDT or USDC (paired with KES) on the sender network (for example tron).
  3. fiat_currency values must reference an active row in the shared fiat_currencies table. Enumerate allowed codes with GET /api/v1/auth/fiat-currencies (same catalog OTC and other products use).

​
Mobile sequence

  1. POST /api/v1/auth/pricing/resolve or POST /api/v1/auth/pricing/fx-quotes (and profiles) as you do today — obtain pricing_profile_id and fx_rate_quote_id for flow_type = offramp.
  2. POST /api/v1/auth/remittance/custodial/drafts — body includes custodial_wallet_id, beneficiary_fiat_amount, fiat_currency, beneficiary and sender KYC fields, fee_bearer, and the pricing IDs. The response includes usdt_total_debit (total stablecoin debit for USDT- or USDC-priced flows. Field name is historical) and escrow_wallet_address for the summary screen.
  3. POST /api/v1/auth/remittance/custodial/drafts/{id}/confirm — empty JSON body is fine. The server creates the order and submits the on-chain transfer from the custodial wallet to the draft escrow.
Drafts expire after REMITTANCE_DRAFT_EXPIRY_MINUTES (default 15 minutes). If the chain send fails, the order may move to failed while the draft stays draft with a linked order_id. A second confirm retries the transfer for the same order.

​
Order shape

Confirmed orders use order_type = OFF_RAMP_SELL, payment_method = custodial_remittance_escrow, and order_subtype = custodial_remittance_offramp. Payout orchestration uses beneficiary_phone for mobile money, same as remittance_offramp. See Orders and payments for standard off-ramp and the listing-based remittance endpoint. See Pricing and FX for quote-backed enforcement.