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
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 (AID). | Required | 6 or 7 | 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. 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. 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 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:
|
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:
This field is specific to binlookup operations. |
pinless | Pinless Supported Shows whether the card supports 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:
This field is specific to binlookup operations. |
billPaymentSupport | Bill Payment Support Shows whether the card supports online bill payment. Possible Values:
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:
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:
This field is specific to binlookup operations. |
ecommSupport | Ecommerce Supported Indicates whether this card supports online, one-off transactions. Possible Values:
This field is specific to binlookup operations. |
internationalSupport | InternationalSupport Indicates whether this card supports international transactions. Possible Values:
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:
This field is specific to binlookup operations. |
signatureSupport | Signature Supported Indicates whether this card supports debit signature with no PIN. Possible Values:
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:
This field is specific to binlookup operations. |
surchargeAllowed | Surcharge Allowed Indicates whether a credit surcharge can be applied to this card. Possible Values:
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_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>