Skip to main content

Retrieve the Bank Identification Number (BIN)

For Enterprise clients with advanced fraud-analysis or treasury-routing needs, transaction responses can include the Bank Identification Number (BIN) — the first 6 digits of the card number. This field is opt-in and gated by a feature toggle tied to your account's PCI compliance status.

Default behavior​

By default, the bin field on transaction responses returns null for all accounts. This is the safe-by-default posture — no card-identifying digits leave Payments AI unless you have explicitly opted in and demonstrated PCI compliance.

When you need this​

Common reasons enterprise integrators request BIN exposure:

  • Fraud analytics. BIN identifies the issuing bank and country, which lets you build BIN-level approval-rate baselines and detect outliers.
  • Treasury routing. Some merchants route transactions to different acquirers based on the issuing bank's country, which requires knowing the BIN before settlement.
  • Reconciliation. Some chargeback-prevention and reconciliation workflows match on BIN.

If your integration does not need BIN-level data, leave the field off — the default response already includes everything most integrations need.

Business justification requirement​

BIN exposure is not enabled on a self-service basis. To turn it on:

  1. Contact support or your account manager. Request activation of the isBinExposureEnabled flag for your Organization.
  2. Provide a valid Attestation of Compliance (AoC). This proves your environment meets the PCI DSS scope required to receive partial card data.
  3. Describe the use case. Explain why your integration needs BIN — fraud analysis, treasury routing, or another specific reason. Payments AI may decline activation if the business justification is unclear.

Once enabled, the toggle is permanent until you ask to disable it.

Response structure once enabled​

The bin field is populated within the Transaction object in transaction responses (for example, GET /transactions/{id}, POST /transactions, and list endpoints).

{
  "id": "c114b68a-432e-4e94-b8ba-1658ef3258e2",
  "status": "completed",
  "amount": 100.00,
  "currency": "USD",
  "bin": "424242",
  "paymentInstrument": {
    "method": "payment-card",
    "brand": "Visa",
    "creditCardLastFourDigits": "4242"
  }
}

Field​

  • bin (string | null):
    • If enabled: the first 6 digits of the card number (for example, "424242").
    • If disabled (default): null.

Security constraints​

  • No full PAN. Under no circumstances does this field expose the full Primary Account Number. Only the standard 6-digit BIN range is returned.
  • Audit logging. Access to BIN-enabled responses is logged internally. Your integration must store and process this data within your own PCI DSS scope.
  • Field-level encryption recommended. Treat BIN as cardholder data per PCI DSS guidance, even though it is not by itself a full PAN.