> ## 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 Payment Methods for Corridor > Retrieve available payment methods, fees, and required beneficiary fields for a currency pair/corridor. ## Overview Returns all available payment methods for a specific currency pair/corridor, including: * Current exchange rate * Payment methods with fees and settlement times * Required and optional fields for each method (mostly on `beneficiary`; some are top-level on `POST /initiate`) Use this endpoint to render payout forms dynamically based on the selected corridor. ## Request ```http theme={null} GET /v1/payout-api/payouts/methods?sourceCurrency=NGN&destinationCurrency=CNY&destinationCountryCode=CHN HTTP/1.1 Host: gateway.staging.useyala.com x-api-key: ``` ### Query Parameters | Parameter | Required | Type | Description | Example | | ------------------------ | -------- | ------ | ---------------------------------------------- | ------- | | `sourceCurrency` | Yes | string | Source currency (3-letter ISO code) | `NGN` | | `destinationCurrency` | Yes | string | Destination currency (3-letter ISO code) | `CNY` | | `destinationCountryCode` | Yes | string | ISO country code (3-letter ISO 3166-1 alpha-3) | `CHN` | ### Headers | Header | Required | Description | | ----------- | -------- | ------------ | | `x-api-key` | Yes | Your API key | ## Response ```json theme={null} { "statusCode": 200, "message": "success", "data": { "corridor": { "sourceCurrency": "NGN", "destinationCurrency": "CNY", "destinationCountryCode": "CHN" }, "rate": { "code": "CNY/NGN", "rate": 235.0 }, "methods": [ { "code": "ALIPAY", "name": "Alipay", "settlement": "Instant", "fee": { "amount": 0, "currency": "NGN", "type": "FIXED" }, "requiredFields": [ { "name": "accountName", "type": "string", "description": "Beneficiary full name" }, { "name": "alipayId", "type": "email_or_phone", "validation": "email_or_phone", "description": "Alipay account email or phone" } ], "optionalFields": [] }, { "code": "SWIFT", "name": "SWIFT", "settlement": "2-5 business days", "fee": { "amount": 5.0, "currency": "USD", "type": "FIXED" }, "requiredFields": [ { "name": "accountName", "type": "string", "description": "Beneficiary full name" }, { "name": "accountNumber", "type": "string", "description": "Bank account number" }, { "name": "swiftCode", "type": "string", "description": "SWIFT/BIC code" }, { "name": "bankName", "type": "string", "description": "Bank name" }, { "name": "beneficiaryCountry", "type": "string", "description": "Beneficiary country code (3-letter ISO 3166-1 alpha-3)" } ], "optionalFields": [ { "name": "iban", "type": "string", "description": "IBAN (optional for SWIFT)" }, { "name": "intermediarySwift", "type": "string", "description": "Intermediary bank SWIFT code" }, { "name": "address", "type": "string", "description": "Beneficiary address (optional for SWIFT compliance)" }, { "name": "city", "type": "string", "description": "Beneficiary city (optional for SWIFT compliance)" }, { "name": "postCode", "type": "string", "description": "Beneficiary postal code (optional for SWIFT compliance)" } ] }, { "code": "FASTER_PAYMENTS", "name": "FASTER_PAYMENTS", "settlement": "Same day", "requiredFields": [ { "name": "accountName", "type": "string" }, { "name": "sortCode", "type": "string", "description": "6-digit UK sort code" }, { "name": "accountNumber", "type": "string" }, { "name": "iban", "type": "string", "description": "IBAN" } ], "optionalFields": [ { "name": "bankName", "type": "string" }, { "name": "remitterAddress", "type": "string", "description": "Top-level field on POST /initiate (not inside beneficiary). Optional payer address when the remitter is not the business onboarded on Yala; when omitted, Yala uses the onboarded business address on file." } ] } ] } } ``` ### Response Fields | Field | Type | Description | | --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `corridor` | object | Currency pair and destination country information | | `corridor.sourceCurrency` | string | Source currency (3-letter ISO code) | | `corridor.destinationCurrency` | string | Destination currency (3-letter ISO code) | | `corridor.destinationCountryCode` | string | Destination country code (3-letter ISO 3166-1 alpha-3) | | `rate` | object | Current exchange rate for the pair | | `rate.code` | string | Currency pair code (e.g., "CNY/NGN") | | `rate.rate` | number | **Current exchange rate** (for converting sourceCurrency to destinationCurrency) - This rate is current at the time of this request. When you call `POST /initiate`, the system will fetch a fresh rate that may differ. Always check the `exchangeRate` field in the `/initiate` response to see the rate that was actually applied. | | `methods` | array | Available payment methods for this corridor | ### Method Object Fields | Field | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------- | | `code` | string | Method code (e.g., "ALIPAY", "SWIFT", "NIP") | | `name` | string | Human-readable method name | | `settlement` | string | Settlement time (e.g., "Instant", "2-5 business days") | | `fee` | object | Fee information | | `fee.amount` | number | Fee amount | | `fee.currency` | string | Fee currency (3-letter ISO code) | | `fee.type` | string | Fee type: "FIXED", "PERCENTAGE", or "TIERED" | | `requiredFields` | array | Required fields for this method (see note below on where to send each) | | `optionalFields` | array | Optional fields for this method (beneficiary or top-level initiate) | Most fields belong in the **`beneficiary`** object on `POST /initiate`. Exceptions are called out in the field `description`—for example **`remitterAddress`** is a **top-level** initiate field (not nested under `beneficiary`). It is optional for all payment methods: provide it when the payer is **not** the business onboarded on Yala; when omitted, Yala uses the onboarded business address on file. ### Field Object Structure | Field | Type | Description | | ------------- | ----------------- | ----------------------------------------------------------------------------------------- | | `name` | string | Field name—use on `beneficiary` unless the description says top-level initiate | | `type` | string | Data type: `string`, `email`, `phone`, `number`, `enum` | | `validation` | string (optional) | Additional validation hint (e.g., "email\_or\_phone") | | `required` | boolean | Whether field is required | | `description` | string | Human-readable description | | `enumValues` | array (optional) | Allowed values for enum type fields (e.g., `["checking", "savings"]` for ACH accountType) | **Note:** Some methods may include a `oneOf` array, which means **one of the field groups** must be provided. For example, WeChat Pay requires either `openId` OR `wechatUserId`. ## Error Responses ### 400 Bad Request - Invalid Parameters ```json theme={null} { "statusCode": 400, "message": "destinationCountryCode must be exactly 3 characters (ISO 3166-1 alpha-3)" } ``` ### 400 Bad Request - Corridor Not Enabled ```json theme={null} { "statusCode": 400, "message": "Currency pair is not enabled for this business. Please enable it in your dashboard." } ``` **Solution**: Enable the currency pair in your Yala dashboard. ### 401 Unauthorized ```json theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Usage Example ```javascript theme={null} // User selects NGN to CNY corridor const response = await fetch( 'https://gateway.staging.useyala.com/v1/payout-api/payouts/methods?sourceCurrency=NGN&destinationCurrency=CNY&destinationCountryCode=CHN', { method: 'GET', headers: { 'x-api-key': 'your-api-key' } } ); const { methods, rate, corridor } = await response.json(); // Display methods to user methods.forEach(method => { console.log(`${method.name}: ${method.settlement}, Fee: $${method.fee.amount}`); // Render form fields based on requiredFields method.requiredFields.forEach(field => { console.log(`Required: ${field.name} (${field.type})`); }); }); // Use the rate and methods to display to your user // After user submits, call POST /initiate with beneficiary details // The initiate response will include a payout id for tracking ``` ## Exchange Rate Behavior **Important:** The exchange rate shown in the `rate.rate` field is current at the time of this request. * **Rate is for reference only** - The rate displayed here reflects the exchange rate at the moment you call this endpoint * **Rate may change** - When you later call `POST /initiate`, the system will fetch a fresh rate that may differ from what you see here * **Check the actual rate used** - The `POST /initiate` response includes an `exchangeRate` field showing the rate that was actually applied to your payout * **No rate guarantee** - There is no rate locking mechanism. The rate used is whatever is current at initiation time **Best Practice:** Display rates to users as "current rates" and inform them that the final rate will be confirmed in the payout response. ## Notes * **Country Codes**: All country codes must be 3-letter ISO 3166-1 alpha-3 format (e.g., "CHN" for China, "NGA" for Nigeria, "USA" for United States) * **Currency Pair**: Must be enabled for your business in the Yala dashboard * **Rate**: The exchange rate is calculated based on the base currency anchoring logic * **Methods**: Available methods depend on the destination country and currency pair * **Fields**: Required fields vary by payment method - use this endpoint to discover them dynamically ## OpenAPI ````yaml GET /v1/payout-api/payouts/methods 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.
✨ Key Features - Real-time payment processing - Secure wallet management - Comprehensive exchange rate calculations - Robust transaction monitoring
💰 Payment Methods and Fees ## 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)
$40 ($2k-$10k)
$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)
$40 ($2k-$10k)
$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)
$40 ($2k-$10k)
$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)
$40 ($2k-$10k)
$0 (≥$10k) | 24 to 72 hours | | HKD | Hong Kong | FPS | $20 | < 24 hrs | | Multiple* | Any Country | Swift | $50 (<$2k)
$40 ($2k-$10k)
$0 (≥$10k) | 24 to 72 hours | *Includes: GHS, XAF, ZAR, XOF, CAD, KES, UGX, INR
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/methods: get: tags: - Payouts summary: Get payment methods and rates description: >- Get payment methods and required beneficiary fields for a corridor (source/destination currency and country). operationId: getMethods parameters: - name: sourceCurrency in: query required: true schema: type: string example: NGN - name: destinationCurrency in: query required: true schema: type: string example: USD - name: destinationCountryCode in: query required: true schema: type: string example: USA responses: '200': description: Methods fetched successfully '400': description: Invalid query parameters '401': description: Unauthorized components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````