BIN Lookup - binlookup

Use binlookup to get access to the Bank Identification number of a card. The results of binlookup determine whether a card is a debit or credit card.

In this section:

For the entire list of API endpoints, refer to API Endpoints.

Requirements

binlookup is available on terminals with the following settings:

  • Region set to USA
  • Market segment set to one of the following
    • Retail
    • MOTO
    • Internet
    • Service

Binlookup and Surcharging

note

binlookup is an important step in implementing surcharges on credit card users. Before applying a surcharge to a user, use a BIN lookup request to determine whether a card is a debit or credit card.

Every binlookup will return the field surchargeAllowed. If this field returns Y, the card that the binlookup was for is a credit card and may have surcharges applied to it. If this field returns N, then the card is not a credit card and should not have surcharge applied.

Request

Field nameDescriptionRequiredLengthData type
ssl_merchant_idMerchant ID
Elavon-assigned Converge Account ID (AID).
Required6 or 7numeric
ssl_user_idConverge User ID
The user ID with Hosted Payment API User status that can send transaction requests through the terminal.
Required15alphanumeric
ssl_pinTerminal ID
Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway.
The ssl_user_id sending the transaction request must be associated with the terminal that will process the request.
Required64alphanumeric
ssl_transaction_typeTransaction Type
Valid value:  binlookup
Required20alphanumeric
ssl_card_numberCard Number
Card Number as it appears on the debit card.
Required18numeric
ssl_tokenCredit Card Token
The Token ID to delete from Card Manager.
Important:
- All information associated with the token will be removed.
- The token must already be stored in Card Manager.
- Use only if the terminal is set up with the Tokenization terminal option.
Required20alphanumeric
ssl_amountTransaction Amount
Amount sent for authorization, approval or refund.
Format: Number with 2 decimals places
Important: When submitting transaction amounts to terminals that are set up with the Multi Currency credit payment option, make sure that the number of decimal places are correct as some currencies have 0 (like JPY) or 3 (like BHD) decimal places.
-11numeric
ssl_track_dataRaw Track I and/or II Data
Track data captured from the card’s magnetic stripe. The data includes beginning and ending sentinels, card’s expiry date, cardholder’s first and last name.
Required76alphanumeric
ssl_enc_track_dataEncrypted Raw Track I and/or II Data
Encrypted Track I and/or II data captured from the card’s magnetic stripe or an encrypting device. The data includes beginning and ending sentinels, card’s expiry date, cardholder’s first and last name.
160alphanumeric
ssl_enc_track_data_formatEncrypted Raw Track I and/or II Data Format
Format of the Track data captured from the card’s magnetic stripe. Required if card is read from a ROAM device.
Valid value:  ROAM_GENERIC_TDES_EMV
---
ssl_ksnKey Serial Number
Unique identifier generated from the swiped payment card and returned by the encrypting device. The KSN encrypts the PAN data through the DUKPT method.
Required if submitting ssl_enc_track_data in the transaction request.
20alphanumeric

Response

Field nameDescription
fundingSourceFunding Source
This fields returns on all binlookup responses.
Possible values:
  • Credit
  • Debit
ssl_amountTotal Authorized/Approved Transaction Amount
The base amount for a transaction.
ssl_credit_surcharge_percentCredit Surcharge Percent
The percentage of the amount in ssl_amount applied as a surcharge.
ssl_credit_surcharge_amountCredit Surcharge Amount
The amount in USD added to ssl_amount as a surcharge.
ssl_total_amountTotal Amount
The total of ssl_amount + ssl_credit_surcharge_amount
cardNumberCard Number
Card Number field. This field is specific to binlookup operations.
debitDebit Check
Shows whether the card was a debit card.
Possible Values:
  • Y - Returned if the card is a debit card.
  • N - Returned if the card is not a debit card.

This field is specific to binlookup operations.
pinlessPinless Supported
Shows whether the card supports pinless transactions.
  • Y - Returned if the card supports pinless transactions.
  • N - Returned if the card doesn’t support pinless transactions.

This field is specific to binlookup operations.
hsaHealth Savings Account Linked
Shows whether the card is linked to a health savings account.
Possible Values:
  • Y - Returned if the card is linked to a health savings account.
  • N - Returned if the card is not linked to a health savings account.

This field is specific to binlookup operations.
billPaymentSupportBill Payment Support
Shows whether the card supports online bill payment.
Possible Values:
  • Y - Returned if the card supports online bill payment.
  • N - Returned if the card does not support online bill payment.

This field is specific to binlookup operations.
businessCardBusiness Card Support
Shows whether the card supports L2, which includes customer codes and sales tax.
Possible Values:
  • Y - Returned if the card supports L2.
  • N - Returned if the card does not support L2.

