PART 1 - API - Card BIN to Card Number in API (to BIN Intelligence API)
Connection Endpoints for Staging and Production
Version | Environment | Request Level Encryption | Endpoint | Description |
|---|---|---|---|---|
v2 | Staging | No | https://geostag.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/Load | N/A
|
Yes | https://geostag.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/EncryptedLoad | |||
Production | No | https://geo.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/Load | ||
Yes | https://geo.cardinalcommerce.com/DeviceFingerprintWeb/V2/Server/Bin/EncryptedLoad | |||
v3 | Staging | No | https://geostag.cardinalcommerce.com/DeviceFingerprintWeb/V3/Server/Bin/Load | We added support for 2 new fields: Card Type and AccountNumber within the BINs Object, specifically 2.x authentication transactions. |
Yes | https://geostag.cardinalcommerce.com/DeviceFingerprintWeb/V3/Server/Bin/EncryptedLoad | |||
Production | No | https://geo.cardinalcommerce.com/DeviceFingerprintWeb/V3/Server/Bin/Load | ||
Yes | https://geo.cardinalcommerce.com/DeviceFingerprintWeb/V3/Server/Bin/EncryptedLoad |
BIN Intelligence Request Field Names
Field | Description | Required | Version |
|---|---|---|---|
Signature | A mathematical scheme for verifying the authenticity of digital messages or documents. See examples below for generating the Signature value. | Y | v2 & v3 |
Timestamp | Java Epoch time in millis (0:00:00 UTC on 1 January 1970) | Y | v2 & v3 |
Identifier | api key identifier or Name value | Y | v2 & v3 |
Algorithm | The hashing algorithm used to generate the Signature value. Valid options include:
| Y | v2 & v3 |
TransactionId | Alpha numeric value transactionId. Length 5-55 characters long | Y | v2 & v3 |
OrgUnitId | Processor/Merchant level OrgUnitId, depending on the endpoint | Y | v2 & v3 |
Payload | The Payload for the BIN Intelligence request will contain an AccountNumber where the Card BIN to full Card Number will be passed. | Y | v2 & v3 |
BINs | This field represents the Consumer's Credit Card Number. The BINs field must contain at a minimum, the Card BIN (first 9 digits) to the full Card Number in the request. | Y | v2 & v3 |
AccountNumber | The account number to profile. Must be at least 9 digits. | Y | Only v3 |
CardType | Type of cards used for purchase. Possible Values: CB - Cartes Bancaires UPI - UnionPay International The CardType field is required for CB and UPI. It should not be included for any other card brands. |
C | Only v3 |
Examples of generating a Signature Value
SHA-256 Example
Timestamp: 2019-01-14T20:42:13.216Z
Milliseconds Since Epoch: 1547498533216
TransactionId: 07643622
ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44
Signature: wpGKFbhcBl+8JLVXGP0QqBooK6dtLBv9bYtI15NXL1U=
Generate Signature:
Signature = SHA-256(Epoch + TransactionId + ApiKey)
where, TransactionId is optional. |
SHA-512 Example
Timestamp: 2019-01-14T20:42:13.216Z
Milliseconds Since Epoch: 1547498533216
TransactionId: 07643622
ApiKey: 13f1fd1b-XXXX-XXXX-XXXX-ca61878f2a44
Signature: SBF4wmV5LPCsb7Em+Yfa2RB4xtohV8s2ffYArhPUrZqjEsgUjbuVzBPyhgYma5x71T5y7dIHPJHE2uqL3Vp0Hg==
Generate Signature:
Signature = SHA-512(Epoch + TransactionId + ApiKey)
where, TransactionId is optional. |
Example of the BIN Intelligence JSON Request/Response
v2 BIN Intelligence Request/Response
JSON Request {
"Signature": "rDblGQSJujgHEeuvqTbJjB6Fktsodddiri6+F5do9cA=",
"Timestamp": "2018-08-12T14:23:02.941Z",
"Identifier": "aalkjdfalkdjfaslkdj",
"Algorithm": "SHA-256",
"TransactionId": "132456789",
"OrgUnitId": "565607c18b111e058463ds8r",
"Payload": {
"BINs": ["44444444"]
}
}JSON Response |
v3 BIN Intelligence Request/Response
Single PANs
In the event where a merchant is passing single account number, they must pass at least 8 digits to allow Centinel to correctly identify the 3DS Method. The more number of digits a merchant passes for the PAN, Centinel has a better chance to accurately determine the 3DS Method.
JSON Request JSON Response |
Multiple Cards on File
Multiple Card-on-File Scenario:
Merchants can pass multiple account numbers (up to 3) on the BIN Intelligence API request (as shown below). This allows Centinel to run all 3DS Methods associated with these account numbers. This helps alleviate any need to re-run Device Data Collection, should the consumer select a different payment method (based on stored payment credentials). Merchants must pass at least 13 digits of the account number.
JSON Request JSON Response |
Encrypted BIN Intelligence Request/Response
Encrypted Request JSON Response |
Handling the BIN Intelligence Response with ReferenceId
The BIN Intelligence response will include a ReferenceId and DeviceDataCollectionUrl if successful, these two values will be used when invoking the DeviceDataCollectionUrl within an iframe on your website. We are essentially initiating the session with the Card BIN to full Card Number and returning back a ReferenceId to invoke the frontend DeviceDataCollectionUrl.
BIN Intelligence Response Fields
Field | Type | Description | Required |
|---|---|---|---|
ErrorNumber | AN(255) | Application error number. A non-zero value represents the error encountered while attempting the process the message request. | Y |
TransactionId | AN(50) | A transaction identifier returned back from Cardinal | Y |
Payload | The Payload for the BIN Intelligence response will contain a ReferenceId and a DeviceDataCollectionUrl | Y | |
ReferenceId | AN(50) | This identifier represents the DeviceDataCollection session that has been started. It must be passed in the Authentication JWT when invoking the DeviceDataCollectionUrl and during the cmpi_lookup request as a DFReferenceId. | Y |
DeviceDataCollectionUrl | AN(100) | The DeviceDataCollectionUrl is the location to send the Authentication JWT when invoking the Device Data Collection process. | Y |