> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useyala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Payout Quote

> Get exchange rate, fee, and final amounts before initiating a payout. Use this to show the user what they will pay before they confirm.

## Overview

Returns a **quote** for a prospective payout **without** creating one. Use this endpoint to:

* Show the **fee** to the user before they confirm
* Display **total amount debited** from the wallet (`totalDeductible`, always in source currency)
* Display **amount the beneficiary receives** (`destinationAmount`)

**Fees are always borne by the tenant** (your business). The fee is added on top of the source amount; the wallet is debited `sourceAmount + fee`, and the beneficiary receives the full converted amount.

**Read-only** — call as many times as needed (e.g. when the user changes the amount). When the user confirms, call `POST /initiate` to create the payout.

<Tip>
  **Recommended flow:** 1) `GET /pairs`, 2) `GET /methods`, 3) **`POST /quote`** (user enters amount; show fee and totals), 4) User confirms, 5) `POST /initiate`
</Tip>

## Request

```http theme={null}
POST /v1/payout-api/payouts/quote HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>
```

### Request Body

```json theme={null}
{
  "sourceAmount": 100000,
  "sourceCurrency": "NGN",
  "destinationCurrency": "CNY",
  "destinationCountryCode": "CHN",
  "method": "ALIPAY"
}
```

### Request Fields

| Field                    | Type   | Required | Description                                           |
| ------------------------ | ------ | -------- | ----------------------------------------------------- |
| `sourceAmount`           | number | Yes      | Amount to send from source wallet                     |
| `sourceCurrency`         | string | Yes      | Source currency (e.g. `USD`, `NGN`)                   |
| `destinationCurrency`    | string | Yes      | Destination currency (e.g. `NGN`, `CNY`)              |
| `destinationCountryCode` | string | Yes      | ISO country code (3-letter, e.g. `NGA`, `CHN`, `USA`) |
| `method`                 | string | Yes      | Payout method (e.g. `NIP`, `SWIFT`, `ALIPAY`)         |

## Response

```json theme={null}
{
  "sourceAmount": 100000,
  "sourceCurrency": "NGN",
  "destinationAmount": 463.48,
  "destinationCurrency": "CNY",
  "totalDeductible": 100060.07,
  "exchangeRate": 214.0404,
  "method": "ALIPAY",
  "fee": {
    "amount": 60.07,
    "currency": "NGN"
  }
}
```

### Response Fields

| Field                 | Type   | Description                                                                                    |
| --------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `sourceAmount`        | number | Amount entered by user (source currency)                                                       |
| `sourceCurrency`      | string | Source currency                                                                                |
| `destinationAmount`   | number | **Amount beneficiary receives** (destination currency)                                         |
| `destinationCurrency` | string | Destination currency                                                                           |
| `totalDeductible`     | number | **Total debited from wallet** (always in source currency). Equals `sourceAmount + fee.amount`. |
| `exchangeRate`        | number | Exchange rate used for the conversion                                                          |
| `method`              | string | Payout method                                                                                  |
| `fee`                 | object | Fee (always borne by the tenant)                                                               |
| `fee.amount`          | number | Fee amount                                                                                     |
| `fee.currency`        | string | Fee currency (always source currency)                                                          |

## Showing Fees to the User

> "You will pay **{totalDeductible} {sourceCurrency}** (includes **{fee.amount} {fee.currency}** fee). Recipient gets **{destinationAmount} {destinationCurrency}**."

## Error Responses

### 400 Bad Request – Validation or unsupported pair

```json theme={null}
{
  "statusCode": 400,
  "message": "Currency pair is not enabled for this business.",
  "error": "CORRIDOR_NOT_ENABLED"
}
```

### 401 Unauthorized

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Usage Example

```javascript theme={null}
// User has entered amount and selected method; show quote before "Confirm"
const quoteResponse = await fetch(
  'https://gateway.staging.useyala.com/v1/payout-api/payouts/quote',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      sourceAmount: 100000,
      sourceCurrency: 'NGN',
      destinationCurrency: 'CNY',
      destinationCountryCode: 'CHN',
      method: 'ALIPAY',
    }),
  }
);

const quote = await quoteResponse.json();

// Display to user
console.log(`You pay: ${quote.totalDeductible} ${quote.sourceCurrency}`);
console.log(`Recipient gets: ${quote.destinationAmount} ${quote.destinationCurrency}`);
console.log(`Fee: ${quote.fee.amount} ${quote.fee.currency}`);
console.log(`Rate: ${quote.exchangeRate}`);

// When user clicks "Confirm", call POST /initiate with same parameters + beneficiary + narration
```

