paytm developer docs logoDeveloperDocumentation
search

POSTTokenize Card API

Use Case

Used to tokenize a card to create a server-based Token. Paytm TG will perform both card availability and eligibility checks to check that this specific card is eligible for tokenization. The tokenization decision will be one of Successful or Failed.

Request Attributes

Content Type : JSON

Head

AttributeDescription
Version
string
mandatory

Version of the API
Possible Value: v1

requestTimestamp
string
mandatory

EPOCH timestamp of the time at which request is being sent

Possible Value: 1588402269

requestId
string
mandatory

Merchant’s Unique Request ID for card tokenization

Possible Value: Any

signature
string
mandatory

Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.

Possible Value: Any

signatureType
string
mandatory

Authorization method for this request.

Possible Value: CHECKSUM

clientId
string
optional

Paytm uses the merchant key on the basis of clientId parameter value. It is required only if the merchant has more than one key.

encryptionKeyVersion
string
optional

Paytm uses the merchant key on the basis of the encryption key version. It is required only if the merchant has more than one key.

Possible Value: v1

Body

AttributeDescription
authRefId
string
conditional

Authentication ID for the 2FA transaction generated as received from the acquirer.
Condition: To be provided mandatorily for RupayCards

cardSource
string
mandatory

The source where PAN data was captured. Must be one of the possible values.
CARD_ON_FILE: If the merchant already has the PAN data in storage.
MANUAL_ENTERED:  PAN data is manually entered by the cardholder.
CARD_SCAN: PAN data is manually captured via a camera/OCR

encryptedCardData
string
mandatory

Encrypted card data string with RSA Encryption logic

Decrypted String: {"cardNumber":"4111XXXXXXXX1111","expiryMonth":"10","expiryYear":"2022","securityCode":"123"}

Note: This is sample string which is encrypted by RSA Encryption logic and used here.

userInfo
string
mandatory

Customer info object

userInfoCoft
+
AttributeDescription
custId
string
mandatory

 Merchant customer id/consumer id

Possible Values: Any

firstName
string
optional

Customer/consumer first name

Possible Values: Any

lastName
string
optional

Customer/consumer last name

Possible Values: Any

mobileNumber
string
optional

Customer/consumer mobile no

Possible Value: Any (valid mobile no)

tokenizationConsent
string
mandatory

User consent detail

tokenizationConsent
+
AttributeDescription
userConsent
boolean
mandatory

Tokenisation consent from the user in a boolean expression
Sample Value: (1,0) 

createdAt
string
mandatory

Timestamp when user consented for tokenization was captured
Sample Value: Jul 22, 2021 02:46:54 PM

userConsentId
string
optional

The ID of the message displayed to the user for consent

language
string
optional

Language in which consent was accepted by end customer
Sample Value: en

platform
string
optional

PHONE, TABLET, PC, WATCH, OTHER,API
Sample Value: APP

os
string
optional

The OS on which consent was given by the user such as Android, IOS, Windows, Web, Others
Sample Value:androidapp

appVersion
string
optional

App version of merchant or Paytm on which consent was collected
Sample Value: 9.10.2

locale
string
optional

Location of application communicating to cardholder
sample value. en-IN

ip
string
optional

IP address of the device that accepted the consent
Sample Value: 157.35.79.240

deviceId
string
optional

Device ID of the device that accepted the consent
Sample Value :samsung-SM-A260G-01b9ec5dc11fc570

deviceName
string
optional

Device Name of the device that accepted the consent
Sample Value: SM-A260G\

Response Attributes

Content Type : JSON

Head

AttributeDescription
Version
string

Version of the API
Possible Value: v1

responseTimestamp
string

EPOCH timestamp of the time at which request is being received

Possible Value: 1588402269

requestId
string

Merchant’s Unique Request ID for card tokenization

Possible Value: Any

Body

AttributeDescription
mid
string

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

tokenIndexNumber
string

Unique Token Reference ID provided by Paytm Token Service

tokenStatus
string

The status of the token. Must be one of the four possible values.

INIT: Tokenization is not yet complete

ACTIVE: Card token is active and transactions can be processed with the same.

FAILED: Card tokenization failed by system or card network error

resultInfo
string

Status object

ResultInfo
+
AttributeDescription
resultCode
string

Response code for different failure reason

Possible Values: Any

resultStatus
string

Response status

Possible Values: S/F/U

resultMsg
string

Response message

Possible Values: Any

Response Codes & Messages

resultCoderesultStatusresultMsg
00SuccessSUCCESS
100PendingPENDING
150PENDINGSYSTEM_ERROR
400FAILEDBAD_REQUEST
401FAILEDFAILURE
406FAILEDInvalid request id
407FAILEDIncorrect mid
408FAILEDIncorrect User ID
409FAILEDIncorrect details passed
410FAILEDMandatory fields missing
412FAILEDDUPLICATE_REQUEST
420FAILEDCard Bin is not supported
730FAILEDError from card network
440FAILEDOperation not supported by network
442FAILEDUnable to found TRID
443FAILEDTRID is not in Active state
500FAILEDINTERNAL_SYSTEM_ERROR
502FAILEDSYSTEM_ERROR
1001FAILEDSignature Validation Failure
1002FAILEDCheckSum Validation Failure
1003FAILEDJwt Validation Failure
1004FAILEDMerchant Id is missing
1005FAILEDSignature type is missing
1006FAILEDHead is missing
1400FAILEDSignature Type is invalid
700FAILEDBad Request from card Network
701FAILEDFailure from card network
702FAILEDError from Network
708FAILEDError connecting with card network
709FAILEDError communicating with card network
711FAILEDInvalid card details
712FAILEDCard not eligible
713FAILEDCard not allowed
714FAILEDFurther operations for this card are not allowed
716FAILEDCARD_DECLINED
721FAILEDError with Network
723FAILEDError While connecting to card network
727FAILEDINVALID_AUTHREFNO
750FAILEDREQUIRE_ADDITIONAL_AUTHENTICATION
801PENDINGAwaiting response from the network
⇾
Staging
Production
https://securestage.paytmpayments.com/coft-center/coft/merchant/{mid}/tokenize?requestId={request-id}copy icon
REQUEST
RESPONSE
CURL
PHP
PYTHON
NODE
DOTNET
curl -X POST 'https://securestage.paytmpayments.com/coft-center/coft/merchant/{mid}/tokenize?requestId={request-id}
' \
--header 'Content-Type: application/json' \
--data '{"body":{"authRefId":"501123338","cardSource":"CARD_ON_FILE","encryptedCardData":"Encrypted cardData object","userInfo":{"custId":"CUST_001","firstName":"","lastName":"","mobileNumber":""},"tokenizationConsent":{"userConsent":1,"createdAtuser":"Jul 22, 2021 02:46:54 PM","userConsentId":"1234","language":"en","platform":"APP","os":"androidapp","appVersion":"9.10.2","locale":"en-IN","ip":"157.35.79.240","deviceId":"samsung-SM-A260G-01b9ec5dc11fc570","deviceName":"SM-A260G"}},"head":{"version":"v1","requestTimestamp":"1544614590000","requestId":"merchre000001","signature":"{signature}","signatureType":"signatureType","clientId":""}}'
copy icon