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.

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

error_outline

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 name Description Required Length Data type
ssl_merchant_id Merchant ID
Elavon-assigned Converge account ID.		 Required 15 numeric
ssl_user_id Converge User ID
The user ID with Hosted Payment API User status that can send transaction requests through the terminal.		 Required 15 alphanumeric
ssl_pin Terminal ID
Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway.
error_outline

important

The ssl_user_id sending the transaction request must be associated with the terminal that will process the request.

 Required 64 alphanumeric
ssl_transaction_type Transaction Type
Valid value: binlookup		 Required 20 alphanumeric
ssl_card_number Card Number
Card Number as it appears on the debit card.		 Required 18 numeric
ssl_token Credit Card Token
The Token ID to delete from Card Manager.
error_outline

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.

 Required 20 alphanumeric
ssl_amount Transaction Amount
Amount sent for authorization, approval or refund.
Format: Number with 2 decimals places
error_outline

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.

 - 11 numeric
ssl_track_data Raw 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.		 Required 76 alphanumeric
ssl_enc_track_data Encrypted Raw Track I and/or II Data
Encrypted Track I and/or II data captured from the card's magnetic stripe or an Ingenico encrypting device. The data includes beginning and ending sentinels, card's expiry date, cardholder's first and last name.		 160 alphanumeric
ssl_enc_track_data_format Encrypted 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_encrypted_track1_data Encrypted Raw Track I Data
Track I data captured from a MagTek encrypting device.		 160 alphanumeric
ssl_encrypted_track2_data Encrypted Raw Track II Data
Track II data captured from a MagTek encrypting device.		 160 alphanumeric
ssl_ksn Key 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, ssl_enc_track1_data or ssl_enc_track2_data in the transaction request.		 20 alphanumeric

Response

Field name Description
fundingSource Funding Source
This fields returns on all binlookup responses.
Possible values:
Credit
Debit
ssl_amount Total Authorized/Approved Transaction Amount
The base amount for a transaction.
ssl_credit_surcharge_percent Credit Surcharge Percent
The percentage of the amount in ssl_amount applied as a surcharge.
ssl_credit_surcharge_amount Credit Surcharge Amount
The amount in USD added to ssl_amount as a surcharge.
ssl_total_amount Total Amount
The total of ssl_amount + ssl_credit_surcharge_amount
cardNumber Card Number
Card Number field. This field is specific to binlookup operations.
debit Debit 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.
pinless Pinless 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.
hsa Health 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.
billPaymentSupport Bill 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.
businessCard Business 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 Code Country Code
Returns the ISO Country code for the card.
This field is specific to binlookup operations.
dbIntechFraudInd Regulated 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.
ecommSupport Ecommerce 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.
internationalSupport InternationalSupport
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.
networkRoutingCode Network 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.
prepaidSupport Prepaid 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.
signatureSupport Signature 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.
fundingSource Funding 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.
surchargeAllowed Surcharge 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.

Examples

Card Request

<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_encrypted_track1_data></ssl_encrypted_track1_data>
    <ssl_encrypted_track2_data></ssl_encrypted_track2_data>
</txn>

Card Response

<txn>
  <cardNumber>55**********0008</cardNumber> 
  <debit>N</debit> 
  <pinless>N</pinless>
  <hsa>N</hsa>
  <billPaymentSupport>N</billPaymentSupport>
  <businessCard>N</businessCard>
  <countryCode>000</countryCode>
  <dbIntchFraudInd>N</dbIntchFraudInd>
  <ecommSupport>N</ecommSupport>
  <internationalSupport>N</internationalSupport>
  <networkRoutingCode>AF</networkRoutingCode>
  <posEligible>Y</posEligible>
  <prepaidSupport>N</prepaidSupport>
  <signatureSupport>N</signatureSupport>
  <fundingSource>C</fundingSource>
  <surchargeAllowed>Y</surchargeAllowed>
  <ssl_amount>100.00</ssl_amount>
  <ssl_credit_surcharge_percent>3</ssl_credit_surcharge_percent>
  <ssl_credit_surcharge_amount>3.00</ssl_credit_surcharge_amount>
  <ssl_total_amount>103.00</ssl_total_amount>
</txn>