## Notes

* **No side effects** — calling this endpoint does not create a payout or debit any wallet.
* **`totalDeductible` is always in source currency** — the amount that will be debited from the wallet if the user confirms.
* **Fees are always borne by the tenant** — the fee is in source currency and added on top of the source amount.
* **Rate at quote time** — the rate used when you call `POST /initiate` may differ slightly; the initiate response contains the actual rate applied.


## OpenAPI

````yaml POST /v1/payout-api/payouts/quote
openapi: 3.0.3
info:
  title: Yala Payout APIs
  description: >-
    Yala Payout API documentation. This comprehensive API suite enables seamless
    integration with our financial services platform, providing secure and
    efficient access to cross-border payment solutions.


    <details>

    <summary><b>✨ Key Features</b></summary>


    - Real-time payment processing

    - Secure wallet management

    - Comprehensive exchange rate calculations

    - Robust transaction monitoring

    </details>


    <details>

    <summary><b>💰 Payment Methods and Fees</b></summary>


    ## USD Payments


    | Destination | Method | Fees | Settlement Time |

    |------------|---------|------|-----------------|

    | United States | Wire | $20 | 1 day |

    | | ACH | $5.00 | 1 to 3 days |

    | China, Hong Kong | China wire/HK FPS | $20 | 24 to 72 hours |

    | Other Countries | Swift | $50 (<$2k)<br>$40 ($2k-$10k)<br>$0 (≥$10k) | 24
    to 72 hours |


    ### EUR Payments


    | Destination | Method | Fees | Settlement Time |

    |------------|---------|------|-----------------|

    | EU Countries | SEPA | $5.00 | < 48 hrs |

    | Other Countries | Swift | $50 (<$2k)<br>$40 ($2k-$10k)<br>$0 (≥$10k) | 24
    to 72 hours |


    ### GBP Payments


    | Destination | Method | Fees | Settlement Time |

    |------------|---------|------|-----------------|

    | United Kingdom | Faster Payments/BACS | $2.00 | < 24 hrs |

    | Other Countries | Swift | $50 (<$2k)<br>$40 ($2k-$10k)<br>$0 (≥$10k) | 24
    to 72 hours |


    ### Other Currencies


    | Currency | Destination | Method | Fees | Settlement Time |

    |----------|------------|---------|------|-----------------|

    | NGN | Nigeria | NIP | N100 | < 24 hrs |

    | CNY | All countries | Swift | $50 (<$2k)<br>$40 ($2k-$10k)<br>$0 (≥$10k) |
    24 to 72 hours |

    | HKD | Hong Kong | FPS | $20 | < 24 hrs |

    | Multiple* | Any Country | Swift | $50 (<$2k)<br>$40 ($2k-$10k)<br>$0
    (≥$10k) | 24 to 72 hours |


    *Includes: GHS, XAF, ZAR, XOF, CAD, KES, UGX, INR

    </details>


    For additional support or integration assistance, please contact our
    developer support team.
  version: 1.0.0
  termsOfService: https://useyala.com/
  contact:
    name: API Support
    email: developers@useyala.com
servers:
  - url: https://gateway.useyala.com
    description: Production server
  - url: https://gateway.staging.useyala.com
    description: Staging (Sandbox) server
security:
  - ApiKeyAuth: []
tags:
  - name: Payouts
    description: Operations related to payouts
  - name: Countries
    description: Operations to fetch supported countries and currency information
  - name: Transactions
    description: Operations to fetch transaction history and details
  - name: Webhooks
    description: Register and manage webhook URLs for payout status notifications
paths:
  /v1/payout-api/payouts/quote:
    post:
      tags:
        - Payouts
      summary: Get quote
      description: Get fee and conversion quote without creating a payout.
      operationId: getQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatorPayoutRequest'
      responses:
        '200':
          description: Quote calculated successfully
        '400':
          description: Validation error or unsupported currency pair
        '401':
          description: Unauthorized
components:
  schemas:
    CalculatorPayoutRequest:
      type: object
      required:
        - sourceAmount
        - sourceCurrency
        - destinationCurrency
        - method
        - destinationCountryCode
      properties:
        sourceAmount:
          type: number
          format: float
          example: 1000
        sourceCurrency:
          type: string
          example: USD
        destinationCurrency:
          type: string
          example: NGN
        method:
          type: string
          enum:
            - swift
            - nip
            - hk_fps
            - china_wire
            - faster_payments
            - wire
            - ach
            - sepa
        destinationCountryCode:
          type: string
          example: NGA
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````