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 beneficiary fields for each method

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)"
          }
        ]
      }
    ]
  }
}

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 beneficiary fields for this method
`optionalFields`	array	Optional beneficiary fields for this method

Field Object Structure

Field	Type	Description
`name`	string	Field name (use in POST /initiate beneficiary object)
`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

Payouts

​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