{
"openapi": "3.0.1",
"info": {
"title": "Card BIN Data",
"description": "Retrieve detailed information about a card.\n\n\n __Header__\n```\n Authorization: {your_credentials}\n Content-Type: application/json\n WP-Api-Version: 1\n```\n Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Worldpay Implementation Manager.\n
\n You **must** use the `Authorization` header for any request you send to our Card BIN Data API.
__DNS whitelisting__\n\n Whitelist the following URLs:\n * `https://try.access.worldpay.com/`\n * `https://access.worldpay.com/`\n\n Please ensure you use DNS whitelisting, not explicit IP whitelisting.\n When you make a request within Access Worldpay, you should always cache the response returned.\n ",
"version": "1",
"x-metadata": {
"category": [
"Card BIN"
],
"business": [
"Enterprise"
],
"catalog-list": true,
"generated": false
}
},
"servers": [
{
"url": "https://try.access.worldpay.com/api",
"description": "Test (Try)"
},
{
"url": "https://access.worldpay.com/api",
"description": "Live"
}
],
"security": [
{
"BasicAuth": []
}
],
"paths": {
"/cardBin/panLookup": {
"post": {
"summary": "Get BIN data",
"description": "Returns card BIN data for the card number or Worldpay token supplied.",
"operationId": "panlookup",
"parameters": [
{
"$ref": "#/components/parameters/wpApiVersion"
}
],
"requestBody": {
"description": "Lookup details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/request"
},
"examples": {
"cardNumber": {
"$ref": "#/components/examples/cardRequest"
},
"token": {
"$ref": "#/components/examples/tokenRequest"
}
}
}
},
"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"
}
},
"deprecated": false
},
"parameters": []
}
},
"components": {
"securitySchemes": {
"BasicAuth": {
"type": "http",
"scheme": "basic"
}
},
"parameters": {
"wpApiVersion": {
"name": "WP-Api-Version",
"in": "header",
"description": "The API version.",
"style": "simple",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
},
"example": 1
}
},
"schemas": {
"cardNumber": {
"type": "object",
"title": "cardNumber",
"properties": {
"merchant": {
"$ref": "#/components/schemas/merchant"
},
"cardNumber": {
"type": "string",
"description": "Primary Account Number (PAN) and Network Token Number are accepted.",
"example": "4444333322221111",
"pattern": "^\\d{12,19}$"
}
},
"required": [
"merchant",
"cardNumber"
]
},
"token": {
"type": "object",
"title": "token",
"properties": {
"merchant": {
"$ref": "#/components/schemas/merchant"
},
"token": {
"type": "string",
"description": "Worldpay token href",
"example": "https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
}
},
"required": [
"merchant",
"token"
]
},
"entity": {
"type": "string",
"description": "Used to route the request in Access Worldpay, created as part of on-boarding.",
"example": "default",
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9]*$"
},
"merchant": {
"type": "object",
"description": "An object that contains information about the merchant.",
"properties": {
"entity": {
"$ref": "#/components/schemas/entity"
}
},
"required": [
"entity"
]
},
"request": {
"type": "object",
"description": "Lookup details.",
"oneOf": [
{
"$ref": "#/components/schemas/cardNumber"
},
{
"$ref": "#/components/schemas/token"
}
]
},
"response": {
"type": "object",
"description": "Successful response with BIN details.",
"properties": {
"type": {
"type": "string",
"enum": [
"pan",
"networkToken"
],
"description": "The type of account number provided.",
"example": "pan"
},
"brand": {
"type": "array",
"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"
],
"description": "Brand of the card. For co-branded cards multiple brands are returned."
},
"bin": {
"type": "string",
"description": "Bank Identification Number.",
"example": "444422"
},
"binLength": {
"type": "integer",
"description": "Length of the BIN.",
"example": 6
},
"fundingType": {
"type": "string",
"enum": [
"credit",
"debit",
"prepaid",
"chargeCard",
"deferredDebit",
"unknown"
],
"description": "Funding source of the card.",
"example": "credit"
},
"issuerName": {
"type": "string",
"description": "Card issuer name.",
"example": "Bank of America"
},
"countryCode": {
"type": "string",
"description": "Card issuer country in ISO alpha-2 format or unknown.",
"example": "US"
},
"currency": {
"type": "string",
"description": "Currency of the card in ISO alpha-3 format.",
"example": "USD"
},
"dccAllowed": {
"type": "boolean",
"description": "Sets whether Dynamic Currency Conversion (DCC) is permitted.",
"example": true
},
"anonymousPrepaid": {
"type": "string",
"enum": [
"anonymousNonCompliant",
"anonymousCompliant",
"notPrepaidOrNonAnonymous",
"unknown"
],
"description": "Anonymous prepaid program and AMLD5 compliance.",
"example": "notPrepaidOrNonAnonymous"
},
"category": {
"type": "string",
"enum": [
"commercial",
"consumer"
],
"description": "The card category.",
"example": "consumer"
},
"multipleAccountAccess": {
"type": "string",
"enum": [
"managed",
"selfServe",
"notParticipating",
"notSupported"
],
"description": "Participation in Visa multiple-account access. Managed cardholder choices are stored with Visa and self-serve with the issuer.",
"example": "managed"
}
}
},
"validationError": {
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"description": "A machine and human readable error type for clarity and semantic understanding of the error.",
"enum": [
"fieldIsMissing",
"fieldMustBeString",
"fieldMustBeNumber",
"fieldMustBeInteger",
"fieldMustBeBoolean",
"fieldMustBeObject",
"fieldMustBeArray",
"fieldIsNull",
"fieldIsEmpty",
"fieldHasInvalidValue",
"fieldIsNotAllowed",
"numberIsTooSmall",
"integerIsTooLarge",
"stringIsTooShort",
"stringIsTooLong",
"stringFailedRegexCheck",
"panFailedLuhnCheck",
"dateHasInvalidFormat"
],
"example": "fieldIsNotAllowed"
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*.",
"example": "Field at path is not allowed."
},
"jsonPath": {
"type": "string",
"description": "This field represents the JSON path of the element within the request body associated with the error.",
"example": "$.transactionRef"
}
}
}
},
"examples": {
"cardRequest": {
"value": {
"merchant": {
"entity": "default"
},
"cardNumber": "4444333322221111"
}
},
"tokenRequest": {
"value": {
"merchant": {
"entity": "default"
},
"token": "https://access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ"
}
},
"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",
"multipleAccountAccess": "managed"
}
},
"validationError": {
"value": {
"errorName": "bodyDoesNotMatchSchema",
"message": "A JSON body matching the expected schema must be provided.",
"validationErrors": [
{
"errorName": "fieldIsNotAllowed",
"message": "Field at path is not allowed.",
"jsonPath": "$.transactionRef"
}
]
}
},
"headerError": {
"value": {
"errorName": "headerIsMissing",
"message": "A valid header must be provided.",
"headerName": "Content-Type"
}
},
"cardNotFound": {
"value": {
"errorName": "cardNotFound",
"message": "The card number cannot be found in any BIN ranges."
}
},
"tokenNotFound": {
"value": {
"errorName": "tokenNotFound",
"message": "Token not found"
}
}
},
"responses": {
"200": {
"description": "Request Successful",
"headers": {
"WP-CorrelationId": {
"schema": {
"type": "string"
},
"description": "Generated identifier for the request and response. When contacting support please include this.",
"example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323"
},
"WP-Api-Version": {
"schema": {
"type": "string"
},
"description": "The complete API Version is returned in the WP-Api-Version HPP Header. It contains the Major, Minor and Patch details of API Version.",
"example": "1.1.20240411"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/response"
},
"examples": {
"cardNumber": {
"$ref": "#/components/examples/response"
},
"token": {
"$ref": "#/components/examples/response"
}
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"WP-CorrelationId": {
"schema": {
"type": "string"
},
"description": "Generated identifier for the request and response. When contacting support please include this.",
"example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323"
},
"WP-Api-Version": {
"schema": {
"type": "string"
},
"description": "The complete API Version is returned in the WP-Api-Version HPP Header. It contains the Major, Minor and Patch details of API Version.",
"example": "1.1.20240411"
}
},
"content": {
"application/json": {
"examples": {
"Validation Error": {
"$ref": "#/components/examples/validationError"
},
"Header Error": {
"$ref": "#/components/examples/headerError"
}
},
"schema": {
"title": "error400",
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"internalErrorOccurred",
"headerIsMissing",
"headerHasInvalidValue",
"bodyIsEmpty",
"bodyIsNotJson",
"bodyDoesNotMatchSchema"
],
"description": "A machine and human readable error type for clarity and semantic understanding of the error.",
"example": "bodyDoesNotMatchSchema"
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*.",
"example": "A JSON body matching the expected schema must be provided."
},
"validationErrors": {
"type": "array",
"description": "If there were field validation errors, they will be collected in this array.",
"items": {
"$ref": "#/components/schemas/validationError"
}
},
"headerName": {
"type": "string",
"description": "If the header is missing or does not contain an expected value, this field will be populated with the incorrect header name.",
"example": "Content-Type"
}
}
}
}
}
},
"401": {
"description": "Client is not authorized due to missing or invalid Authorization header.",
"headers": {
"WP-CorrelationId": {
"schema": {
"type": "string"
},
"description": "Generated identifier for the request and response. When contacting support please include this.",
"example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323"
}
},
"content": {
"application/json": {
"schema": {
"title": "error401",
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"description": "A machine and human readable error type for clarity and semantic understanding of the error.",
"example": "accessDenied"
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*.",
"example": "Access to the requested resource has been denied"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"headers": {
"WP-CorrelationId": {
"schema": {
"type": "string"
},
"description": "Generated identifier for the request and response. When contacting support please include this.",
"example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323"
},
"WP-Api-Version": {
"schema": {
"type": "string"
},
"description": "The complete API Version is returned in the WP-Api-Version HPP Header. It contains the Major, Minor and Patch details of API Version.",
"example": "1.1.20240411"
}
},
"content": {
"application/json": {
"examples": {
"Token Not Found": {
"$ref": "#/components/examples/tokenNotFound"
},
"Card Not Found": {
"$ref": "#/components/examples/cardNotFound"
}
},
"schema": {
"title": "error404",
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"tokenNotFound",
"cardNotFound"
],
"description": "A machine and human readable error type for clarity and semantic understanding of the error.",
"example": "cardNotFound"
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*.",
"example": "The card number cannot be found in any BIN ranges."
}
}
}
}
}
},
"415": {
"description": "Invalid content-type HTTP header",
"headers": {
"WP-CorrelationId": {
"schema": {
"type": "string"
},
"description": "Generated identifier for the request and response. When contacting support please include this.",
"example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323"
},
"WP-Api-Version": {
"schema": {
"type": "string"
},
"description": "The complete API Version is returned in the WP-Api-Version HPP Header. It contains the Major, Minor and Patch details of API Version.",
"example": "1.1.20240411"
}
},
"content": {
"application/json": {
"schema": {
"title": "error415",
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"description": "A machine and human readable error type for clarity and semantic understanding of the error.",
"example": "headerHasInvalidValue"
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*.",
"example": "A valid header must be provided."
},
"headerName": {
"type": "string",
"description": "If the header is missing or does not contain an expected value, this field will be populated with the incorrect header name.",
"example": "Content-Type"
}
}
}
}
}
},
"500": {
"description": "An error occurred processing the request on our side.",
"headers": {
"WP-CorrelationId": {
"schema": {
"type": "string"
},
"description": "Generated identifier for the request and response. When contacting support please include this.",
"example": "4c195ce9-3dbd-4bc8-9c94-3d3393842323"
},
"WP-Api-Version": {
"schema": {
"type": "string"
},
"description": "The complete API Version is returned in the WP-Api-Version HPP Header. It contains the Major, Minor and Patch details of API Version.",
"example": "1.1.20240411"
}
},
"content": {
"application/json": {
"schema": {
"title": "error500",
"type": "object",
"required": [
"errorName",
"message"
],
"properties": {
"errorName": {
"type": "string",
"enum": [
"internalServerError"
],
"description": "A machine and human readable error type for clarity and semantic understanding of the error.",
"example": "internalServerError"
},
"message": {
"type": "string",
"description": "A human readable message giving a corrective action for the error. *This is not for machine consumption*.",
"example": "An internal server error occurred"
}
}
}
}
}
}
}
}
}