Get Payment Methods for 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

GET /v1/payout-api/payouts/methods?sourceCurrency=NGN&destinationCurrency=CNY&destinationCountryCode=CHN HTTP/1.1
Host: gateway.staging.useyala.com
x-api-key: <YOUR_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

{
  "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

{
  "statusCode": 400,
  "message": "destinationCountryCode must be exactly 3 characters (ISO 3166-1 alpha-3)"
}

400 Bad Request - Corridor Not Enabled

{
  "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

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Usage Example

// 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

Authorizations

x-api-key

string

header

required

Query Parameters

sourceCurrency

string

required

Example:

"NGN"

destinationCurrency

string

required

Example:

"USD"

destinationCountryCode

string

required

Example:

"USA"

Response

Methods fetched successfully

​Overview

​Request

​Query Parameters

​Headers

​Response

​Response Fields

​Method Object Fields

​Field Object Structure

​Error Responses

​400 Bad Request - Invalid Parameters

​400 Bad Request - Corridor Not Enabled

​401 Unauthorized

​Usage Example

​Exchange Rate Behavior

​Notes

Authorizations

Query Parameters

Response

Overview

Request

Query Parameters

Headers

Response

Response Fields

Method Object Fields

Field Object Structure

Error Responses

400 Bad Request - Invalid Parameters

400 Bad Request - Corridor Not Enabled

401 Unauthorized

Usage Example

Exchange Rate Behavior

Notes