Fetch Bin Details API

Checksum required: NO

Use Case


  • To check if the BIN entered by the user is a valid card BIN from which Paytm can process a payment
  • To check if subscription payments is available on the BIN. e.g. subscription is not supported on SBI DC. Hence if a user enters a BIN belonging to SBI DC, subscription unavailability will be indicated in isSubscriptionAvailable attribute
  • To get the card details like card scheme and issuing bank of the BIN
  • To get past 15 minutes success rate on the BIN. In case the success rate is low, then the customer can be notified to use another card or payment method

Note:

  • This API should be called the moment customer completes entering first 6 digits of the card. In case of an error received in response, same should be notified to the customer instantly

Request Attributes:

API Content format: JSON

Head

PARAMETERDESCRIPTIONMANDATORY
Version String (4)Version of the API. Current version is v1YES
requestTimestamp String (15)UNIX timestamp of the time request is being sentNO
channelId String (3)For websites, the value is WEB,For Mobile websites/App, the value is WAPYES
txnToken String (64)Provided in response of Create Subscription/ Initiate Transaction APIYes

Body

PARAMETERDESCRIPTIONMANDATORY
bin String (6)Starting 6 digits of credit or debit card numberYes
paymentMode String (3)If it is 'EMI' , we check for EMI details for a particular emiType and channelCode onlyNo
emiType String (11)CREDIT_CARD/DEBIT_CARDNo
channelCode String (5)Bank Code for which EMI details are requiredNo
txnType String (7)Payment flow - NONE/ADDNPAY/HYBRIDNo
isEMIDetail StringReturned in response if InitiateTxn request had requestType PAYMENT, NATIVE_SUBSCRIPTIONNo

Response Attributes:

API Content format: JSON

Head

PARAMETERDESCRIPTIONMandatory
Version String (2)Version of the API passed in the requestYES
responseTimestamp String (15)UNIX Timestamp of the responseYES

Body

PARAMETERDESCRIPTIONMandatory
binDetail BinDetailBin details like issuing bank name, Card scheme (Visa/Master..) are provided hereYES
hasLowSuccess hasLowSuccessIdentifier to depict low success rate on the payment mode/instrument in past 15 minutes. If the success rate is low, user should be communicated the same on the cashier page and motivated to choose a different payment instrumentYES
authMode Array of String (5)Auth mode available on bin (PIN/OTP)YES
iconUrl String (255)Icon URL of issuing bank of saved cardYES
resultInfo ResultInfoResult information of API requestYES
errorMessageCaptures the error encounteredYES
isSubscriptionAvailable BooleanDepicts if subscription payments is available on this BIN or not. In case the value true, then subscription payments is supportedNO
pcf pcfPost convenience fees if applicableNO
extraParamsMap Map<String , Object>Map for any additional data that is required to be provided in the responseNO
isHybridDisabled BooleanSpecifies whether Hybrid paymode is disabled on this card or notYES

BinDetail

PARAMETERDESCRIPTIONMANDATORY
bin String (6)Bin noYES
issuingBank String (100)issuing BankYES
issuingBankCode String (15)Bank Code. For eg : SBI,HDFCYES
paymentMode String (15)Payment mode of card - Credit_Card, Debit_CardYES
channelName String (15)Name of card scheme of the BIN - Visa,Master, Rupay etc.YES
channelCode String (15)Code of card scheme of the BIN - Visa, Master, Rupay etc.YES
cnMin String (2)Minimum card number digitsYES
cnMax String (2)Maximum card number digitsYES
cvvR String (5)Cvv required or notYES
cvvL String (1)Cvv lengthYES
expR String (5)Expiry required or notYES
isIndian String (5)Whether card is Indian or notYES
isActive String (5)Bin status (true, false)YES

hasLowSuccess Json Object

PARAMETERDESCRIPTIONMANDATORY
status BooleanIf success rate is lower in last 15 minutes, then the value is returned as trueYES
msg String (500)Message to display the user about the low success rateNO

ResultInfo

PARAMETERDESCRIPTIONMANDATORY
resultStatusString (S(Success), F(Failure), U(Unknown))Status of API callYes
resultCodestringResult code returned to merchant . Max length of result code can be 64Yes
resultMsgstring (Max length can be 256])Result Message contains information about the result.Yes

Pcf json object

PARAMETERDESCRIPTIONMANDATORY
feeAmount MoneyPost convenience feesYES
taxAmount MoneyTotal tax amountYES
totalTransactionAmount MoneyTotal txn amount after including pcf chargesYES

Money

PARAMETERDESCRIPTIONMANDATORY
currency string (length = 3)Currency Code (INR)YES
value string (regexp = [0-9]+([.][0-9]{1, 2})?, length less than 16 characters)Transaction value upto decimalYES
## Refund Status Response Codes and Description
RESPONSE CODEDESCRIPTION
1006Session Expired Exception
200successful operation
2013Mid in the query PARAM doesn’t match with the Mid send in the request
2014OrderId in the query param doesn’t match with the OrderId send in the request
0000Success
00000900System error
1003Bin number is not valid
2011Payment not allowed for your card,Please try again using other card

Endpoints

Staging: https://securegw-stage.paytm.in/fetchBinDetail?mid=<mid>&orderId=<orderId>

Production: https://securegw.paytm.in/fetchBinDetail?mid=<mid>&orderId=<orderId>

Request CodeResponse JSON
curl -X POST 'https://securegw-stage.paytm.in/fetchBinDetail?mid=xxxxxxxxxxxxxxxxxxxx&orderId=xxxxxxxxxxxxxxxxxxxx' --header 'Content-Type: application/json' --data '{"head":{"version":"v1","requestTimestamp":xxxxxxxxxx,"channelId":"XXX","txnToken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},"body":{"bin":"xxxxxx"}}