Create a payment token from a payment card

post https://cert.api.firstdata.com/gateway/v2/payment-tokens

Use this to create a payment token to safely store sensitive credit card information.

Body Params

PaymentCardPaymentTokenizationRequest

PaymentDevicePaymentTokenizationRequest

Headers

Content-Type

string

enum

required

Defaults to application/json

Content type.

Allowed:

Client-Request-Id

string

required

A client-generated ID for request tracking and signature creation, unique per request. This is also used for idempotency control. We recommend 128-bit UUID format.

Api-Key

string

required

Key given to merchant after boarding associating their requests with the appropriate app in Apigee.

Timestamp

int64

required

Epoch timestamp in milliseconds in the request from a client system. Used for Message Signature generation and time limit (5 mins).

Message-Signature

string

required

Used to ensure the request has not been tampered with during transmission. The Message-Signature is the Base64 encoded HMAC hash (SHA256 algorithm with the API Secret as the key.) For more information, refer to the supporting documentation on the Developer Portal.

Authorization

string

The access token previously generated with the access-tokens call. Use the format 'Bearer {access-token}'.

Responses

Response body

object

clientRequestId

string

Echoes back the value in the request header for tracking.

apiTraceId

string

Request identifier in API, can be used to request logs from the support team.

responseType

string

enum

The type of the response.

BadRequest Unauthenticated Unauthorized NotFound GatewayDeclined EndpointDeclined ServerError EndpointCommunicationError UnsupportedMediaType

requestStatus

string

enum

The status of the request.

DELETED FAILED SUCCESS APPROVED WAITING VALIDATION_FAILED DECLINED

requestTime

int64

Time of the request.

brand

string

Card brand.

country

string

Country of the card issued.

paymentToken

object

Use this model to create a payment token.

value

string

Client-supplied payment token value. Only applicable for DataVault tokenization scheme.

reusable

boolean

Defaults to true

If the token is reusable.

declineDuplicates

boolean

Defaults to false

Decline duplicate payment info if client token is supplied.

last4

string

The last 4 numbers of a payment card.

brand

string

Card brand, only for tokenization with payment.

accountVerification

boolean

If the account the token was created from has been verified.

type

string

Indicates the type of tokenization source.

error

object

Error information.

paymentCard

object

Payment card model.

number

string

required

Payment card number.

expiryDate

object

Required for normal transactions except for payment with 'RECURRING' flags.

securityCode

string

length between 3 and 4

Card verification value/number.

cardFunction

string

enum

Card function. This field is required when performing transactions for Brazil merchants.

CREDIT DEBIT PREPAID VOUCHER UNDEFINED

cardholderName

string

length ≤ 96

Name of the cardholder. Note - Only supported with request payload.

bin

string

The payment card BIN.

last4

string

The last 4 numbers of a payment card.

brand

string

Required only if using dual branded card.

networkToken

object

Network Token Model

value

string

required

Token value

expiryMonth

string

required

Month of the token expiration date in MM format.

expiryYear

string

required

Year of the card expiration date in YY format.

cardLast4

string

length ≤ 4

Last four digits of Card number.

brand

string

enum

Card brand.

AMEX DINERS/DISCOVER EFTPOS JCB MAESTRO MASTERCARD RUPAY VISA

cryptogram

string

Cryptogram value.

authIndicator

string

enum

Authorization Indicator.

P T

tokenEligible

string

Token Assurance Method Value determines the confidence level of the payment token to PAN/cardholder binding and it will be provided by the token service provider.

processor

object

Model for processor data.

referenceNumber

string

Reference transaction ID.

authorizationCode

string

Code returned to confirm transaction.

responseCode

string

Response code from endpoints.

network

string

Network used for transaction.

associationResponseCode

string

Raw response code from issuer.

responseMessage

string

Message returned from endpoints.

avsResponse

object

The processor address validation response for compliance.

cardholderInfoResponse

object

The processor Cardholder Info Response.

securityCodeResponse

string

enum

Code returned for CVV.

MATCHED NOT_MATCHED NOT_PROCESSED NOT_PRESENT NOT_CERTIFIED NOT_CHECKED

merchantAdviceCodeIndicator

string

Code to map merchant advice code to ISO specification.

responseIndicator

string

Indicates whether the transaction was routed through the payment card's own network or through a different network.

debitReceiptNumber

string

Receipt number from debit network provider.

transactionIntegrityClass

string

MasterCard provided Transaction Integrity Class for Point of Sale (POS) Purchase and Purchase with Cash Back transactions initiated on the Authorization Platform.

orderId

string

Note - Client Order ID if supplied by client. If not supplied by client, IPG will generate. The first 12 alphanumeric digits are passed down to Fiserv Enterprise reporting tool, Clientline and Data File Manager (DFM).

ipgTransactionId

string

length ≤ 14

The response transaction ID.

merchantTransactionId

string

length ≤ 40

The unique merchant transaction ID from the request header, if supplied.

additionalResponseData

object

Additional Response Data.

issuingBankName

string

length ≤ 18

Issuing Bank Name.

countryOfIssuance

string

length ≤ 3

Country of Issuance.

cardProductID

string

length ≤ 1

Card Product ID.

detailedProductID

string

length ≤ 3

Detailed Product ID.

associationResponseCodeAdtl

string

length ≤ 3

Association Response Code.

cardBrand

string

length ≤ 1

Card Brand.

deferredAuthTransactionID

string

length ≤ 16

Deferred Auth Transaction ID for re-authorized (Optimized) transaction

Response body

object

clientRequestId

string

Echoes back the value in the request header for tracking.

apiTraceId

string

Request identifier in API, can be used to request logs from the support team.

responseType

string

enum

The type of the response.

BadRequest Unauthenticated Unauthorized NotFound GatewayDeclined EndpointDeclined ServerError EndpointCommunicationError UnsupportedMediaType

requestStatus

string

enum

The status of the request.

DELETED FAILED SUCCESS APPROVED WAITING VALIDATION_FAILED DECLINED

requestTime

int64

Time of the request.

brand

string

Card brand.

country

string

Country of the card issued.

paymentToken

object

Use this model to create a payment token.

value

string

Client-supplied payment token value. Only applicable for DataVault tokenization scheme.

reusable

boolean

Defaults to true

If the token is reusable.

declineDuplicates

boolean

Defaults to false

Decline duplicate payment info if client token is supplied.

last4

string

The last 4 numbers of a payment card.

brand

string

Card brand, only for tokenization with payment.

accountVerification

boolean

If the account the token was created from has been verified.

type

string

Indicates the type of tokenization source.

error

object

Error information.

paymentCard

object

Payment card model.

number

string

required

Payment card number.

expiryDate

object

Required for normal transactions except for payment with 'RECURRING' flags.

securityCode

string

length between 3 and 4

Card verification value/number.

cardFunction

string

enum

Card function. This field is required when performing transactions for Brazil merchants.

CREDIT DEBIT PREPAID VOUCHER UNDEFINED

cardholderName

string

length ≤ 96

Name of the cardholder. Note - Only supported with request payload.

bin

string

The payment card BIN.

last4

string

The last 4 numbers of a payment card.

brand

string

Required only if using dual branded card.

networkToken

object

Network Token Model

value

string

required

Token value

expiryMonth

string

required

Month of the token expiration date in MM format.

expiryYear

string

required

Year of the card expiration date in YY format.

cardLast4

string

length ≤ 4

Last four digits of Card number.

brand

string

enum

Card brand.

AMEX DINERS/DISCOVER EFTPOS JCB MAESTRO MASTERCARD RUPAY VISA

cryptogram

string

Cryptogram value.

authIndicator

string

enum

Authorization Indicator.

P T

tokenEligible

string

Token Assurance Method Value determines the confidence level of the payment token to PAN/cardholder binding and it will be provided by the token service provider.

processor

object

Model for processor data.

referenceNumber

string

Reference transaction ID.

authorizationCode

string

Code returned to confirm transaction.

responseCode

string

Response code from endpoints.

network

string

Network used for transaction.

associationResponseCode

string

Raw response code from issuer.

responseMessage

string

Message returned from endpoints.

avsResponse

object

The processor address validation response for compliance.

cardholderInfoResponse

object

The processor Cardholder Info Response.

securityCodeResponse

string

enum

Code returned for CVV.

MATCHED NOT_MATCHED NOT_PROCESSED NOT_PRESENT NOT_CERTIFIED NOT_CHECKED

merchantAdviceCodeIndicator

string

Code to map merchant advice code to ISO specification.

responseIndicator

string

Indicates whether the transaction was routed through the payment card's own network or through a different network.

debitReceiptNumber

string

Receipt number from debit network provider.

transactionIntegrityClass

string

MasterCard provided Transaction Integrity Class for Point of Sale (POS) Purchase and Purchase with Cash Back transactions initiated on the Authorization Platform.

orderId

string

ipgTransactionId

string

length ≤ 14

The response transaction ID.

merchantTransactionId

string

length ≤ 40

The unique merchant transaction ID from the request header, if supplied.

additionalResponseData

object

Additional Response Data.

issuingBankName

string

length ≤ 18

Issuing Bank Name.

countryOfIssuance

string

length ≤ 3

Country of Issuance.

cardProductID

string

length ≤ 1

Card Product ID.

detailedProductID

string

length ≤ 3

Detailed Product ID.

associationResponseCodeAdtl

string

length ≤ 3

Association Response Code.

cardBrand

string

length ≤ 1

Card Brand.

deferredAuthTransactionID

string

length ≤ 16

Deferred Auth Transaction ID for re-authorized (Optimized) transaction

error

object

Error information.

code

string

Uniquely identifies an error condition. Client applications need to read and handle errors based on this.

message

string

A generic description of the error condition.

details

array of objects

Detailed information about message format errors.

details

object

field

string

The property or attribute associated with the error.

message

string

Information specific to a property or attribute.

declineReasonCode

string

Information about the decline reason.

Response body

object

clientRequestId

string

Echoes back the value in the request header for tracking.

apiTraceId

string

Request identifier in API, can be used to request logs from the support team.

responseType

string

enum

The type of the response.

BadRequest Unauthenticated Unauthorized NotFound GatewayDeclined EndpointDeclined ServerError EndpointCommunicationError UnsupportedMediaType

requestStatus

string

enum

The status of the request.

DELETED FAILED SUCCESS APPROVED WAITING VALIDATION_FAILED DECLINED

requestTime

int64

Time of the request.

brand

string

Card brand.

country

string

Country of the card issued.

paymentToken

object

Use this model to create a payment token.

value

string

Client-supplied payment token value. Only applicable for DataVault tokenization scheme.

reusable

boolean

Defaults to true

If the token is reusable.

declineDuplicates

boolean

Defaults to false

Decline duplicate payment info if client token is supplied.

last4

string

The last 4 numbers of a payment card.

brand

string

Card brand, only for tokenization with payment.

accountVerification

boolean

If the account the token was created from has been verified.

type

string

Indicates the type of tokenization source.

error

object

Error information.

paymentCard

object

Payment card model.

number

string

required

Payment card number.

expiryDate

object

Required for normal transactions except for payment with 'RECURRING' flags.

securityCode

string

length between 3 and 4

Card verification value/number.

cardFunction

string

enum

Card function. This field is required when performing transactions for Brazil merchants.

CREDIT DEBIT PREPAID VOUCHER UNDEFINED

cardholderName

string

length ≤ 96

