{ "openapi": "3.0.1", "info": { "title": "Card BIN Data", "description": "Lookup card metadata from a Primary Account Number (PAN), Network Token Number, or Worldpay token href.\n\nReturns: card brand(s), BIN and BIN length, PAN length, funding type, issuer name, issuer country (ISO alpha-2), default currency (ISO alpha-3), DCC eligibility, anonymous prepaid / AMLD5 compliance status, card category (consumer or commercial), product ID, product subtype, flexible credential participation including the Visa deployment model and account funding transactions support for domestic and cross-border.

\n\n __Set your headers__\n ```\n Authorization: {your_credentials}\n Content-Type: application/json\n WP-Api-Version: 2\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username:password given to you by your Worldpay Implementation Manager.

We require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.

We use the WP-Api-Version header to identify which version of our API you are using. You must use this header for any request you send to our Card BIN API.

\n__DNS whitelisting__
Whitelist the following URLs:
* `https://try.access.worldpay.com/`
* `https://access.worldpay.com/`

\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting.", "version": "2", "x-ai-hints": { "primary-use-cases": [ "Lookup card brand and funding type before processing a payment", "Determine DCC eligibility for a card", "Check anonymous prepaid / AMLD5 status for compliance", "Enrich card data from a stored Worldpay token", "Determine Visa Direct AFT eligibility before initiating a pull payment" ], "authentication": "HTTP Basic Auth. Set the Authorization header to \"Basic \". Credentials are issued by your Worldpay Worldpay Implementation Manager.", "required-headers": [ "Authorization: Basic ", "Content-Type: application/json", "WP-Api-Version: 2" ], "error-recovery": { "400": "Fix the request body or headers per the validationErrors array and retry immediately.", "401": "Re-check credentials. Do not retry automatically.", "404": "The card or token is not in Worldpay BIN ranges. Do not retry; surface error to caller.", "415": "Set Content-Type to application/json and retry immediately.", "500": "Transient server error. Retry with exponential back-off; include WP-CorrelationId in support tickets." } }, "x-metadata": { "category": [ "Card BIN" ], "business": [ "Enterprise" ], "catalog-list": true, "generated": false } }, "servers": [ { "url": "https://try.access.worldpay.com", "description": "Test (Try) - use for integration and QA" }, { "url": "https://access.worldpay.com", "description": "Live - use for production traffic" } ], "tags": [ { "name": "Card Lookup", "description": "Lookup card metadata by PAN, Network Token Number, or Worldpay token." } ], "paths": { "/api/cardBin/panLookup": { "post": { "tags": [ "Card Lookup" ], "deprecated": false, "summary": "Lookup BIN data for a card number or Worldpay token", "description": "Returns card metadata for the supplied payment instrument. This is a read-only lookup with no side effects - safe to retry on network errors.", "operationId": "getCardBinData", "security": [ { "basicAuth": [] } ], "x-ai-hints": { "when-to-call": "Call before authorizing a payment when you need to know the card brand, funding type, or DCC eligibility, or when you need to verify AMLD5 compliance for a prepaid card, or to check AFT eligibility before initiating a Visa Direct pull payment.", "input-selection": "Use the card variant when you have a raw PAN or network token number. Use the token variant when you have a Worldpay token href (starts with https://.../tokens/).", "idempotency": "This is a read-only lookup. Safe to retry on network errors. No side effects.", "response-fields": { "type": "pan or networkToken. Indicates whether the card belongs to a tokenized issuer range.", "brand": "Array of card brands. Co-branded cards return multiple values (e.g. [\"visa\",\"maestro\"]).", "bin": "Bank Identification Number extracted from the card. Use binLength to determine how many digits constitute the BIN for this card. Capped at 8 digits to protect PCI-sensitive data where the BIN length exceeds 8 digits.", "binLength": "Number of digits in the BIN (typically 6 or 8).", "panLength": "The length of the PAN, a value of 0 indicates a variable length.", "fundingType": "credit | debit | prepaid | chargeCard | deferredDebit. Use to apply correct interchange category or surcharge logic.", "issuerName": "Name of the card-issuing bank or financial institution.", "countryCode": "ISO 3166-1 alpha-2 country code of the card issuer. Use for cross-border fee logic or geographic restrictions.", "currency": "ISO 4217 alpha-3 default currency of the card. Use together with dccAllowed to determine whether to offer Dynamic Currency Conversion.", "dccAllowed": "true if Dynamic Currency Conversion may be offered to the cardholder. Always check this flag before presenting a DCC offer.", "anonymousPrepaid": "AMLD5 anonymous prepaid status. notPrepaidOrNonAnonymous means no AMLD5 concern. anonymousCompliant means anonymous prepaid but AMLD5-compliant. anonymousNonCompliant means anonymous and non-compliant - block if your compliance policy requires it. unknown means status could not be determined.", "category": "commercial or consumer card classification.", "productId": "Scheme product identifier assigned by the card scheme. Can be used to determine card product tier and support interchange cost analysis. Values are scheme-defined and subject to change.", "productSubType": "Scheme product sub-type providing further classification within a product, for example agriculture or healthcare segments for Visa. Values are scheme-defined, subject to change, and not consistent across schemes.", "flexibleCredential.participating": "true if the card participates in Visa Flexible Credential or Mastercard One Credential. Check this before applying flexible credential routing logic.", "flexibleCredential.deploymentModel": "Visa only. managed means cardholder choices are held by Visa; selfServe means held by the issuer. Only present when flexibleCredential.participating is true.", "accountFundingTransactions.domestic": "Whether this card is eligible to be the source of a domestic Visa Direct Account Funding Transaction. A value of supported means the issuer participates in AFT for domestic transactions. notSupported means the issuer does not permit AFTs for domestic transactions.", "accountFundingTransactions.crossBorder": "Whether this card is eligible to be the source of a cross-border Visa Direct Account Funding Transaction. A value of supported means the issuer participates in AFT for cross-border transactions. notSupported means the issuer does not permit AFTs for cross-border transactions." } }, "parameters": [ { "$ref": "#/components/parameters/WPApiVersion" } ], "requestBody": { "description": "Provide a paymentInstrument with type card (PAN or Network Token Number, 12-19 digits) or type token (Worldpay token href). The merchant.entity field identifies your routing entity; use the value assigned during on-boarding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/request" }, "examples": { "cardNumber": { "$ref": "#/components/examples/cardRequest" }, "tokenHref": { "$ref": "#/components/examples/tokenHrefRequest" } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/200" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" }, "415": { "$ref": "#/components/responses/415" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Base64-encode your username:password (issued by Worldpay) and send as `Authorization: Basic ` on every request." } }, "parameters": { "WPApiVersion": { "name": "WP-Api-Version", "in": "header", "description": "API major version number. Must be 2.", "style": "simple", "required": true, "schema": { "type": "integer", "minimum": 2, "maximum": 2 }, "example": 2 } }, "schemas": { "paymentInstrument": { "type": "object", "description": "Use the card variant when you have a raw PAN or Network Token Number. Use the token variant when you have a Worldpay token href.", "discriminator": { "propertyName": "type", "mapping": { "card": "#/components/schemas/cardInstrument", "token": "#/components/schemas/tokenInstrument" } }, "oneOf": [ { "$ref": "#/components/schemas/cardInstrument" }, { "$ref": "#/components/schemas/tokenInstrument" } ] }, "cardInstrument": { "type": "object", "description": "Worldpay card lookup. Provide a Primary Account Number (PAN) or Network Token Number.", "required": [ "type", "number" ], "properties": { "type": { "type": "string", "description": "Discriminator value identifying this as a card number lookup.", "enum": [ "card" ] }, "number": { "type": "string", "description": "Primary Account Number (PAN) or Network Token Number. Must be 12–19 digits. Do not include spaces or dashes.", "example": "4444333322221111", "minLength": 12, "maxLength": 19, "pattern": "^\\d+$" } } }, "tokenInstrument": { "type": "object", "description": "Worldpay token lookup. Provide the token href URL returned when the token was originally created.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Discriminator value identifying this as a token lookup.", "enum": [ "token" ] }, "href": { "type": "string", "format": "uri", "description": "Full Worldpay token href URL, as returned when the token was created. Begins with https://.../tokens/.", "example": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" } } }, "request": { "type": "object", "required": [ "merchant", "paymentInstrument" ], "properties": { "merchant": { "type": "object", "description": "Identifies the merchant entity for request routing. The entity value is assigned during on-boarding.", "required": [ "entity" ], "properties": { "entity": { "type": "string", "description": "Merchant routing entity name assigned during on-boarding. Supports alphanumeric characters and the following special characters: space (not leading or trailing), hyphen, underscore, and common punctuation.", "example": "default", "minLength": 1, "maxLength": 64, "pattern": "^(?! )[ \\-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`\\/+]*(?
This list may grow as new schemes are added. Treat unrecognised values as valid strings and handle them gracefully rather than failing.", "items": { "type": "string", "enum": [ "accel", "affn", "airplus", "allstar", "amex", "argencard", "ath", "aurore", "bc", "cabal", "carnet", "cartesBancaires", "cencosud", "coopeplus", "credimas", "culiance", "dankort", "diners", "discover", "eftposAU", "elo", "gecapital", "hana", "hipercard", "hyundai", "ikea", "interac", "interlink", "italcred", "jaywan", "jcb", "jeanie", "keyfuels", "kookmin", "lotte", "maestro", "mastercard", "naranja", "nativa", "ncp", "nevada", "newday", "nexo", "nonghyup", "nyce", "overdrive", "pavd", "pulse", "samsung", "sears", "shazam", "shinhan", "sorocred", "star", "starAccess", "supercharge", "tarjeta", "troy", "uatp", "unionPay", "visa" ] }, "example": [ "visa" ] }, "fundingType": { "type": "string", "enum": [ "credit", "debit", "prepaid", "chargeCard", "deferredDebit" ], "description": "Funding source of the card. Use to select the correct interchange category, apply surcharging rules, or restrict card acceptance by type.", "example": "credit" }, "response": { "type": "object", "description": "Card metadata returned for a successful BIN lookup. Includes brand, BIN and BIN length, PAN length, funding type, issuer details, DCC eligibility, AMLD5 compliance status, card category, scheme product ID and sub-type, flexible credential participation, and Visa Direct Account Funding Transaction eligibility.", "properties": { "type": { "type": "string", "enum": [ "pan", "networkToken" ], "description": "Indicates whether the card belongs to a tokenized issuer range.", "example": "pan" }, "brand": { "$ref": "#/components/schemas/brand" }, "bin": { "type": "string", "description": "Bank Identification Number extracted from the card. Capped at 8 digits to protect PCI-sensitive data where the BIN length exceeds 8 digits. Use `binLength` to determine the full BIN length for this card.", "example": "444422", "maxLength": 8 }, "binLength": { "type": "integer", "description": "Number of digits in the BIN (typically 6 or 8).", "example": 6 }, "fundingType": { "$ref": "#/components/schemas/fundingType" }, "issuerName": { "type": "string", "description": "Name of the card-issuing bank or financial institution.", "example": "Bank of America" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the card issuer. Use for cross-border fee logic or geographic restrictions.", "example": "US" }, "currency": { "type": "string", "description": "ISO 4217 alpha-3 default currency of the card. Use together with dccAllowed to determine whether to offer Dynamic Currency Conversion.", "example": "USD" }, "dccAllowed": { "type": "boolean", "description": "true if Dynamic Currency Conversion may be offered to the cardholder for this card. Always check this flag before presenting a DCC offer.", "example": true }, "anonymousPrepaid": { "type": "string", "description": "AMLD5 anonymous prepaid status.", "enum": [ "notPrepaidOrNonAnonymous", "anonymousNonCompliant", "anonymousCompliant", "unknown" ], "x-enumDescriptions": { "notPrepaidOrNonAnonymous": "No AMLD5 concern.", "anonymousCompliant": "Anonymous prepaid but AMLD5-compliant.", "anonymousNonCompliant": "Anonymous prepaid and non-compliant; block if your compliance policy requires it.", "unknown": "Status could not be determined." }, "example": "notPrepaidOrNonAnonymous" }, "category": { "type": "string", "enum": [ "commercial", "consumer" ], "description": "Whether the card is a commercial (business) or consumer card.", "example": "consumer" } } }, "validationError": { "type": "object", "required": [ "errorName", "message" ], "properties": { "errorName": { "type": "string", "description": "Machine-readable error code identifying the validation failure.", "enum": [ "fieldIsMissing", "fieldMustBeString", "fieldMustBeNumber", "fieldMustBeInteger", "fieldMustBeBoolean", "fieldMustBeObject", "fieldMustBeArray", "fieldIsNull", "fieldIsEmpty", "fieldHasInvalidValue", "fieldIsNotAllowed", "numberIsTooSmall", "integerIsTooLarge", "stringIsTooShort", "stringIsTooLong", "stringFailedRegexCheck" ], "example": "fieldIsMissing" }, "message": { "type": "string", "description": "Human-readable description of the error and corrective action.", "example": "Field at path must be present." }, "jsonPath": { "type": "string", "description": "JSON path of the field that caused the validation error.", "example": "$.merchant.entity" } } } }, "examples": { "cardRequest": { "summary": "Lookup by card number (PAN)", "value": { "merchant": { "entity": "default" }, "paymentInstrument": { "type": "card", "number": "4444333322221111" } } }, "tokenHrefRequest": { "summary": "Lookup by Worldpay token (href)", "value": { "merchant": { "entity": "default" }, "paymentInstrument": { "type": "token", "href": "https://access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ" } } }, "cardResponse": { "summary": "Card request response - tokenized issuer range", "value": { "type": "networkToken", "brand": [ "visa" ], "bin": "491183", "binLength": 6, "fundingType": "debit", "issuerName": "Bank of America", "countryCode": "US", "currency": "USD", "dccAllowed": false, "anonymousPrepaid": "notPrepaidOrNonAnonymous", "category": "consumer" } }, "tokenResponse": { "summary": "Worldpay token request response", "value": { "type": "pan", "brand": [ "visa" ], "bin": "444433", "binLength": 6, "fundingType": "debit", "issuerName": "Bank of America", "countryCode": "US", "currency": "USD", "dccAllowed": true, "anonymousPrepaid": "notPrepaidOrNonAnonymous", "category": "consumer" } }, "validationError": { "summary": "Request body failed schema validation", "value": { "errorName": "bodyDoesNotMatchSchema", "message": "A JSON body matching the expected schema must be provided.", "validationErrors": [ { "errorName": "fieldIsMissing", "message": "Field at path must be present.", "jsonPath": "$.merchant.entity" } ] } }, "headerError": { "summary": "Required header missing", "value": { "errorName": "headerIsMissing", "message": "A valid header must be provided.", "headerName": "Content-Type" } }, "cardNotFound": { "summary": "PAN not found in any BIN range", "value": { "errorName": "cardNotFound", "message": "The card number cannot be found in any BIN ranges." } }, "tokenNotFound": { "summary": "Worldpay token not found", "value": { "errorName": "tokenNotFound", "message": "Token not found" } } }, "responses": { "200": { "description": "BIN lookup succeeded. Response contains card metadata including brand, BIN and BIN length, PAN length, funding type, issuer details, DCC eligibility, AMLD5 status, card category, scheme product ID and sub-type, flexible credential participation, and Visa Direct Account Funding Transaction eligibility.", "headers": { "WP-CorrelationId": { "schema": { "type": "string" }, "description": "Unique request/response correlation ID. Include in support tickets when reporting issues.", "example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323" }, "WP-Api-Version": { "schema": { "type": "string" }, "description": "Full API version (major.minor.patch) used to process the request.", "example": "2.0.20260327" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/response" }, "examples": { "cardNumber": { "$ref": "#/components/examples/cardResponse" }, "token": { "$ref": "#/components/examples/tokenResponse" } } } } }, "400": { "description": "Bad request. The request body or a required header is invalid. Inspect `errorName` and `validationErrors` to identify the specific problem, fix the request, and retry. Do NOT retry without fixing the issue first.", "headers": { "WP-CorrelationId": { "schema": { "type": "string" }, "description": "Correlation ID for support.", "example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323" }, "WP-Api-Version": { "schema": { "type": "string" }, "description": "Full API version (major.minor.patch) used to process the request.", "example": "2.0.20260327" } }, "content": { "application/json": { "schema": { "title": "error400", "type": "object", "required": [ "errorName", "message" ], "properties": { "errorName": { "type": "string", "description": "Machine-readable error code.\n- `headerIsMissing` / `headerHasInvalidValue`: fix the named header.\n- `bodyIsEmpty` / `bodyIsNotJson` / `bodyDoesNotMatchSchema`: fix the request body.\n", "enum": [ "internalErrorOccurred", "headerIsMissing", "headerHasInvalidValue", "bodyIsEmpty", "bodyIsNotJson", "bodyDoesNotMatchSchema" ], "example": "bodyDoesNotMatchSchema" }, "message": { "type": "string", "description": "Human-readable corrective action. Not for machine parsing.", "example": "A JSON body matching the expected schema must be provided." }, "validationErrors": { "type": "array", "description": "Present when `errorName` is `bodyDoesNotMatchSchema`. Each entry identifies a specific field error with a jsonPath pointer.", "items": { "$ref": "#/components/schemas/validationError" } }, "headerName": { "type": "string", "description": "Present when `errorName` is `headerIsMissing` or `headerHasInvalidValue`. Identifies which header needs to be corrected.", "example": "Content-Type" } } }, "examples": { "Validation Error": { "$ref": "#/components/examples/validationError" }, "Header Error": { "$ref": "#/components/examples/headerError" } } } } }, "401": { "description": "Unauthorized. The Authorization header is missing or contains invalid credentials. Do not retry automatically. Verify credentials and re-authenticate.", "headers": { "WP-CorrelationId": { "schema": { "type": "string" }, "description": "Correlation ID for support.", "example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323" } }, "content": { "application/json": { "schema": { "title": "error401", "type": "object", "required": [ "errorName", "message" ], "properties": { "errorName": { "type": "string", "enum": [ "accessDenied" ], "description": "Machine-readable error code. Always `accessDenied` for 401 responses.", "example": "accessDenied" }, "message": { "type": "string", "description": "Human-readable corrective action.", "example": "Access to the requested resource has been denied" } } } } } }, "404": { "description": "Not found. The supplied card number or token does not match any known BIN range or token record. Do not retry. Surface the error to the caller; the input data may be invalid or unsupported.", "headers": { "WP-CorrelationId": { "schema": { "type": "string" }, "description": "Correlation ID for support.", "example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323" }, "WP-Api-Version": { "schema": { "type": "string" }, "description": "Full API version (major.minor.patch) used to process the request.", "example": "2.0.20260327" } }, "content": { "application/json": { "schema": { "title": "error404", "type": "object", "required": [ "errorName", "message" ], "properties": { "errorName": { "type": "string", "description": "- `tokenNotFound`: the Worldpay token href is not recognized.\n- `cardNotFound`: the PAN is not in any known BIN range.\n", "enum": [ "cardNotFound", "tokenNotFound" ], "example": "cardNotFound" }, "message": { "type": "string", "description": "Human-readable corrective action.", "example": "The card number cannot be found in any BIN ranges." } } }, "examples": { "Token Not Found": { "$ref": "#/components/examples/tokenNotFound" }, "Card Not Found": { "$ref": "#/components/examples/cardNotFound" } } } } }, "415": { "description": "Unsupported Media Type. Set Content-Type to application/json and retry immediately.", "headers": { "WP-CorrelationId": { "schema": { "type": "string" }, "description": "Correlation ID for support.", "example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323" }, "WP-Api-Version": { "schema": { "type": "string" }, "description": "Full API version (major.minor.patch) used to process the request.", "example": "2.0.20260327" } }, "content": { "application/json": { "schema": { "title": "error415", "type": "object", "required": [ "errorName", "message" ], "properties": { "errorName": { "type": "string", "description": "Machine-readable error code. Always `headerHasInvalidValue` for 415 responses.", "enum": [ "headerHasInvalidValue" ], "example": "headerHasInvalidValue" }, "message": { "type": "string", "description": "Human-readable corrective action.", "example": "A valid header must be provided." }, "headerName": { "type": "string", "description": "Identifies which header is incorrect.", "example": "Content-Type" } } } } } }, "500": { "description": "Internal server error. The problem is on Worldpay's side. Retry with exponential back-off. If errors persist, contact support and provide WP-CorrelationId.", "headers": { "WP-CorrelationId": { "schema": { "type": "string" }, "description": "Correlation ID - include in all support tickets.", "example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323" }, "WP-Api-Version": { "schema": { "type": "string" }, "description": "Full API version (major.minor.patch) used to process the request.", "example": "2.0.20260327" } }, "content": { "application/json": { "schema": { "title": "error500", "type": "object", "required": [ "errorName", "message" ], "properties": { "errorName": { "type": "string", "description": "Machine-readable error code. Always `internalServerError` for 500 responses.", "enum": [ "internalServerError" ], "example": "internalServerError" }, "message": { "type": "string", "description": "Human-readable description of the server error.", "example": "An internal server error occurred" } } } } } } } } }