> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/payouts.md).

# Payouts

Manage payouts

## List payouts

> Returns all payouts.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"PayoutsV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","type":"array","items":{"$ref":"#/components/schemas/PayoutV2Dto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"details":{"description":"Type-specific details. crypto_address: { chain, address }. ngn_bank_account: { accountName, accountNumber, bankName, bankCode, accountType, currency }. kes_mobile_money and ghs_mobile_money: { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }.","oneOf":[{"$ref":"#/components/schemas/PayoutCryptoRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutBankRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutCrossBorderRecipientDetailsDto"}]}},"required":["id","type","details"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}},"paths":{"/api/v1/payouts":{"get":{"description":"Returns all payouts.","operationId":"PayoutV2Controller_getAllPayouts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by payout reference, transaction hash or destination address.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by payout status","schema":{"type":"string","enum":["pending","processing","success","failed"]}},{"name":"recipientId","required":false,"in":"query","description":"Filter by payout recipient.","schema":{"type":"string"}},{"name":"method","required":false,"in":"query","description":"Filter by payout method.","schema":{"type":"string","enum":["crypto","fiat"]}},{"name":"currency","required":false,"in":"query","description":"Filter by payout currency.","schema":{"type":"string","enum":["NGN","USDT","USDC","KES","ZAR","GHS"]}},{"name":"chain","required":false,"in":"query","description":"Filter by blockchain. Only crypto payouts move on a blockchain, so this excludes fiat payouts from the results.","schema":{"type":"string","enum":["bitcoin","ethereum","solana","bsc","tron","polygon","base","arbitrum","celo","arc"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutsV2ResponseDto"}}}},"401":{"description":"Unauthorized"}},"summary":"List payouts","tags":["Payouts"]}}}}
```

## Initiate payout

> Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CreatePayoutDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives. Local fiat: NGN. Stablecoin: USDT or USDC. Cross-border (KES, GHS) and native coins (ETH, BNB, POL, SOL) are funded from the stablecoin balance in sourceCurrency."},"sourceCurrency":{"type":"string","description":"Stablecoin balance to debit (USDT or USDC), for a cross-border or native coin payout, where the recipient is paid in a different currency. Omit for local fiat and stablecoin payouts, which debit the balance in `currency`.","enum":["USDT","USDC"]},"quoteId":{"type":"string","description":"The `id` of a quote from POST /payouts/quote, for a cross-border or native coin payout. Pass it to pay exactly the quoted price. Quotes expire after two minutes; omit it to price at the current rate."},"amount":{"type":"string","description":"Amount to pay out, in `currency`. For a cross-border or native coin payout this is the amount the recipient receives, and it is not needed when `quoteId` is given: the quote already fixes it. A native coin amount takes up to 8 decimal places."},"recipientId":{"type":"string","description":"Payout receipient Id"},"narration":{"type":"string","description":"Optional narration/description for the payout"},"reference":{"type":"string","description":"Optional idempotency reference for your request. If omitted, we generate a reference for you."},"webhookUrl":{"type":"string","description":"Optional URL to receive webhook notifications for this payout (must be HTTPS). Overrides your dashboard webhook URL for this payout only."}},"required":["currency","recipientId"]},"PayoutV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["success","message"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"details":{"description":"Type-specific details. crypto_address: { chain, address }. ngn_bank_account: { accountName, accountNumber, bankName, bankCode, accountType, currency }. kes_mobile_money and ghs_mobile_money: { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }.","oneOf":[{"$ref":"#/components/schemas/PayoutCryptoRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutBankRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutCrossBorderRecipientDetailsDto"}]}},"required":["id","type","details"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}},"paths":{"/api/v1/payouts":{"post":{"description":"Initiates a payout to a recipient. Requests authenticated with an API key never need a one-time code. Dashboard requests need a one-time code unless the recipient is trusted.","operationId":"PayoutV2Controller_initializePayout","parameters":[],"requestBody":{"required":true,"description":"Payout initiation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayoutDto"}}}},"responses":{"201":{"description":"Payout initialized successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutV2ResponseDto"}}}},"400":{"description":"Bad request - validation error, insufficient balance, daily limit exceeded, or missing one-time code (not required when the recipient is trusted)"},"404":{"description":"Recipient (bank account or wallet address) not found"},"500":{"description":"Internal server error - payout processing failed"}},"summary":"Initiate payout","tags":["Payouts"]}}}}
```

## Quote a payout

> Returns the fee and conversion for a payout the recipient receives in a different currency from the balance that pays for it, e.g. KES or ETH. Call it before creating the payout to show the cost.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"PayoutQuoteDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives, e.g. KES or ETH.","enum":["KES","GHS","ETH","BNB","POL","SOL"]},"sourceCurrency":{"type":"string","description":"Stablecoin balance the payout is funded from and debited in.","enum":["USDT","USDC"]},"chain":{"type":"string","description":"Blockchain the recipient is paid on. Required when currency is a coin such as ETH.","enum":["bsc","tron","solana","base","ethereum","polygon","arbitrum","arc"]},"sourceAmount":{"type":"string","description":"Amount to pay from the balance, in sourceCurrency. The amount the recipient receives is derived from it. Provide either sourceAmount or targetAmount, not both."},"targetAmount":{"type":"string","description":"Amount the recipient receives, in currency. Supported when currency is a coin such as ETH. Provide either sourceAmount or targetAmount, not both."}},"required":["currency","sourceCurrency"]},"PayoutQuoteResponseDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Quote id. Pass it as quoteId to POST /payouts to pay exactly this price before it expires."},"conversion":{"description":"The exchange applied: the funding stablecoin converted to the amount the recipient receives. sourceAmount x rate = targetAmount. sourceAmount plus sourceFee is what the payout costs, in fromCurrency.","allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"fee":{"type":"string","description":"Fee, in conversion.toCurrency."},"total":{"type":"string","description":"conversion.targetAmount plus fee, in conversion.toCurrency."},"expiresAt":{"type":"string","description":"When this quote expires. After this time, request a new quote."}},"required":["id","conversion","fee","total","expiresAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}},"paths":{"/api/v1/payouts/quote":{"post":{"description":"Returns the fee and conversion for a payout the recipient receives in a different currency from the balance that pays for it, e.g. KES or ETH. Call it before creating the payout to show the cost.","operationId":"PayoutV2Controller_quotePayout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutQuoteDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutQuoteResponseDataDto"}}}}},"summary":"Quote a payout","tags":["Payouts"]}}}}
```

## Quote a cross-border payout

> Deprecated: use POST /payouts/quote. Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Cross-border payouts are available to verified businesses.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CrossBorderQuoteDto":{"type":"object","properties":{"currency":{"type":"string","description":"Currency the recipient receives.","enum":["KES","GHS"]},"sourceCurrency":{"type":"string","description":"Stablecoin balance the payout is funded from and debited in.","enum":["USDT","USDC"]},"sourceAmount":{"type":"string","description":"Amount to pay from the balance, in sourceCurrency. The amount the recipient receives is derived from it."}},"required":["currency","sourceCurrency","sourceAmount"]},"CrossBorderQuoteResponseDataDto":{"type":"object","properties":{"id":{"type":"string","description":"Quote id. Pass it as quoteId to POST /payouts to pay exactly this price before it expires."},"conversion":{"description":"The FX applied: the funding stablecoin converted to the amount the recipient receives. sourceAmount x rate = targetAmount.","allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"fee":{"type":"string","description":"Flat fee, in conversion.fromCurrency."},"total":{"type":"string","description":"Total debited from the balance: conversion.sourceAmount plus fee, in conversion.fromCurrency."},"expiresAt":{"type":"string","description":"When this quote expires. After this time, request a new quote."}},"required":["id","conversion","fee","total","expiresAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]}}},"paths":{"/api/v1/payouts/cross-border/quote":{"post":{"deprecated":true,"description":"Deprecated: use POST /payouts/quote. Returns the fee and conversion for a cross-border payout, priced by the amount to pay from a balance (sourceAmount). Cross-border payouts are available to verified businesses.","operationId":"PayoutV2Controller_quoteCrossBorderPayout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBorderQuoteDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrossBorderQuoteResponseDataDto"}}}}},"summary":"Quote a cross-border payout","tags":["Payouts"]}}}}
```

