Look up BIN information

Browse API reference

POST/cards/bin-lookupbinLookup

Use this method to retrieve information about a debit card, a credit card, or an EBT card. If you apply surcharges to transactions, you can also check if the card supports surcharging.

In the response, our gateway returns the following information about the card:

Card details - Information about the card, for example, the issuing bank and the masked card number.
Surcharging information - If you apply a surcharge to transactions, our gateway checks that the card supports surcharging and returns information about the surcharge. For more information about surcharging, go to Credit card surcharging.

Request body

application/json · required

Field Edit request inputs →

amountintegerint64
Transaction amount that you send to check the surcharge amount. The value is in the currency's lowest denomination, for example, cents.
cardobjectrequired
Polymorphic object that contains payment details. The value of the type parameter determines which variant you should use: card Payment card details cardBin Bank identification number (BIN) of the payment card secureToken Secure token details digitalWallet Digital wallet details
- cardobject
  Object that contains information about the customer’s payment card.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardDetailsobjectrequired
    Polymorphic object that contains payment card information. The value of the entryMethod parameter determines which variant you should use: raw Unencrypted payment data directly from the device. icc Payment data that the device captured from the chip. keyed Payment data that the merchant entered manually. swiped Payment data that the device captured from the magnetic strip.+132 more fields at deeper levels — see the full spec
  - typestringrequired
    Method that the terminal used to take the payment.card
- cardBinobject
  Object that contains information about the card's bank identification number (BIN).
  - binstringrequired
    6–12 chars
  - typestringrequired
    Method that the terminal used to take the payment.cardBin
- secureTokenobject
  Object that contains information about the secure token that represents the customer’s payment details.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only if the secure token represents bank account details.checkingsavings
  - secCodestring
    Indicates how the customer authorized the ACH transaction. Send one of the following values: web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction. Note: This field is mandatory when the secure token represents ACH bank account details.webtelccdppd
  - tokenstringrequired
    Unique token that the gateway assigned to the payment details.12–19 chars
  - typestringrequired
    Method that the terminal used to take the payment.secureToken
- digitalWalletobject
  Object that contains information about the payment details in the customer’s digital wallet.
  - accountTypestring
    Indicates the customer’s account type. Note: Send a value for accountType only for bank account details.checkingsavings
  - cardholderNamestring
    Cardholder’s name.0–50 chars
  - encryptedDatastringrequired
    Encrypted data of the digital wallet.128–20480 chars
  - serviceProviderstringrequired
    Provider of the digital wallet. Send one of the following values: apple For more information about how to integrate with Apple Pay, go to Apple Pay®. google For more information about how to integrate with google Pay, go to Google Pay®.applegoogle
  - typestringrequired
    Method that the terminal used to take the payment.digitalWallet
currencystring
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
processingTerminalIdstring
Unique identifier that we assigned to the terminal. We recommend that you include the processingTerminalId to make sure that we return the correct surcharge information for the terminal.4–50 chars

Responses

Successful request. Returns the BIN information.

200 OK · application/json

{
  "cardNumber": "453985******7062",
  "country": "US",
  "currency": "USD",
  "debit": false,
  "healthcare": false,
  "type": "Visa Credit"
}

Response schema · 11 fields

cardNumberstringrequired
Masked card number. Our gateway shows only the first six digits and the last four digits of the card number, for example, 548010******5929.12–19 chars
countrystringiso-3166-1
Country of the issuing bank. The value for the country follows the ISO-3166-1 standard.
currencystring
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
debitboolean
Indicates if the card is a debit card.
healthcareboolean
Indicates if the card is linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). The value is one of the following: true Card is linked to an FSA or an HSA. false Card isn't linked to an FSA or an HSA.
surchargingobject
Object that contains surcharge information. Our gateway returns this object only if the merchant adds a surcharge to transactions.
- allowedbooleanrequired
  Indicates if the merchant can add a surcharge when the customer uses this card.
- amountintegerint64
  Surcharge amount to add to the transaction. Note: Our gateway returns the surcharge amount only if you include a transaction amount in the request.
- disclosurestring
  Statement that informs the customer about the surcharge fee.
- percentagenumberdouble
  Surcharge rate that the merchant configures on their account.≤ 100
typestringrequired
Card brand of the card, for example, Visa.

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

look-up-bin

Look up BIN information

Browse API reference

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer