Get Available Banks

Retrieves the list of available banks for a specific payment method and currency combination. This is useful for displaying bank selection dropdowns to your customers before initiating withdrawal/payout transactions.

Endpoint

POST https://api.paysecurez.com/api/v1/transactions/banks

Request Headers

Authorization: Bearer {your_access_token}
Content-Type: application/json

Request Body

{
  "paymentMethod": "payment-method-code",
  "currency": "PKR",
  "country": "Pakistan"
}

Request Parameters

Field	Type	Required	Description
paymentMethod	string	Yes	Payment method identifier
currency	string	Yes	Currency code (EUR, TRY, etc.)
country	string	No	Country code or name. Accepts ISO 3166-1 alpha-2, alpha-3, or full name

Response

Returns an array of available banks:

[
  {
    "code": "00209",
    "name": "Ziraat Katılım"
  },
  {
    "code": "00062",
    "name": "Garanti BBVA"
  },
  {
    "code": "00015",
    "name": "Vakıfbank"
  }
]

Response Fields

Field	Type	Description
code	string	Bank code to use in transaction requests
name	string	Bank display name for UI

Example Request

curl -X POST https://api.paysecurez.com/api/v1/transactions/banks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "withdrawal-pkr-fps",
    "currency": "PKR",
    "country": "PK"
  }'

Example Response

[
  {
    "code": "ALBK",
    "name": "Allied Bank Limited"
  },
  {
    "code": "BAFL",
    "name": "Bank Alfalah Limited"
  },
  {
    "code": "BAHL",
    "name": "Bank Al Habib Limited"
  }
]

Error Responses

400 Bad Request - Missing Required Fields

{
  "error": "Validation Error",
  "message": "Payment method is required"
}

{
  "error": "Validation Error",
  "message": "Currency is required"
}

400 Bad Request - Invalid Configuration

{
  "error": "Validation Error",
  "message": "Payment method not found. Please check your payment method from request"
}

401 Unauthorized

{
  "error": "Authentication Error",
  "message": "Invalid client credentials"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An error occurred while fetching the bank list. Please contact support."
}

Usage Flow

1. Before creating a withdrawal/payout transaction, call this endpoint to get available banks
2. Display the bank list to your customer (dropdown, radio buttons, etc.)
3. Customer selects a bank from the list
4. Use the bank code in your transaction creation request in the payment.bank field

Example Implementation

// Step 1: Get available banks
async function fetchAvailableBanks() {
  const response = await fetch('https://api.paysecurez.com/api/v1/transactions/banks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      paymentMethod: 'withdrawal-pkr-fps',
      currency: 'PKR',
      country: 'Pakistan'
    })
  });
  
  const banks = await response.json();
  return banks;
}

// Step 2: Display banks in UI
function displayBankDropdown(banks) {
  const select = document.getElementById('bankSelect');
  banks.forEach(bank => {
    const option = document.createElement('option');
    option.value = bank.code;
    option.text = bank.name;
    select.appendChild(option);
  });
}

// Step 3: Create transaction with selected bank
async function createWithdrawal(bankCode, amount) {
  const response = await fetch('https://api.paysecurez.com/api/v1/transactions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      transactionAction: 'PAYMENT',
      amount: amount,
      currency: 'PKR',
      reference: 'ORDER-123',
      payment: {
        paymentMethod: 'withdrawal-pkr-fps',
        bank: bankCode, // Use the selected bank code here
        holder: 'John Doe',
        accountNumber: '1234567890'
      },
      // ... other required fields
    })
  });
  
  return await response.json();
}

Best Practice

Cache bank lists on your frontend for a reasonable duration (e.g., 1 hour) to reduce API calls. Bank lists typically don't change frequently.

Provider Support

Not all payment methods support bank list retrieval. If a payment method doesn't support this feature, you'll receive an error message. Contact support to enable bank list functionality for your payment methods.