## Retrieve payout

> Returns the payout for the given ID.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"PayoutV2ResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/PayoutV2Dto"}]}},"required":["success","message"]},"PayoutV2Dto":{"type":"object","properties":{"id":{"type":"string","description":"Payout ID"},"reference":{"type":"string","description":"Payout reference","nullable":true},"method":{"type":"string","description":"Payout method","enum":["fiat","crypto"]},"status":{"type":"string","description":"Payout status","enum":["pending","processing","success","failed"]},"amount":{"type":"string","description":"Amount the recipient receives"},"fee":{"type":"string","description":"Fee, in currency."},"total":{"type":"string","description":"amount plus fee, in currency."},"currency":{"type":"string","description":"Currency the recipient is paid in."},"conversion":{"description":"Conversion applied when the payout crosses currencies (e.g. a KES payout funded from USDT); null when none occurred. sourceAmount and sourceFee are what was charged, in fromCurrency.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ConversionDto"}]},"narration":{"type":"string","description":"Payout narration"},"recipient":{"description":"Recipient details","allOf":[{"$ref":"#/components/schemas/PayoutRecipientDto"}]},"channel":{"type":"string","description":"Payout channel (origin of the request)","enum":["API","dashboard"]},"txHash":{"type":"string","description":"Transaction hash (crypto payouts)","nullable":true},"failureReason":{"type":"string","description":"Failure reason","nullable":true},"completedAt":{"format":"date-time","type":"string","description":"Completion timestamp","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","reference","method","status","amount","fee","total","currency","conversion","narration","recipient","channel","txHash","failureReason","completedAt","createdAt","updatedAt"]},"ConversionDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency or asset."},"toCurrency":{"type":"string","description":"Target currency or asset."},"sourceAmount":{"type":"string","description":"Amount converted, in the source currency."},"sourceFee":{"type":"string","description":"Fee charged on top of sourceAmount, in the source currency. Returned on payouts and payout quotes."},"targetAmount":{"type":"string","description":"Amount produced, in the target currency."},"rate":{"type":"string","description":"Conversion rate applied."}},"required":["fromCurrency","toCurrency","sourceAmount","targetAmount","rate"]},"PayoutRecipientDto":{"type":"object","properties":{"id":{"type":"string","description":"Recipient ID (crypto address ID or bank account ID)","nullable":true},"type":{"type":"string","description":"Recipient type","enum":["crypto_address","ngn_bank_account","kes_mobile_money","zar_bank_account","ghs_mobile_money"]},"details":{"description":"Type-specific details. crypto_address: { chain, address }. ngn_bank_account: { accountName, accountNumber, bankName, bankCode, accountType, currency }. kes_mobile_money and ghs_mobile_money: { currency, countryIsoCode, accountNumber, accountName, institutionCode, institutionName, accountType }.","oneOf":[{"$ref":"#/components/schemas/PayoutCryptoRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutBankRecipientDetailsDto"},{"$ref":"#/components/schemas/PayoutCrossBorderRecipientDetailsDto"}]}},"required":["id","type","details"]},"PayoutCryptoRecipientDetailsDto":{"type":"object","properties":{"chain":{"type":"string","description":"Blockchain network","nullable":true},"address":{"type":"string","description":"Destination wallet address","nullable":true}},"required":["chain","address"]},"PayoutBankRecipientDetailsDto":{"type":"object","properties":{"accountName":{"type":"string","description":"Account holder name","nullable":true},"accountNumber":{"type":"string","description":"Masked account number","nullable":true},"bankName":{"type":"string","description":"Bank name","nullable":true},"bankCode":{"type":"string","description":"Bank code","nullable":true},"accountType":{"type":"string","description":"Account type","nullable":true},"currency":{"type":"string","description":"Account currency","nullable":true}},"required":["accountName","accountNumber","bankName","bankCode","accountType","currency"]},"PayoutCrossBorderRecipientDetailsDto":{"type":"object","properties":{"currency":{"type":"string","description":"Payout currency","nullable":true},"countryIsoCode":{"type":"string","description":"Destination country code","nullable":true},"accountNumber":{"type":"string","description":"Masked account or phone number","nullable":true},"accountName":{"type":"string","description":"Recipient name","nullable":true},"institutionCode":{"type":"string","description":"Bank or mobile money provider code","nullable":true},"institutionName":{"type":"string","description":"Bank or mobile money provider name","nullable":true},"accountType":{"type":"string","description":"Recipient account type","nullable":true}},"required":["currency","countryIsoCode","accountNumber","accountName","institutionCode","institutionName","accountType"]}}},"paths":{"/api/v1/payouts/{id}":{"get":{"description":"Returns the payout for the given ID.","operationId":"PayoutV2Controller_findOnePayout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Payout retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutV2ResponseDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Payout not found"}},"summary":"Retrieve payout","tags":["Payouts"]}}}}
```

## Retrieve all payout fees

> Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Payouts","description":"Manage payouts"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CalculatePayoutFeesApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Response data","allOf":[{"$ref":"#/components/schemas/CalculatePayoutFeesResponseDataDto"}]}},"required":["success","message"]},"CalculatePayoutFeesResponseDataDto":{"type":"object","properties":{"fiat":{"type":"object","description":"Fiat payout fees grouped by currency, then method. Covers every supported fiat payout rail.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"crossBorder":{"type":"object","description":"Cross-border payout fees grouped by destination currency, then method. The fee is a flat charge in USD, debited from the funding stablecoin (USDT/USDC), not in the destination currency.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"crypto":{"type":"object","description":"Crypto payout fees (USDT) grouped by asset, then chain. Covers every supported payout chain and asset.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}},"required":["fiat","crossBorder","crypto"]}}},"paths":{"/api/v1/payouts/fees":{"get":{"description":"Returns fiat, cross-border, and crypto payout fees across every supported currency, corridor, chain, and asset.","operationId":"PayoutV2Controller_getPayoutFees","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculatePayoutFeesApiResponseDto"}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error - Unable to calculate fees"}},"summary":"Retrieve all payout fees","tags":["Payouts"]}}}}
```