This field is specific to binlookup operations.
Country CodeCountry Code
Returns the ISO Country code for the card.
This field is specific to binlookup operations.
dbIntechFraudIndRegulated With Fraud
Indicates whether this card is regulated with fraud.
Possible Values:
  • Y - Returned if the card supports regulated with fraud.
  • N - Returned if the card does not support regulated with fraud.

This field is specific to binlookup operations.
ecommSupportEcommerce Supported
Indicates whether this card supports online, one-off transactions.
Possible Values:
  • Y - Returned if the card supports eCommerce.
  • N - Returned if the card does not support eCommerce.

This field is specific to binlookup operations.
internationalSupportInternationalSupport
Indicates whether this card supports international transactions.
Possible Values:
  • Y - Returned if the card supports international transactions.
  • N - Returned if the card does not support international transactions.

This field is specific to binlookup operations.
networkRoutingCodeNetwork Routing Code
Indicates the processor network for a card.
If this result returns Elavon, the card is a credit card. Otherwise, the card will return the debit network the card transaction was routed over.
This field is specific to binlookup operations.
prepaidSupportPrepaid Support
Indicates whether the card is a prepaid card.
Possible Values:
  • Y - Returned if the card is a prepaid card.
  • N - Returned if the card is not a prepaid card.

This field is specific to binlookup operations.
signatureSupportSignature Supported
Indicates whether this card supports debit signature with no PIN.
Possible Values:
  • Y - Returned if the card supports debit signature with no PIN.
  • N - Returned if the card does not support debit signature with no PIN.

This field is specific to binlookup operations.
fundingSourceFunding Source
Indicates whether this card is using credit or debit as a funding source.
Possible Values:
  • C - Returned if the card is a credit card.
  • D - Returned if the card is a debit card.

This field is specific to binlookup operations.
surchargeAllowedSurcharge Allowed
Indicates whether a credit surcharge can be applied to this card.
Possible Values:
  • Y - Returned if a credit surcharge can be applied to this card.
  • N - Returned if a credit surcharge cannot be applied to this card.

This field is specific to binlookup operations.
cardProductTypeCode  Code indicating the card product type.
This field is specific to binlookup operations. 
pinlessDebitEnabled  Pinless Supported for debit card
Shows whether the debit card supports pinless transactions.
  • Y - Returned if the debit card supports pinless transactions.
  • N - Returned if the debit card doesn’t support pinless transactions.

This field is specific to binlookup operations.  
octeligible  Used to identify if the transaction is eligible for a disbursement as an Original Credit Transaction (OCT). 
Possible Values:
  • Y - Transaction is eligible for OCT Disbursement
  • N - Transaction is NOT eligible for OCT Disbursement

This field is specific to binlookup operations.
pinlessDebitThreshold
quickServeSupport  Debit Quick Serve (QSR) indicator without PIN under $50
This field is specific to binlookup operations.  
institutionName The issuing bank name for China Union Pay debit cards  
This field is specific to binlookup operations.

Examples

Card Request

xmldata=
<txn>
    <ssl_merchant_id>000006</ssl_merchant_id>
    <ssl_user_id>su06</ssl_user_id>
    <ssl_pin>NL1F6KYN6E7JK72MGQC40QB7AYMC3DVZQ1LIXO96MIEB8E9P5QEVQOFXJNS9YTNX</ssl_pin>
    <ssl_transaction_type>BINLOOKUP</ssl_transaction_type>
    <ssl_card_number>5546710000000008</ssl_card_number>
    <ssl_track_data></ssl_track_data>
    <ssl_track_data_format></ssl_track_data_format>
    <ssl_enc_track_data></ssl_enc_track_data>
</txn>

Card Response

<txn>
   <cardNumber>4643********1504</cardNumber>
   <debit>Y</debit>
   <surchargeAllowed>N</surchargeAllowed>
   <fundingSource>D</fundingSource>
   <pinlessDebitEnabled>N</pinlessDebitEnabled>
   <hsa>N</hsa>
   <billPaymentSupport>N</billPaymentSupport>
   <businessCard>N</businessCard>
   <cardProductTypeCode>RF</cardProductTypeCode>
   <countryCode>840</countryCode>
   <dbIntchFraudInd>Y</dbIntchFraudInd>
   <ecommSupport>N</ecommSupport>
   <institutionName/>
   <internationalSupport>N</internationalSupport>
   <networkRoutingCode>ST</networkRoutingCode>
   <posEligible>Y</posEligible>
   <prepaidSupport>N</prepaidSupport>
   <signatureSupport>N</signatureSupport>
   <quickServeSupport>N</quickServeSupport>
   <pinlessDebitThreshold>50</pinlessDebitThreshold>
   <octeligible>N</octeligible>
</txn>