search

POSTFetch Bin Details API

Use Case

This API is used to check if the BIN entered by the user is a valid card or token BIN with which Paytm can process a payment. Further, the API can serve the following purpose:-

  • To get attributes such as card scheme, card type and issuing bank of the card or token BIN
  • To get attributes such as card country code, country name, currency name and currency symbol for international card or token BIN
  • To check if subscription payment is available on the card or token BIN
  • To check if EMI payment is available on the card or token BIN
  • To check Native-OTP is eligibile for on the card or token BIN

Note: The API should be called with the first 9 digits for card or token number for accurate and updated response.

Query Params

ATTRIBUTE DESCRIPTION

mid

string
mandatory

Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.
Example: INTEGR7769XXXXXX9383

orderId

string
conditional

This is the unique identifier for order and should have the same value as used in orderId of Initiate Transaction API or Initiate Subscription API.
Note: It becomes mandatory in case tokenType value is sent as CHECKSUM or TXN_TOKEN in this request.
Example: OREDRID_98765

referenceId

string
conditional

This is the unique reference id and should have the same value as used in Access Token API.
Note: It becomes mandatory in case tokenType value is sent as ACCESS in the request.

 

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string
optional

Version of the API.

Example: v1

requestTimestamp
string
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

channelId
string
mandatory

The parameter value identifies the Channel for which API call is initiated.

Possible values:
WEB
For websites, the value to be passed should be "WEB"
,
WAP
For Mobile websites/App, the value to be passed should be "WAP"
tokenType
string
mandatory

Authorization method for this request.

Possible values:
ACCESS
To be used in case authentication is done using access token.
,
CHECKSUM
To be used in case authentication done using Checksum.
,
TXN_TOKEN
To be used in case authentication done using transaction token.
token
string
mandatory

Authorization string corresponding to the tokenType used.

Example: 739816707d7444XXXXXXXX6cb4264d0a1590145379323

Body

AttributeDescription
bin
string
mandatory

The first 9 digits of the card number or card token.
Example: 537652176

mid
string
conditional

Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.

Example: INTEGR7769XXXXXX9383

Note: It becomes mandatory in case tokenType value is send as ACCESS in the request.

paymentMode
string
optional

The payment mode used by customer for transaction.

Possible values:
CREDIT_CARD
For Credit Card
,
DEBIT_CARD
For Debit Card
emiType
string
optional

The emi type used by customer for transaction.

Possible values:
CREDIT_CARD
For Credit Card
,
DEBIT_CARD
For Debit Card
channelCode
string
optional

Bank Code for which the EMI details are required

Possible Values: ICICI, HDFC

txnType
string
optional

This parameter is used to identify the payment flow.

Possible values:
NONE
By Default
,
ADDANDPAY
For Add and Pay
,
HYBRID
For Hybrid
isEMIDetail
string
optional

Returned in response, if the InitiateTxn request had requestType PAYMENT, NATIVE_SUBSCRIPTION

cardPreAuthType
string
optional

The type of Pre-Auth flow - Standard/Delayed that is to be used for the transaction. 
If not provided in this API the cardPreAuthType used in Access Token API can be used.

Example : STANDARD_AUTH, DELAYED_AUTH

STANDARD_AUTH : This pre-auth flow involves blocking of amount in the customer’s account to be captured/released at a later stage.

DELAYED_AUTH : This flow involves no blocking of amount but only the authorization for this transaction is done at a later stage.

Note: This parameter is applicable for only Pre-auth flow applicability needs to be checked for the requested BIN.
requestType
string
conditional

This parameter is used to identify the transaction flow.
use 'NATIVE_SUBSCRIPTION' to check if subscription payments are available on a BIN or not.

nativeOTPDetailRequired
string
optional

This parameter is used to identify whether the bin supports Native OTP flow or not.     

Possible Values: true

Response Attributes

Content Type : JSON

Head

AttributeDescription
version
string

Version of the API passed in the request.
Example: v1

responseTimestamp
string

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

Body

AttributeDescription
resultInfo
object

This parameter gives the information about the result of the API response

ResultInfo
+
AttributeDescription
resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.

resultStatus
string

This parameter indicates the status of API call.

Possible Values: S, F, U

resultMsg
string

This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
 

binDetail
object

BIN details like issuing bank name and card scheme (Visa/Master..) are provided here

BinDetail
+
AttributeDescription
bin
string

Bank Identification Number

Example: 411111

issuingBank
string

issuing Bank

Example: ICICI Bank

issuingBankCode
string

Bank Code

Example: ICICI

paymentMode
string

The payment mode used by customer for transaction. If it is 'EMI', we check for EMI details for a particular emiType and channelCode only.

Example: CREDIT_CARD

channelName
string

Name of card scheme of the BIN

Example: VISA

channelCode
string

Code of card scheme of the BIN

Example: VISA

cnMin
string

Minimum card number digits

Example: 13

cnMax
string

Maximum card number digits

Example: 19

cvvR
string

CVV required or not

Possible Values: true, false

cvvL
string

CVV length

Example: 3

