---
updatedAt: 2025-08-21T13:31:28.000Z
agentTools:
siteIndex: https://merchants.westpac.com.au/llms.txt
projectIndex: https://merchants.westpac.com.au/onlinepay/llms.txt
---
# Bin lookup of Card Number
The Card Details API endpoints will bin lookup and provides card details.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"title": "eCommerce API",
"description": "The OnlinePay eCommerce API is used to process and manage payments via RESTful API requests.",
"version": "2.0.0",
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"contact": {}
},
"servers": [
{
"url": "https://au.gsc.verifone.cloud/oidc",
"description": "Australia"
},
{
"url": "https://cst.test-gsc.vfims.com/oidc",
"description": "Global Sandbox"
}
],
"components": {
"securitySchemes": {
"BasicAuth": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"BadRequestV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 400,
"enum": [
400
],
"default": 400
},
"message": {
"type": "string",
"example": "At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL.",
"enum": [
"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."
],
"default": "At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."
}
},
"required": [
"message"
]
},
"UnauthorizedV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 401,
"enum": [
401
],
"default": 401
},
"message": {
"type": "string",
"example": "Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request).",
"enum": [
"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."
],
"default": "Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."
}
},
"required": [
"message"
]
},
"ForbiddenV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 403,
"enum": [
403
],
"default": 403
},
"message": {
"type": "string",
"example": "Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator.",
"enum": [
"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."
],
"default": "Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."
}
},
"required": [
"message"
]
},
"NotFoundV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 404,
"enum": [
404
],
"default": 404
},
"message": {
"type": "string",
"example": "The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights.",
"enum": [
"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."
],
"default": "The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."
}
},
"required": [
"message"
]
},
"InternalErrorV2Docs": {
"type": "object",
"properties": {
"details": {
"type": "object",
"additionalProperties": {
"type": "object"
}
},
"timestamp": {
"type": "number",
"description": "Error timestamp",
"example": 1596467016700
},
"reversal_status": {
"type": "string",
"description": "Indicates to the API client if a technical reversal has been completed by Verifone.",
"default": "NONE",
"enum": [
"NONE",
"REQUIRED",
"COMPLETED"
]
},
"code": {
"type": "number",
"example": 500,
"enum": [
500
],
"default": 500
},
"message": {
"type": "string",
"example": "Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error",
"enum": [
"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"
],
"default": "Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"
}
},
"required": [
"message"
]
},
"CardDetailsResponse": {
"type": "object",
"properties": {
"bin_details": {
"description": "The details of the bin range or card. May contain more than one record if a co-branded card.",
"type": "array",
"items": {
"title": "BIN Information",
"description": "BIN entries refer to the Bank Identification Number entries in a financial system, typically representing the first six digits of a credit or debit card. These entries are essential for identifying the issuing bank or financial institution associated with a specific card.",
"type": "object",
"additionalProperties": false,
"properties": {
"bin": {
"description": "A BIN (Bank Identification Number) prefix refers to the initial set of digits in a credit or debit card number that uniquely identifies the issuing bank or financial institution.",
"type": "string",
"minLength": 4,
"maxLength": 8,
"example": 492912
},
"card_brand": {
"title": "The Card Brand",
"description": "The brand of this card, e.g. VISA, MASTERCARD, AMEX, CB, GIFT_CARD, etc.",
"type": "string",
"example": "VISA"
},
"type": {
"description": "The Account type or PAYMENT_TYPE in UGP. This source of the payment for the goods or service. This has a mapping to the processing code in DE03 (Processing Code) in ISO8583. This should map to the AccountType in Nexo/ISO20022. MSISDN - Mobile Station Integrated Services Digital Network. eg. CREDIT, DEBIT, STORED_VALUE, PRIVATE_LABEL, DEFAULT, etc.",
"type": "string",
"example": "CREDIT"
},
"funding_source": {
"description": "The type of funding this card has. Is this linked to a savings account/pre paid account or is this linked to a credit facility. eg. CREDIT, DEBIT, PREPAID, UNKNOWN",
"type": "string",
"example": "CREDIT"
},
"issuer_country": {
"$ref": "#/components/schemas/issuerCountryEnum"
},
"issuer_name": {
"description": "The issuer of this card. eg. HSBC, BARCLAYS.",
"type": "string",
"example": "HSBC"
},
"added_leading_zeroes": {
"description": "The number of leading zeroes that were added to get the match. This used at least for Isracard to deal with cards that have only 7 digits because the first three are zeroes.",
"type": "integer",
"minimum": 0,
"maximum": 3
},
"checksum_algorithm": {
"description": "The checksum algorithm to apply to the PAN including the addedLeadingZeroes. LUHN is the default.",
"type": "string",
"enum": [
"LUHN",
"ISRACARD",
"NONE"
],
"default": "LUHN"
},
"card_product": {
"type": "string",
"example": "VISA CLASSIC",
"description": "The type or category of credit or debit card."
}
}
}
}
}
},
"cardDetailsPrefixRequest": {
"title": "Prefix",
"type": "object",
"properties": {
"prefix": {
"type": "string",
"minLength": 4,
"maxLength": 8,
"example": 492912,
"description": "The prefix of the card to search for."
},
"entity_id": {
"type": "string",
"description": "Optional. The identifier of merchant entity for this request.",
"format": "uuid",
"example": "30b8bec8-5042-4e67-939c-5453fbe41711"
},
"query_context": {
"$ref": "#/components/schemas/BinQueryContext"
}
},
"required": [
"prefix"
]
},
"cardDetailsEncryptedCardRequest": {
"title": "Encrypted Card",
"type": "object",
"properties": {
"encrypted_card": {
"type": "string",
"title": "Client encrypted cardholder data",
"description": "The cardholder data encrypted using the OnlinePay provided public key. This can be obtained using either Verifone.JS solution or OnlinePay Checkout in capture mode.\n\n The data to encrypt is a JSON with possible tags being cardNumber, sequenceNumber, cardholderName, startMonth, startYear, expiryMonth, expiryYear, cvv. This should be a single JSON line and should not contain any spaces. Read Secure card capture key for details.\n\n Additionally, a tag called captureTime must be presenting indicating the time the card was captured in UTC in format RFC 3339, section 5.6. eg. 2019-08-24T14:15:22Z. Encrypted card is valid for only 15 minutes.",
"example": "U3dhZ2dlciByb2Nrcw=="
},
"public_key_alias": {
"type": "string",
"title": "Public Key Alias",
"description": "The alias for the public key used to encrypt this card.",
"example": "KEY00101"
},
"entity_id": {
"type": "string",
"description": "The identifier of merchant entity under whose cardTableGroupId you want to look for bin info.",
"format": "uuid",
"example": "30b8bec8-5042-4e67-939c-5453fbe41711"
},
"query_context": {
"$ref": "#/components/schemas/BinQueryContext"
}
},
"required": [
"encrypted_card",
"public_key_alias"
]
},
"BinQueryContext": {
"type": "object",
"properties": {
"supported_card_brands": {
"type": "array",
"description": "A list of card brands supported by the merchant for this context. This list will be used to filter results to supported card brands only.\n",
"items": {
"title": "The Card Brand",
"description": "The brand of this card, e.g. VISA, MASTERCARD, AMEX, CB, GIFT_CARD, etc.",
"type": "string",
"example": "VISA"
}
},
"amount_details": {
"type": "object",
"description": "Optional amount and currency of the transaction corresponding to this bin lookup.\n\nThese values will be used for the automatic selection of card brand for dual branded cards if MCR (Merchant Choice Routing)\nis enabled for the merchant and supported for the country.\n",
"required": [
"amount",
"currency_code"
],
"properties": {
"amount": {
"description": "Amount without a decimal place e.g. $1.5 = 150.\n\nThe required number of decimal places for a currency code is according to ISO 4217.\n",
"type": "integer"
},
"currency_code": {
"type": "string",
"title": "Currency Code",
"description": "Three-letter ISO 4217 alphabetical currency code. Supported values are: AUD",
"enum": [
"AUD"
]
}
}
}
}
},
"issuerCountryEnum": {
"type": "string",
"description": "The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code.Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
.",
"enum": [
"ZZZ",
"ABW",
"AFG",
"AGO",
"AIA",
"ALA",
"ALB",
"AND",
"ARE",
"ARG",
"ARM",
"ASM",
"ATA",
"ATF",
"ATG",
"AUS",
"AUT",
"AZE",
"BDI",
"BEL",
"BEN",
"BES",
"BFA",
"BGD",
"BGR",
"BHR",
"BHS",
"BIH",
"BLM",
"BLR",
"BLZ",
"BMU",
"BOL",
"BRA",
"BRB",
"BSB",
"BRN",
"BTN",
"BVT",
"BWA",
"CAF",
"CAN",
"CCK",
"CHE",
"CHL",
"CHN",
"CIV",
"CMR",
"COD",
"COG",
"COK",
"COL",
"COM",
"CPV",
"CRI",
"CUB",
"CUW",
"CXR",
"CYM",
"CYP",
"CZE",
"DEU",
"DJI",
"DMA",
"DNK",
"DOM",
"DZA",
"ECU",
"EGY",
"ERI",
"ESH",
"ESP",
"EST",
"ETH",
"FIN",
"FJI",
"FLK",
"FRA",
"FRO",
"FSM",
"GAB",
"GBR",
"GEO",
"GGY",
"GHA",
"GIB",
"GIN",
"GLP",
"GMB",
"GNB",
"GNQ",
"GRC",
"GRD",
"GRL",
"GTM",
"GUF",
"GUM",
"GUY",
"HKG",
"HMD",
"HND",
"HRV",
"HTI",
"HUN",
"IDN",
"IMN",
"IND",
"IOT",
"IRL",
"IRN",
"IRQ",
"ISL",
"ISR",
"ITA",
"JAM",
"JEY",
"JOR",
"JPN",
"KAZ",
"KEN",
"KGZ",
"KHM",
"KIR",
"KNA",
"KOR",
"KWT",
"LAO",
"LBN",
"LBR",
"LBY",
"LCA",
"LIE",
"LKA",
"LSO",
"LTU",
"LUX",
"LVA",
"MAC",
"MAF",
"MAR",
"MCO",
"MDA",
"MDG",
"MDV",
"MEX",
"MHL",
"MKD",
"MLI",
"MLT",
"MMR",
"MNE",
"MNG",
"MNP",
"MOZ",
"MRT",
"MSR",
"MTQ",
"MUS",
"MWI",
"MYS",
"MYT",
"NAM",
"NCL",
"NER",
"NFK",
"NGA",
"NIC",
"NIU",
"NLD",
"NOR",
"NPL",
"NRU",
"NZL",
"OMN",
"PAK",
"PAN",
"PCN",
"PER",
"PHL",
"PLW",
"PNG",
"POL",
"PRI",
"PRK",
"PRT",
"PRY",
"PSE",
"PYF",
"QAT",
"REU",
"ROU",
"RUS",
"RWA",
"SAU",
"SDN",
"SEN",
"SGC",
"SGP",
"SHN",
"SJM",
"SLB",
"SLE",
"SLV",
"SMR",
"SOM",
"SPM",
"SRB",
"SSD",
"STP",
"SUR",
"SVK",
"SVN",
"SWE",
"SWZ",
"SXM",
"SYC",
"SYR",
"TCA",
"TCD",
"TGO",
"THA",
"TJK",
"TKL",
"TKM",
"TLS",
"TON",
"TTO",
"TUN",
"TUR",
"TUV",
"TWN",
"TZA",
"UGA",
"UKR",
"UMI",
"URY",
"USA",
"UZB",
"VAT",
"VCT",
"VEN",
"VGB",
"VIR",
"VNM",
"VUT",
"WLF",
"WSM",
"YEM",
"ZAF",
"ZMB",
"ZWE"
]
}
}
},
"security": [
{
"BasicAuth": []
}
],
"paths": {
"/api/v2/card/card-details": {
"post": {
"operationId": "Binlookup",
"summary": "Bin lookup of Card Number",
"description": "The Card Details API endpoints will bin lookup and provides card details.",
"parameters": [
{
"name": "x-vfi-api-idempotencykey",
"required": false,
"in": "header",
"description": "Example: 63bbc548-d2de-4546-b106-880a5018461c \n\n A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "The Card Details API endpoints will bin lookup and provides card details.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/cardDetailsPrefixRequest"
},
{
"$ref": "#/components/schemas/cardDetailsEncryptedCardRequest"
}
]
}
}
}
},
"responses": {
"201": {
"description": "The details of the bin range or card. May contain more than one record if a co-branded card.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardDetailsResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestV2Docs"
}
}
}
},
"401": {
"description": "Unauthorised",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedV2Docs"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForbiddenV2Docs"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundV2Docs"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalErrorV2Docs"
}
}
}
}
},
"tags": [
"Bin"
]
}
}
},
"x-tagGroups": [
{
"name": "ECOMMERCE",
"tags": [
"Ecom Payments",
"Payment Modifications",
"Transaction",
"Secure Card Capture",
"Wallet"
]
},
{
"name": "Loyalty Program Operations",
"tags": [
"Redemption Order"
]
},
{
"name": "Balance Enquiry",
"tags": [
"Balance Enquiry"
]
},
{
"name": "Gift Card Operations",
"tags": [
"Load Card",
"Activate Card"
]
},
{
"name": "Bin",
"tags": [
"Bin"
]
},
{
"name": "Token Management",
"tags": [
"Token Management"
]
},
{
"name": "Health Check",
"tags": [
"Health"
]
}
]
}
```