Bank reachability is the set of payment types and payment channels through which a given bank can receive or send payments.

How it works

Every bank participates in one or more payment channels, such as a clearing and settlement mechanism. Participation can be direct, or indirect through another bank. A bank reachable through SEPA credit transfers is not necessarily reachable through SEPA instant credit transfers.

The bank reachability lookup resolves a bank from an International Bank Account Number (IBAN), a Business Identifier Code (BIC) of eight characters (BIC8), or a BIC of 11 characters (BIC11). It returns the bank's identifiers, address, and the payment channels it participates in for each payment type.

Use it to confirm a payment can reach its destination before you create a payment order, and to select the right payment type and routing identifiers.

Key concepts

Look up a bank

Send exactly one identifier. The three fields are mutually exclusive.

The following request looks up a bank from a French IBAN.

curl --request POST \
     --url https://sandbox.numeral.io/v1/bank_reachability/lookup \
     --header 'X-API-Key: Your_API_Key' \
     --header 'Content-Type: application/json' \
     --data '{
       "iban": "FR7630004008280001234567841"
     }'

The response returns the bank's details and the channels it participates in.

{
  "name": "BNP PARIBAS",
  "alternative_name": null,
  "identifiers": {
    "bic8": "BNPAFRPP",
    "bic11": "BNPAFRPPXXX",
    "routing_bic": "BNPAFRPPXXX",
    "iban_national_id": "3000400828"
  },
  "address": {
    "street": "BOULEVARD DES ITALIENS",
    "building_number": "16",
    "town": "PARIS",
    "postcode": "75009",
    "country_subdivision": "ILE-DE-FRANCE",
    "country_name": "FRANCE",
    "time_zone": "Europe/Paris"
  },
  "reachability": [
    {
      "payment_type": "sepa_credit_transfer",
      "payment_channels": [
        { "channel": "STEP2", "area": "SEPA", "mode": "direct" }
      ]
    },
    {
      "payment_type": "sepa_instant_credit_transfer",
      "payment_channels": [
        { "channel": "RT1", "area": "SEPA", "mode": "direct" }
      ]
    }
  ]
}

Check reachability before sending a payment

1. Look up the creditor bank using the creditor IBAN.
2. Read reachability. If it is null, the bank does not participate in any payment channel.
3. Find the entry whose payment_type matches the payment you intend to send.
4. If the entry exists, create the payment order. If it does not, the payment cannot reach the bank through that payment type.

Checking reachability before you create the payment order avoids rejections after submission.

Choose between instant and standard SEPA credit transfers

1. Look up the creditor bank.
2. Check reachability for an entry with payment_type equal to sepa_instant_credit_transfer.
3. If the entry exists, send the payment as a SEPA instant credit transfer.
4. If it does not, send the payment as a SEPA credit transfer instead, provided an entry with payment_type equal to sepa_credit_transfer exists.

The same pattern applies to SEPA Direct Debit. Check for sepa_direct_debit_b2b before collecting a B2B direct debit, and for sepa_direct_debit_core before collecting a Core direct debit.

Resolve the BIC and routing BIC

1. Look up the bank using the IBAN, BIC8, or BIC11 you hold.
2. Read identifiers.bic11 to get the full BIC of the bank.
3. Read identifiers.routing_bic to get the BIC to use when routing a Swift FIN payment. It can differ from bic11 when the bank is reached through its head office or an intermediary bank.
4. Read identifiers.iban_national_id to get the national bank identifier used in the bank's IBANs.

Limits and constraints

• Provide exactly one of iban, bic8, or bic11 per request. Providing more than one returns a 400 validation error.
• bic8 and bic11 must be uppercase.
• alternative_name, address, routing_bic, iban_national_id, and reachability can be null.
• The lookup returns 404 when no bank matches the identifier.
• Supported payment types are sepa_credit_transfer, sepa_instant_credit_transfer, sepa_direct_debit_core, sepa_direct_debit_b2b, bacs_direct_credit, bacs_direct_debit, bacs_direct_debit_instruction, bacs_direct_debit_mandate, building_society_credits, claims_unpaid_cheques, and dividend_interest_payments.
• Participation mode is direct or indirect.

Related

• Bank reachability lookup
• Send payments
• Create payment order