> ## Documentation Index > Fetch the complete documentation index at: https://docs.platform.chipper.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an order > Collect on one rail and pay out on another in a single call — e.g. take USDC on Solana and deliver GHS to an MTN mobile money wallet. Give the amount on exactly one side: `to.amount` ("deliver exactly this much") or `from.amount` ("the customer sends exactly this much"); cross-currency orders lock the live rate at creation. The response carries `instructions` telling the customer where to send funds (a deposit address, a virtual account, or a mobile money prompt); the payout fires automatically once funds land. `externalReference` is your idempotency key: an identical retry returns the original order with 200, a retry with different from/to details is rejected with 409. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/orders openapi: 3.1.0 info: title: Chipper Platform API version: '2026-02-20' description: >- Payouts, collections, and FX across African rails — bank, mobile money, and stablecoins — through one API. servers: - url: https://api.platform.chipper.ai description: Production (sk_live_ keys) - url: https://sandbox-api.platform.chipper.ai description: Sandbox (sk_test_ keys — simulated rails, no real money) security: - bearerAuth: [] paths: /v1/orders: post: tags: - Orders summary: Create an order description: >- Collect on one rail and pay out on another in a single call — e.g. take USDC on Solana and deliver GHS to an MTN mobile money wallet. Give the amount on exactly one side: `to.amount` ("deliver exactly this much") or `from.amount` ("the customer sends exactly this much"); cross-currency orders lock the live rate at creation. The response carries `instructions` telling the customer where to send funds (a deposit address, a virtual account, or a mobile money prompt); the payout fires automatically once funds land. `externalReference` is your idempotency key: an identical retry returns the original order with 200, a retry with different from/to details is rejected with 409. requestBody: content: application/json: schema: type: object properties: from: type: object properties: code: type: string minLength: 1 accountNumber: type: string minLength: 1 maxLength: 100 amount: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d+)?$ currency: type: string minLength: 2 maxLength: 10 kyc: type: object additionalProperties: {} required: - code - currency to: type: object properties: code: type: string minLength: 1 accountNumber: type: string minLength: 1 maxLength: 100 tag: type: string maxLength: 100 amount: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^\d+(\.\d+)?$ currency: type: string minLength: 2 maxLength: 10 kyc: type: object additionalProperties: {} required: - code - accountNumber - currency externalReference: type: string minLength: 1 maxLength: 100 narration: type: string maxLength: 200 metadata: type: object additionalProperties: {} required: - from - to - externalReference responses: '200': description: >- Idempotent replay — this externalReference was already used with the same intent, the original order is returned. content: application/json: schema: type: object properties: order: $ref: '#/components/schemas/Order' required: - order '201': description: The order was created and is awaiting funds. content: application/json: schema: type: object properties: order: $ref: '#/components/schemas/Order' required: - order '400': description: Invalid request — the body failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: validation_error message: Request validation failed requestId: req_q7vei435zifs51ia0lqr '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: Invalid API key requestId: req_q7vei435zifs51ia0lqr '403': description: The API key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: forbidden message: API key does not have the required scope requestId: req_q7vei435zifs51ia0lqr '409': description: >- This externalReference was already used with different from/to details. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: duplicate message: Order with this externalReference already exists requestId: req_q7vei435zifs51ia0lqr security: - bearerAuth: [] components: schemas: Order: type: object properties: id: type: string example: ord_p95akjfs339uy9icpelj status: type: string enum: - created - awaiting_funds - awaiting_confirmations - funds_received - overpaid - underpaid - processing_payout - completed - failed - expired description: >- awaiting_funds → awaiting_confirmations (crypto only) → funds_received → processing_payout → completed. Terminal: completed, failed, expired. overpaid / underpaid: the deposit did not match `expectedAmount`. from: type: object properties: code: type: string description: Payment method the customer pays with. example: usdc_solana accountNumber: type: - string - 'null' description: >- Mobile money orders: the customer phone number being charged. Bank orders: the virtual account number to transfer into. bank: type: - string - 'null' description: 'Bank orders only: the bank holding the virtual account.' address: type: - string - 'null' description: 'Crypto orders only: the deposit address.' example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU tag: type: string description: 'Crypto orders on Stellar/Ripple: memo the sender must include.' chain: type: - string - 'null' description: Crypto orders only. example: Solana amount: type: string description: Decimal string — never parse as float for arithmetic. example: '100.00' currency: type: string example: USDC kyc: type: object additionalProperties: {} description: Sender KYC you supplied, echoed back. required: - code - amount - currency to: type: object properties: code: type: string description: Payment method the recipient is paid on. example: gh_mtn accountNumber: type: string example: '233559630374' tag: type: string description: Memo/tag for crypto destinations that require one. amount: type: string description: Decimal string — never parse as float for arithmetic. example: '1598.00' currency: type: string example: GHS kyc: type: object additionalProperties: {} description: >- Recipient KYC; `accountName` is the validated holder name where the rail supports lookup. required: - code - accountNumber - amount - currency fee: type: - object - 'null' properties: amount: type: string description: Decimal string — never parse as float for arithmetic. example: '1.00' currency: type: string example: USDC required: - amount - currency description: Charged in the origin currency on top of `from.amount`. rate: type: - string - 'null' description: >- FX rate locked at creation for cross-currency orders, null otherwise. example: '15.9800' instructions: type: - object - 'null' properties: type: type: string enum: - crypto - virtual_account - mobile_money message: type: string description: Ready to show the customer verbatim. example: >- Send 101.00 USDC on Solana to 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU amount: type: string description: Total the customer must send — `from.amount` plus fee. example: '101.00' currency: type: string example: USDC address: type: - string - 'null' description: crypto tag: type: string description: crypto (Stellar/Ripple) chain: type: string description: crypto example: Solana bank: type: - string - 'null' description: virtual_account accountNumber: type: - string - 'null' description: virtual_account accountName: type: - string - 'null' description: virtual_account required: - type - message - amount - currency description: >- What to tell the customer to do. Null once the order has failed before provisioning. expectedAmount: type: string description: 'What the customer must send: `from.amount` + fee.' example: '101.00' receivedAmount: type: - string - 'null' description: What actually arrived. Null until funds land. example: '101.00' collectionId: type: - string - 'null' description: The money-in leg, once created. example: col_x7kd92mfn3qp8wz4t6vb payoutId: type: - string - 'null' description: The money-out leg, once funds are received. example: pay_ghs_p95akjfs339uy9icpelj externalReference: type: string description: >- Your idempotency key — retries with the same value and intent replay the original order. example: inv-1042 narration: type: - string - 'null' example: 'Invoice #1042' metadata: type: object additionalProperties: {} statusMessage: type: - string - 'null' description: Failure reason when status is failed. expiresAt: type: - string - 'null' format: date-time description: >- Bank and crypto orders expire 4 hours after creation if no deposit arrives. Null for mobile money. completedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time example: '2026-08-01T09:12:44.000Z' updatedAt: type: string format: date-time required: - id - status - from - to - fee - rate - instructions - expectedAmount - receivedAmount - collectionId - payoutId - externalReference - narration - metadata - statusMessage - expiresAt - completedAt - createdAt - updatedAt Error: type: object properties: error: type: string description: Stable machine-readable code. message: type: string description: Human-readable explanation. requestId: type: string description: Echoed in the x-request-id response header — quote it to support. required: - error - message securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key: `sk_test_…` (sandbox) or `sk_live_…` (production).' ````