Cards BIN Lookup

Amwal provides a real-time BIN resolution endpoint to inspect payment card BINs (first 6 to 8 digits) to identify the issuing bank, card network/scheme, funding type (credit vs. debit vs. prepaid), bank loyalty rewards programs, and 0% bank installment eligibility.

1. Real-Time BIN Lookup API Endpoint

Use this endpoint in your checkout flow to evaluate customer card prefixes before payment submission or to dynamically render the 0% installment tenure options.

Endpoint Details

Attribute	Details
Method	`GET`
URL	`https://backend.sa.amwal.tech/bin_numbers_lookup/?bin={BIN_NUMBER}`
Query Parameter	`bin` (string, required) — First 6 to 8 digits of the payment card number.
Authentication	Public / Gateway CORS Enabled
Response Content Type	`application/json`

Example cURL Request

curl --url 'https://backend.sa.amwal.tech/bin_numbers_lookup/?bin=54545454' \
  -H 'accept: application/json' \
  -H 'accept-language: en-US,en;q=0.9' \
  -H 'origin: https://pay.sa.amwal.tech' \
  -H 'referer: https://pay.sa.amwal.tech/'

2. API Response Schema

200 OK — Eligible Credit Card Response

{
  "id": 12848,
  "bin": "545454",
  "brand": "MASTER",
  "category": "TEST",
  "country": "Saudi Arabia",
  "issuer": "AL RAJHI BANKING AND INVESTMENT CORP",
  "type": "CREDIT",
  "program_name": "Mokafaa",
  "program_logo": "https://fra1.digitaloceanspaces.com/media-amwal/media/program_logo/mokafaa.png",
  "earn_rate": 1.0,
  "rate_label": "points",
  "is_override": false,
  "bank_amount_limit": "300.00",
  "bank_name": "AL RAJHI BANKING AND INVESTMENT CORP",
  "bank_code": "rajhi",
  "is_eligible": true
}

Response Attributes

Field	Type	Description
`bin`	`string`	The matched 6 or 8-digit Bank Identification Number.
`brand`	`string`	Card scheme or network (`VISA`, `MASTER`, `MADA`, `AMEX`).
`issuer` / `bank_name`	`string`	Official legal name of the issuing bank or financial entity.
`bank_code`	`string`	Normalized bank identifier code (e.g. `rajhi`, `snb`, `ribl`, `inma`).
`type`	`string`	Card funding classification (`CREDIT`, `DEBIT`, `PREPAID`).
`category`	`string`	Product tier (e.g. `TEST`, `CLASSIC`, `PLATINUM`, `INFINITE`).
`is_eligible`	`boolean`	`true` if the card qualifies for Amwal 0% Bank Installments; `false` otherwise.
`bank_amount_limit`	`string`	Minimum basket total required by the issuing bank to offer installment tenures (e.g. `300.00` SAR for Al Rajhi, `1000.00` SAR for SNB).
`program_name`	`string \| null`	Bank loyalty or rewards program associated with the card (e.g. Mokafaa, LAK, Hassad).
`program_logo`	`string \| null`	URL to the bank rewards program emblem or badge.
`earn_rate`	`number`	Multiplier for loyalty rewards earned per unit spent.

404 / Non-Eligible Response

{
  "is_eligible": false,
  "message": "Bin number not found."
}

3. SAMA Compliance & Card Eligibility Rules

The Saudi Central Bank (SAMA, License PSP013) enforces specific consumer lending and card switch mandates:

Credit Cards (Eligible for 0% Installments): The partner bank holds an authorized revolving credit facility with the cardholder. The bank pays the merchant in full on a T+2 SARIE schedule and manages the installment plan directly with the cardholder at 0% interest.
Mada Debit Cards (Ineligible for Installments): Debit cards deduct directly from current bank account balances. Because standard checking accounts have no credit underwriting facility, debit cards cannot be divided into installments.
Graceful Checkout Fallback: When an ineligible card (Mada debit, prepaid, or foreign card) is detected, Amwal immediately routes the session to 1-Click Pay in Full with biometric Passkey authentication.

Rendering diagram...

4. Developer Code Snippets

Node.js / TypeScript

import axios from 'axios';

export interface BinLookupResponse {
  bin: string;
  brand: string;
  category: string;
  country: string;
  issuer: string;
  type: 'CREDIT' | 'DEBIT' | 'PREPAID';
  program_name?: string;
  program_logo?: string;
  bank_amount_limit?: string;
  bank_name?: string;
  bank_code?: string;
  is_eligible: boolean;
}

export async function checkCardEligibility(cardNumber: string) {
  const bin = cardNumber.replace(/\D/g, '').slice(0, 8);

  try {
    const { data } = await axios.get<BinLookupResponse>(
      `https://backend.sa.amwal.tech/bin_numbers_lookup/?bin=${bin}`,
      {
        headers: {
          'accept': 'application/json',
        },
      }
    );

    if (data.is_eligible) {
      console.log(`✅ Qualified for 0% Bank Installments via ${data.bank_name}`);
      console.log(`Minimum Order Limit: ${data.bank_amount_limit} SAR`);
      // Display Amwal Installment Tenure Selector (3, 6, 12, 24 months)
    } else {
      console.log('⚡ Debit/Standard card detected — route to 1-Click Pay in Full');
    }

    return data;
  } catch (error) {
    console.error('BIN Lookup error:', error);
    return null;
  }
}

PHP

<?php

function lookup_amwal_bin($card_number) {
    $bin = substr(preg_replace('/\D/', '', $card_number), 0, 8);
    $url = "https://backend.sa.amwal.tech/bin_numbers_lookup/?bin=" . urlencode($bin);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "accept: application/json"
    ]);

    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 200) {
        $result = json_decode($response, true);
        if (!empty($result['is_eligible'])) {
            return $result; // Eligible for 0% Bank Installments
        }
    }

    return null;
}
?>

Python

import requests
import re

def check_card_bin(card_number: str):
    bin_prefix = re.sub(r'\D', '', card_number)[:8]
    url = f"https://backend.sa.amwal.tech/bin_numbers_lookup/?bin={bin_prefix}"
    
    headers = {
        "accept": "application/json"
    }
    
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        data = response.json()
        if data.get("is_eligible"):
            print(f"Eligible for 0% installments: {data.get('bank_name')}")
            print(f"Min Basket: {data.get('bank_amount_limit')} SAR")
        return data
    return None

Sandbox Test Cards — Full table of test card numbers for installment and standard payment testing.
Card Eligibility Troubleshooting — How to resolve CARD_TYPE_NOT_ELIGIBLE errors.
API Playground — Execute live API requests against Amwal endpoints.
Merchant Integration Keys — Retrieve your merchant and public API credentials.

On this page