Name of the cardholder. Note - Only supported with request payload.

bin

string

The payment card BIN.

last4

string

The last 4 numbers of a payment card.

brand

string

Required only if using dual branded card.

networkToken

object

Network Token Model

value

string

required

Token value

expiryMonth

string

required

Month of the token expiration date in MM format.

expiryYear

string

required

Year of the card expiration date in YY format.

cardLast4

string

length ≤ 4

Last four digits of Card number.

brand

string

enum

Card brand.

AMEX DINERS/DISCOVER EFTPOS JCB MAESTRO MASTERCARD RUPAY VISA

cryptogram

string

Cryptogram value.

authIndicator

string

enum

Authorization Indicator.

P T

tokenEligible

string

Token Assurance Method Value determines the confidence level of the payment token to PAN/cardholder binding and it will be provided by the token service provider.

processor

object

Model for processor data.

referenceNumber

string

Reference transaction ID.

authorizationCode

string

Code returned to confirm transaction.

responseCode

string

Response code from endpoints.

network

string

Network used for transaction.

associationResponseCode

string

Raw response code from issuer.

responseMessage

string

Message returned from endpoints.

avsResponse

object

The processor address validation response for compliance.

cardholderInfoResponse

object

The processor Cardholder Info Response.

securityCodeResponse

string

enum

Code returned for CVV.

MATCHED NOT_MATCHED NOT_PROCESSED NOT_PRESENT NOT_CERTIFIED NOT_CHECKED

merchantAdviceCodeIndicator

string

Code to map merchant advice code to ISO specification.

responseIndicator

string

Indicates whether the transaction was routed through the payment card's own network or through a different network.

debitReceiptNumber

string

Receipt number from debit network provider.

transactionIntegrityClass

string

MasterCard provided Transaction Integrity Class for Point of Sale (POS) Purchase and Purchase with Cash Back transactions initiated on the Authorization Platform.

orderId

string

ipgTransactionId

string

length ≤ 14

The response transaction ID.

merchantTransactionId

string

length ≤ 40

The unique merchant transaction ID from the request header, if supplied.

additionalResponseData

object

Additional Response Data.

issuingBankName

string

length ≤ 18

Issuing Bank Name.

countryOfIssuance

string

length ≤ 3

Country of Issuance.

cardProductID

string

length ≤ 1

Card Product ID.

detailedProductID

string

length ≤ 3

Detailed Product ID.

associationResponseCodeAdtl

string

length ≤ 3

Association Response Code.

cardBrand

string

length ≤ 1

Card Brand.

deferredAuthTransactionID

string

length ≤ 16

Deferred Auth Transaction ID for re-authorized (Optimized) transaction

error

object

Error information.

code

string

Uniquely identifies an error condition. Client applications need to read and handle errors based on this.

message

string

A generic description of the error condition.

details

array of objects

Detailed information about message format errors.

details

object

field

string

The property or attribute associated with the error.

message

string

Information specific to a property or attribute.

declineReasonCode

string

Information about the decline reason.

Language

Credentials

Header

URL


xxxxxxxxxx
20
1
curl --request POST \
2
     --url https://cert.api.firstdata.com/gateway/v2/payment-tokens \
3
     --header 'Content-Type: application/json' \
4
     --header 'accept: application/json' \
5
     --data '
6
{
7
  "createToken": {
8
    "reusable": true,
9
    "declineDuplicates": false
10
  },
11
  "accountVerification": false,
12
  "additionalDetails": {
13
    "receipts": [
14
      {
15
        "type": "cardholder"
16
      }
17
    ]
18
  }
19
}
20
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success response.

400The request cannot be validated.

401The request was unauthorized.

404The requested resource doesn't exist.

409The attempted action is not valid according to gateway rules. For example, when the gateway is too busy then the transaction is not processed.

422The processor declined the transaction.

500An unexpected internal server error occurred.