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.

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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

resultInfo

object

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

ResultInfo

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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.

Example: CORPORATE_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

Attribute

Description

feeAmount

object

Post convenience fees

Money

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

resultCode	resultStatus	resultMsg
0000	S	Success
200	F	successful operation
1003	F	Bin number is not valid
1006	F	Session Expired Exception
2011	F	Payment not allowed for your card,Please try again using other card
2013	F	Mid in the query PARAM doesn’t match with the Mid send in the request
2014	F	OrderId in the query param doesn’t match with the OrderId send in the request
00000900	U	System 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"}}'