expR
string

Expiry required or not

Possible Values: true, false

IsIndian
string

Whether card is Indian or not

Possible Values: true, false

IsActive
string

BIN status

Possible Values: true, false

countryCode
string

The ISO 2-letter country code of the issuer.  
Example: IN

countryName
string

The full country name of the issuer.
Example: India

countryNumericCode
string

The ISO 3-letter country code of the issuer.
Example: 356

currencyCode
string

The ISO 4217 currency code associated with the country of the issuer.
Example: INR

currencyName
string

The full currency name associated with the country of the issuer.
Example: Rupee

currencyNumericCode
string

The ISO 3166 currency code associated with the country of the issuer.  
Example: 356

currencySymbol
string

The symbol of the currency associated with the country of the issuer.
Example: ₹

isEligibleForCoft
boolean

Status whether bin is eligible for card on file tokenization or not.

Possible Values: true, false

isCoftPaymentSupported
boolean

Status whether bin supports token payment or not.

Possible Values: true, false

isEligibleForAltId
boolean

Status whether bin is eligible for alt id generation.

Possible Values: true, false

isAltIdPaymentSupported
boolean

Status whether bin supports alt id payment or not.
Possible Values: true, false

hasLowSuccessRate
object

Identifier to depict the low success rate on the payment mode/instrument in the past 15 minutes. If the success rate is low, the user should be communicated the same on the cashier page and motivated to choose a different payment instrument.

HasLowSuccessRate
+
AttributeDescription
status
boolean

If the success rate is lower in last 15 minutes, then the value is returned as true

msg
string

Message to display the user about the low success rate

IsEmiAvailable
string

Depicts, if the EMI is available on the selected BIN or not

Possible Value: True, False

supportedCardSubTypes
array

Provides an identifier for various types of cards. Depending on your agreement, you can be charged differently for a different card.

ExampleCORPORATE_CARD which Indicates if the card used is a corporate card. Typically a merchant is charged differently for a prepaid card compared to a debit card. 

authModes
array

Auth mode available on the BIN

Possible values:
otp
For Mobile OTP
,
atm
For atm pin
iconUrl
string

Icon URL of issuing bank of saved card

errorMessage
string

Captures the error encountered

isSubscriptionAvailable
boolean

Depicts if subscription payments are available on this BIN or not. In case the value is true, then subscription payments are supported.

Note: If TXN_TOKEN is used, It must be the same value as found in txnToken of Initiate Subscription API response.

 

pcf
object

Post convenience fees if applicable

PCF
+
AttributeDescription
feeAmount
object

Post convenience fees

Money
+
AttributeDescription
value
string

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

taxAmount
object

Total tax amount

Money
+
AttributeDescription
value
string

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

totalTransactionAmount
object

Total txn amount after including pcf charges

Money
+
AttributeDescription
value
string

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

extraParamsMap
object

Map for any additional data that is required to be provided in the response.

isHybridDisabled
boolean

Specifies whether the Hybrid paymode is disabled on this card or not

prepaidCard
string

Indicates, if the card used is a prepaid card or not. Typically a merchant is charged differently for a prepaid card compared to a debit card.

Possible Value: True, False

prepaidCardMaxAmount
string

Maximum amount of payment allowed on that prepaid card. Prepaid cards do not support payments beyond a threshold set by the bank. This is INR 1.0 Lakh.

preAuthDetails
object

The pre-auth level details for the selected BIN and flow type.

Pre-Auth Details
+
AttributeDescription
isDisbaled
boolean

Returns if the selected Pre-Auth flow is disabled on the BIN 

maxBlockSeconds
string

The maximum time period for which the amount can be blocked in customers account for the selected BIN

Example : 172800

cardPreAuthType
string

The type of Pre-Auth flow - Standard/Delayed that is to be used for the transaction.

Example : STANDARD_AUTH, DELAYED_AUTH

STANDARD_AUTH : This pre-auth flow involves blocking of amount in the customer’s account to be captured/released at a later stage.

DELAYED_AUTH : This flow involves no blocking of amount but only the authorization for this transaction is done at a later stage.

nativeOtpEligible
string

This parameter indicates if the Native OTP support is available on the requested BIN or not.                      

Possible Value: True, False

Response Codes & Messages

resultCoderesultStatusresultMsg
0000SSuccess
200Fsuccessful operation
1003FBin number is not valid
1006FSession Expired Exception
2011FPayment not allowed for your card,Please try again using other card
2013FMid in the query PARAM doesn’t match with the Mid send in the request
2014FOrderId in the query param doesn’t match with the OrderId send in the request
00000900USystem error
⇾
Staging
Production
https://securegw-stage.paytm.in/fetchBinDetail?mid={mid}&orderId={order-id}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/fetchBinDetail?mid={mid}&orderId=ORDERRID_98765' \
--header 'Content-Type: application/json' \
--data '{"body":{"bin":"411111"},"head":{"tokenType":"TXN_TOKEN","channelId": "WEB","token":"f0bed899539742309eebd8XXXX7edcf61588842333227"}}'
copy icon