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 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. 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: `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

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>