> ## 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. # Withdraw to a bank > Pays local currency to a bank account from your stablecoin balance. Get the `bank_code` from **List institutions** and confirm the account holder with **Verify an account** before you pay. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/merchant/transaction/fiat/withdrawal 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/merchant/transaction/fiat/withdrawal: post: tags: - Withdrawals summary: Withdraw to a bank description: >- Pays local currency to a bank account from your stablecoin balance. Get the `bank_code` from **List institutions** and confirm the account holder with **Verify an account** before you pay. operationId: MerchantPaymentController_withdrawFiat parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitializeFiatWithdrawalDto' example: amount: 100 currency: usdc payoutCurrency: NGN country: NG beneficiary: holder_name: Chidi Okafor holder_type: individual account_number: '0123456789' bank_code: '044' reference: payout_5511 responses: '201': description: Withdrawal initiated. content: application/json: schema: type: object properties: message: type: string example: Withdrawal initiated status: type: string example: success statusCode: type: number example: 201 data: type: object properties: id: type: string example: 0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a type: type: string example: offramp reference: type: string example: payout_5511 status: type: string example: processing currency: type: string example: usdc network: type: string example: solana amount: type: number example: 100 address: type: string nullable: true example: null txHash: type: string nullable: true example: null failureReason: type: string nullable: true example: null note: type: string nullable: true example: null metadata: type: object properties: beneficiary: type: object properties: holder_name: type: string example: Chidi Okafor holder_type: type: string example: individual account_number: type: string example: '0123456789' bank_code: type: string example: '044' payoutCurrency: type: string example: NGN country: type: string example: NG channel: type: string example: BANK_TRANSFER livemode: type: boolean example: true createdAt: type: string example: '2026-11-04T10:21:09.000Z' updatedAt: type: string example: '2026-11-04T10:21:09.000Z' example: message: Withdrawal initiated status: success statusCode: 201 data: id: 0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a type: offramp reference: payout_5511 status: processing currency: usdc network: solana amount: 100 address: null txHash: null failureReason: null note: null metadata: beneficiary: holder_name: Chidi Okafor holder_type: individual account_number: '0123456789' bank_code: '044' payoutCurrency: NGN country: NG channel: BANK_TRANSFER livemode: true createdAt: '2026-11-04T10:21:09.000Z' updatedAt: '2026-11-04T10:21:09.000Z' '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: InitializeFiatWithdrawalDto: type: object properties: currency: type: string example: usdc description: The stablecoin to pay from. enum: - usdc - usdt amount: type: number example: 100 description: How much to pay out, in `currency`. payoutCurrency: type: string example: NGN description: The local currency the recipient receives. country: type: string example: NG description: The recipient's country, as an ISO code. beneficiary: $ref: '#/components/schemas/WithdrawalBeneficiaryDto' description: The bank account to pay. channel: type: string example: BANK_TRANSFER description: How the payout is sent. reference: type: string example: payout_5511 description: >- Your unique ID for this payout. Sending the same one again returns `409` and sends nothing, so retries are safe. Generated if you leave it out. note: type: string example: 'Payout to supplier #INV-2024-001' description: A note for your records. callbackUrl: type: string example: https://your-server.com/hooks/flipeet description: Send this payout's webhooks here instead of your usual webhook URL. metadata: type: object example: orderId: ORD-123 customerId: USR-456 description: Your own data, returned as-is in the webhook. required: - amount - currency - payoutCurrency - country - beneficiary WithdrawalBeneficiaryDto: type: object properties: holder_name: type: string example: Chidi Okafor description: The name on the account. holder_type: type: string example: individual description: Whether the account belongs to a person or a business. enum: - individual - business account_number: type: string example: '0123456789' description: The account number. bank_code: type: string example: '044' description: The bank, from **List institutions**. required: - holder_name - holder_type - account_number - bank_code 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.