> ## Documentation Index > Fetch the complete documentation index at: https://docs.flipeet.io/llms.txt > Use this file to discover all available pages before exploring further. # Create an on-ramp order > Your customer pays local currency and the stablecoin goes straight to `beneficiary.wallet_address`. The response's `data.deposit` has the account to pay into and the exact amount. Every status change is sent to `callback_url`. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/public/on-ramp/initialize openapi: 3.0.0 info: title: Flipeet Pay API version: '1.0' description: >- Accept and send stablecoin and local-currency payments. Authenticate with your secret key in the x-api-key header. Keys starting fpay_test_ use the sandbox; fpay_live_ moves real money. Guides: https://docs.flipeet.io contact: name: Flipeet Pay url: https://docs.flipeet.io servers: - url: https://api.pay.flipeet.io security: - x-api-key: [] tags: - name: Checkout description: >- Hosted payment pages: create a payment, send your customer to checkoutUrl, and get a webhook when they pay. - name: Deposits description: >- Collect stablecoins or local currency straight into your balance, with your own UI. - name: Balance description: What you hold, per asset. - name: Withdrawals description: Send funds from your balance to a wallet or a bank account. - name: Ramps description: >- Convert between local currency and stablecoins for your own customers, settled to their wallet or bank. - name: Webhooks description: Delivery history, resends and test events. - name: Sandbox description: 'Test-mode tools: simulate outcomes and add test funds. Sandbox keys only.' paths: /api/v1/public/on-ramp/initialize: post: tags: - Ramps summary: Create an on-ramp order description: >- Your customer pays local currency and the stablecoin goes straight to `beneficiary.wallet_address`. The response's `data.deposit` has the account to pay into and the exact amount. Every status change is sent to `callback_url`. operationId: PublicRampController_initializeOnRamp parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicRampDto' example: amount: 150000 asset: usdc network: base currency: NGN country: NG channel: BANK reference: ramp_901 callback_url: https://app.example.com/hooks/flipeet beneficiary: holder_type: INDIVIDUAL holder_name: Ngozi Eze wallet_address: '0x5aE1c3B0d2F4e6A8b0C2d4E6f8A0b2C4d6E89c21' responses: '201': description: Success content: application/json: schema: type: object properties: message: type: string example: Successfully status: type: string example: success statusCode: type: number example: 201 data: type: object properties: success: type: boolean example: true message: type: string example: Onramp initiated livemode: type: boolean example: true data: type: object properties: reference: type: string example: ramp_901 status: type: string example: AWAITING_DEPOSIT rate: type: number example: 1500 source: type: object properties: amount: type: number example: 150000 currency: type: string example: NGN destination: type: object properties: amount: type: number example: 99.25 currency: type: string example: usdc deposit: type: object properties: bank_name: type: string example: Providus Bank account_number: type: string example: '9100482736' account_name: type: string example: Flipeet / Ngozi Eze amount: type: number example: 150000 beneficiary: type: object properties: holder_type: type: string example: INDIVIDUAL holder_name: type: string example: Ngozi Eze wallet_address: type: string example: '0x5aE1c3B0d2F4e6A8b0C2d4E6f8A0b2C4d6E89c21' example: message: Successfully status: success statusCode: 201 data: success: true message: Onramp initiated livemode: true data: reference: ramp_901 status: AWAITING_DEPOSIT rate: 1500 source: amount: 150000 currency: NGN destination: amount: 99.25 currency: usdc deposit: bank_name: Providus Bank account_number: '9100482736' account_name: Flipeet / Ngozi Eze amount: 150000 beneficiary: holder_type: INDIVIDUAL holder_name: Ngozi Eze wallet_address: '0x5aE1c3B0d2F4e6A8b0C2d4E6f8A0b2C4d6E89c21' '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '409': $ref: '#/components/responses/Error409' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' security: - x-api-key: [] components: schemas: PublicRampDto: type: object properties: amount: type: number description: >- For an on-ramp, the local currency the customer pays. For an off-ramp, the stablecoin they send. example: 150000 asset: type: string description: The stablecoin. example: usdc enum: - usdc - usdt - cngn network: type: string description: The network the stablecoin moves on. example: base currency: type: string description: The local currency. example: NGN country: type: string description: The country, as an ISO code. example: NG beneficiary: $ref: '#/components/schemas/PublicOnRampBeneficiaryDto' description: >- Who receives the money: a `wallet_address` for an on-ramp, bank details for an off-ramp. callback_url: type: string description: Where we send every status change for this order. example: https://app.example.com/hooks/flipeet reference: type: string description: >- Your own ID for this order, in any format. Each one can be used once per business; sending it again returns `409`. Responses and webhooks for the order carry it. example: ramp_901 channel: type: string description: How the local currency moves, such as `BANK`. example: BANK reason: type: string description: Why the money is moving, where the country asks. staticAddress: type: boolean description: Reuse the same deposit details for this customer. required: - amount - asset - network - currency - country - channel - reference - callback_url - beneficiary PublicOnRampBeneficiaryDto: type: object properties: holder_type: type: string description: Whether the recipient is a person or a business. example: INDIVIDUAL enum: - INDIVIDUAL - BUSINESS holder_name: type: string description: The recipient's name. example: Ngozi Eze wallet_address: type: string description: 'On-ramps: the wallet that receives the stablecoin.' account_number: type: string description: 'Off-ramps: the bank account number.' bank_code: type: string description: 'Off-ramps: the bank, from **List institutions**.' iban: type: string description: Off-ramps where the country uses IBANs. sort_code: type: string description: Off-ramps to UK accounts. swift: type: string description: Off-ramps by SWIFT. routing_number: type: string description: Off-ramps to US accounts. holder_city: type: string description: The recipient's city, where required. holder_postal_code: type: string description: The recipient's postal code, where required. holder_street: type: string description: The recipient's street address, where required. mobile_number: type: string description: The recipient's mobile number, where required. mobile_network: type: string description: The recipient's mobile network, where required. required: - holder_type - holder_name responses: Error400: description: The request is invalid. `details.errors` lists every problem. content: application/json: schema: type: object properties: message: type: string description: What went wrong, for people. May be reworded. status: type: string example: error statusCode: type: integer description: The HTTP status. code: type: string description: A stable code to branch on. enum: - invalid_request - authentication_failed - permission_denied - not_found - conflict - rate_limited - internal_error - provider_error details: type: object nullable: true description: For validation errors, `errors` lists every problem. requestId: type: string description: Quote it when you contact us. timestamp: type: string format: date-time example: message: Amount must be a positive number status: error statusCode: 400 code: invalid_request details: errors: - Amount must be a positive number requestId: req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b timestamp: '2026-11-04T10:00:00.000Z' Error401: description: The API key is missing, mistyped or revoked. content: application/json: schema: type: object properties: message: type: string description: What went wrong, for people. May be reworded. status: type: string example: error statusCode: type: integer description: The HTTP status. code: type: string description: A stable code to branch on. enum: - invalid_request - authentication_failed - permission_denied - not_found - conflict - rate_limited - internal_error - provider_error details: type: object nullable: true description: For validation errors, `errors` lists every problem. requestId: type: string description: Quote it when you contact us. timestamp: type: string format: date-time example: message: Invalid or inactive API key status: error statusCode: 401 code: authentication_failed details: null requestId: req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b timestamp: '2026-11-04T10:00:00.000Z' Error409: description: >- That reference was used before. Look up the existing one instead of creating another. content: application/json: schema: type: object properties: message: type: string description: What went wrong, for people. May be reworded. status: type: string example: error statusCode: type: integer description: The HTTP status. code: type: string description: A stable code to branch on. enum: - invalid_request - authentication_failed - permission_denied - not_found - conflict - rate_limited - internal_error - provider_error details: type: object nullable: true description: For validation errors, `errors` lists every problem. requestId: type: string description: Quote it when you contact us. timestamp: type: string format: date-time example: message: Reference payout_5510 already exists status: error statusCode: 409 code: conflict details: null requestId: req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b timestamp: '2026-11-04T10:00:00.000Z' Error429: description: Too many requests. Each key can make 120 a minute. content: application/json: schema: type: object properties: message: type: string description: What went wrong, for people. May be reworded. status: type: string example: error statusCode: type: integer description: The HTTP status. code: type: string description: A stable code to branch on. enum: - invalid_request - authentication_failed - permission_denied - not_found - conflict - rate_limited - internal_error - provider_error details: type: object nullable: true description: For validation errors, `errors` lists every problem. requestId: type: string description: Quote it when you contact us. timestamp: type: string format: date-time example: message: Too many requests. Slow down and try again shortly. status: error statusCode: 429 code: rate_limited details: null requestId: req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b timestamp: '2026-11-04T10:00:00.000Z' Error500: description: Something went wrong on our side. Retry with backoff. content: application/json: schema: type: object properties: message: type: string description: What went wrong, for people. May be reworded. status: type: string example: error statusCode: type: integer description: The HTTP status. code: type: string description: A stable code to branch on. enum: - invalid_request - authentication_failed - permission_denied - not_found - conflict - rate_limited - internal_error - provider_error details: type: object nullable: true description: For validation errors, `errors` lists every problem. requestId: type: string description: Quote it when you contact us. timestamp: type: string format: date-time example: message: Internal server error status: error statusCode: 500 code: internal_error details: null requestId: req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b timestamp: '2026-11-04T10:00:00.000Z' Error502: description: A bank or network partner failed. Safe to retry with the same reference. content: application/json: schema: type: object properties: message: type: string description: What went wrong, for people. May be reworded. status: type: string example: error statusCode: type: integer description: The HTTP status. code: type: string description: A stable code to branch on. enum: - invalid_request - authentication_failed - permission_denied - not_found - conflict - rate_limited - internal_error - provider_error details: type: object nullable: true description: For validation errors, `errors` lists every problem. requestId: type: string description: Quote it when you contact us. timestamp: type: string format: date-time example: message: The payment partner could not complete the request status: error statusCode: 502 code: provider_error details: null requestId: req_5f0c2a9b8d7e4c1f9a3b6d2e1c0f7a8b timestamp: '2026-11-04T10:00:00.000Z' securitySchemes: x-api-key: type: apiKey in: header name: x-api-key description: >- Your secret key. `fpay_test_…` keys use the sandbox; `fpay_live_…` keys move real money. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.