Generate a primary transaction

post https://cert.api.firstdata.com/gateway/v2/payments

Use this to originate a financial transaction like a sale, preauthorization, or credit.

Body Params

Accepted request types: PaymentCardSaleTransaction, PaymentCardPreAuthTransaction, PaymentCardPayerAuthTransaction, PaymentTokenCreditTransaction, PaymentTokenPreAuthTransaction, PaymentTokenSaleTransaction, PaypalCreditTransaction.

PaymentCardSaleTransaction

PaymentCardPreAuthTransaction

PaymentTokenCreditTransaction

PaymentTokenPreAuthTransaction

PaymentTokenSaleTransaction

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.

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

ipgTransactionId

string

The response transaction ID.

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).

transactionType

string

enum

Type of transaction to perform. Primary transaction types in requests include 'SALE', 'PREAUTH', 'CREDIT' and 'FORCED_TICKET'.

SALE PREAUTH CREDIT FORCED_TICKET VOID RETURN POSTAUTH PAYER_AUTH

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.

transactionOrigin

string

enum

The source of the transaction. The possible values are ECOM (if the order was received via email or Internet), MOTO (mail order, telephone order), MAIL, PHONE and RETAIL (face to face).

ECOM MOTO MAIL PHONE RETAIL

paymentMethodDetails

object

Provides details of the payment method used.

paymentCard

object

Payment card model.

paymentMethodType

string

enum

Type of payment method.

BCMC BITPAY BLIK BOLETO CASH CONEKTA CUP_DOMESTIC DEBITDE EMI EPS E-TRANSFER GIROPAY IDEAL INDIAWALLET KLARNA KPS MYBANK NATWEST_PAYIT NETBANKING PAYMENT_CARD PAYMENT_TOKEN PAYPAL PAYSAFECARD POLI POSTFINANCE_CARD POSTFINANCE_EF PRZELEWY24 SAMSUNG_PAY SAFETYPAY TRUSTLY TRUSTPAY WALLET WECHAT WECHAT_DOMESTIC

paymentMethodBrand

string

enum

A list of all Payment Method Brands.

AB_BANK_RMS ACB_RMS ADANCARD AFFIN_BANK_RMS AGRI_BANK_RMS AGRO_BANK_RMS WECHATPAY_SG_QFPAY GRABPAY_SG_QFPAY PAYNOW_SG_QFPAY ALLIANCE_BANK_RMS AMEX AM_ONLINE_RMS APAC_DIGITALPAYMENTS APLA ARGENCARD ASTROPAY_CARD ASTROPAY_DIRECT ATMVA_RMS AUTOMATICA AXIS AXS_KIOSK_RMS BACA_BANK_RMS BANAMEX BANCAT BANCODOBRASIL BANCOLOMBIA BANCOMER BANGKOK_BANK_RMS BANKTRANSFER BANK_ISLAM_RMS BANK_MUAMALAT_RMS BANK_OF_AYUDHYA_RMS BANK_RAKYAT_RMS BAOVIET_BANK_RMS BBPS BBVA_CUPON BCMC BENEFICIOS BIDV_RMS BITPAY BLIK BOLETO BOLETO_PAYMENT BOOST_RMS BRADESCO BTF_SOCIAL BUERGEL CABAL CABAL_ARGENTINA CABAL_C_L CABLEVISION CALDEN_AGR CALDEN_MC CARD CARDCRED CARDLESSEMI CARDRED CARTE_BANCAIRE CASH CENCOSUD_MAS CENTROCARD CETELEM CFSA CIMB_CLICKS_RMS CLARIN_365 CLIPER CLUB_DEL_ESTE CLUB_ESTE CLUB_LA_NACION CLUB_L_G COBROEXPRESS COMAHUE COMPRAS_NQN CONECS CONFIABLE CONSUMAX COOPEPLUS CREDENCIAL CREDICASH CREDIFE CREDIGUIA CREDIMAS CREDIMAZ CREDIQUEN CREDISI CREDI_AL CRED_MOVIL CTCILS_GC CUENTA_DNI CUP CUPON CUPONSTAR CUP_CHINAPNR C_REGALO DANSKEBANK DATA DATA2000 DEBITDE DEBITDE_EAPS DEBITDE_ELV DEBITDE_GIRO DINACARD DINERSCLUB DIRECTA DIREKT DONGA_BANK_RMS DPAY DRAGONPAY_RMS DUITNOW DUMBDUMMY EDENRED EFECTIVA_M EFECTY EFTPOS ELEBAR ELO EME ENETS_DBS_RMS ENETS_OCBC_RMS ENETS_SCB_RMS ENETS_UOB_RMS ENTERCASH EPS ESUN_ATM_RMS EXCL_CARD EXIM_BANK_RMS FALABELLA_CMR FAVACARD FIEL FINANYA FINLANDONLINEBANKING FPS FULLCARD GC_CENCOSUD GENIAL GIFT_CARD GIROPAY GLOBAL_BLUE GLOBAL_RED GP_BANK_RMS GRABPAY GRABPAY_RMS GROUPON GRUPAR GRUPARCTDO G_PASEOS HANDELSBANKEN HD_BANK_RMS HELM HIPERCARD HLB_CONNECT_RMS HOGARNET HSBC_BANK_RMS HUILEN IDEAL IKEA INDIAWALLET INSTANTTRANSFER INTERNATIONALPAYOUT IRED ISLA_CARD ITALCRED ITAU_BRAZIL ITAU_CHILE JCB JERARQUICOS KADICARD KASIKORN_PAYPLUS_RMS KLARNA KPS KRUNG_THAI_BANK_RMS KUWAIT_FINANACE_RMS LASER LA_RED LA_VOZ LA_ZONAL LIDER LOS_ANDES LVPB_BANK_RMS MAESTRO MAGENTA MARITIME_BANK_RMS MASTERCARD MASTERPASS MAT_VOUCHER MAXIULTRA MAYBANK_QRPAY_RMS MAYBANK_RMS MB_BANK_RMS MC_BANCOR MEBNA MENDOZA_PS MEXICOLOCAL MILENIA MIRA MI_RENAULT MOBILETOPUP MUDON MULTIBANCO MUSICRED MUTUAL_TAIS MYBANK NAMA_BANK_RMS NARANJA NATIVA NATIVA_MC NAVI_BANK_RMS NETBANKING NEVADA NEWRED NOA_EXPRESS NORDEA NSCARD OCBC_BANK_RMS OCEAN_BANK_RMS OHGIFTCARD OPENCARD OSUUSPANKKI OXXO OXXO_CASH PAGOFACIL PATAGONIA365 PAYBYBANK PAYLATER PAYNOW PAYNOW_RMS PAYPAL PAYSAFECARD PB_EBANK_RMS PERSONALPIN PG_BANK_RMS PHUONGDONG_RMS PIX_PAYMENT PLATINO PLAYP_CARD POLI PREMIER PRIMICIA PRISMA_VALE PROCAMPO PRZELEWY24 PUGGLEPAY PYME_NACION QIDA QIWI RAPICLUB RAPIPAGO RED_BENEF RED_IN RHB_NOW_RMS RIO_NEGRO RIPSA RUPAY SACOM_BANK_RMS SAFETYPAY SAIGON_BANK_RMS SAIGON_HANOI_RMS SAMSUNG_PAY SAM_KIOSK_RMS SANTANDER SANTANDER_CASH SAN_JUAN SAPUCAY SBPS_OTHER_PAYMENTS SEAA_BANK_RMS SERVFINANC SERVICLUB SHELL_LATAM SHOPEEPAY_RMS SIAM_COMMERCIAL_RMS SIDECREER SIMPANANNASIONAL_RMS SKRILL SOFORT SOMOS_RIVER SOROCRED SOYRECOLETA SOY_NORTE SOY_SOLAR SOY_TIGRE STAND_CHART_BANK_RMS SU_CREDITO TARJETA_SHOPPING TARJETA_SOL TARJ_LOCAL TARJ_PRIVAD TCI TC_GRUPO TECHCOM_BANK_RMS TELEINGRESO TERRICLUB TIENPHONG_BANK_RMS TITANIO TJ_VERDE TKT_NACION TNG_EWALLET_RMS TRUSTLY TRUSTPAY TUYA T_CENCOSUD T_CIUDADANA T_FARO ULTRA UNICA UNIRED UOB_BANK_RMS UPO_PAYMENT_RMS VIB_RMS VIETA_BANK_RMS VIETCOM_BANK_RMS VIETIN_BANK_RMS VIP VISA VOUCHER VOUCHER_TUR VP_BANK_RMS VYCARD WECHATPAY_QFPAY WECHATPAY_RMS WECHAT_CHINAPNR WECHAT_OCEAN ZIMPLER

country

string

Country of the card issuer.

terminalId

string

The terminal that is processing the transaction.

merchantId

string

length ≤ 30

The unique (on Acquirer level) mechant ID. Usually this value has been chosen from the merchant itself and will be used in communication with the endpoint.

merchantTransactionId

string

length ≤ 40

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

transactionTime

int64

The transaction time in seconds since epoch.

approvedAmount

object

Amount of the transaction.

total

number

required

≥ 0

Sub component values must add up to total amount.

currency

string

required

ISO 4217 currency code.

components

object

Transaction amounts with multiple components.

transactionAmount

object

Amount of the transaction.

total

number

≥ 0

Sub component values must add up to total amount.

currency

string

ISO 4217 currency code.

components

object

Transaction amounts with multiple components.

transactionStatus

string

enum

This field is Deprecated. Point to 'transactionResult'.

APPROVED WAITING PARTIAL VALIDATION_FAILED PROCESSING_FAILED DECLINED

transactionResult

string

enum

This is the result of the operation, unless transaction status that represent financial status of the transaction, this fields helps us to understand if the operation is successfully executed

APPROVED DECLINED FAILED WAITING PARTIAL FRAUD

approvalCode

string

Shows the transaction approvalcode.

errorMessage

string

Shows the transaction errorMessage.

transactionState

string

enum

Shows the state of the current transaction.

AUTHORIZED CAPTURED DECLINED CHECKED COMPLETED_GET INITIALIZED PENDING READY TEMPLATE SETTLED VOIDED WAITING

paymentAccountReferenceNumber

string

length ≤ 30

Payment Account Reference Number from response, if supplied.

secure3dResponse

object

Contains 3DSecure response code.

responseCode3dSecure

string

Code received after successful payer-auth verification.

cardholderInfo

string

length ≤ 128

The cardholder's information supplied by the ACS.

standinResponseDetails

object

Contains Standin response details.

secure3DEnrolmentStatus

string

Secure 3D Enrolment Status.

secure3DECI

string

Secure 3D ECI.

secure3DAuthenticationResponse

string

Secure 3D Authentication Response.

authenticationValue

string

Secure 3D Authentication Value.

xid

string

Secure 3D XID.

authenticationAlgorithm

string

Secure 3D Authentication Algorithm.

redirectURL

string

The endpoint redirection URL.

authenticationResponse

object

Encapsulates 3DS authentication details in transaction responses.

type

string

enum

The type of authentication.

3D_SECURE

version

string

enum

The version of 3DS used to authenticate.

2.1 2.2

params

object

Additional parameters for authentication redirect.

secure3dMethod

object

Encapsulates the 3DS method form and unique transaction identifier.

schemeTransactionId

string

length ≤ 40

The transaction ID received from schemes for the initial transaction of card on file flows.

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.

additionalDetails

object

Additional transaction details for transaction response.

comments

string

length ≤ 1024

Comment for the payment.

invoiceNumber

string

length ≤ 48

Invoice number.

purchaseOrderNumber

string

length ≤ 128

Purchase order number.

receipts

array of objects

length between 1 and 2

Provides receipt response data, if it has been requested.

receipts

object

type

string

enum

required

Defines the consumer of the receipt (e.g. cardholder, merchant).

cardholder merchant

data

array of objects

required

Array of formatted lines that represents the actual receipt data, that can be printed out.

data*

object

endOfLine

boolean

Defaults to true

Flag to indicate if the text ends at the end of this receipt line.

text

string

required

Text that represents a line of the actual receipt data, that can be printed out.

additionalResponseData

object

Additional Response Data.

accountUpdaterResponse

object

Details related to updated account information.

updatedCard

string

Account updater replacement PAN or TransArmor token.

updatedToken

string

Updated value of token.

updatedExpirationDate

string

New account number expiration date in MMYY format.

updatedAccountStatus

string

Status of the updated account. An account may have closed (ACCOUNT_CLOSED), the expiry date may have changed (EXPIRY_CHANGED), the account may have changed (ACCOUNT_CHANGED), or the cardholder should be contacted (CONTACT_CARDHOLDER).

updatedAccountErrorCode

string

Code for the error encountered when updating account.

originalResponseCode

string

Original Response Code for re-authorized (Optimized) transaction

currencyConversionResponse

object

Currency Conversion Response.

dccApplied

boolean

Dynamic Currency Conversion Applied.

exchangeRateDetails

object

Fields related to Currency Conversion Inquiry.

requiredActions

object

Provides details which actions need to be performed to fulfill requirements of integration data.

requiredConsumerData

array of objects

Consumer data details which need to be provided by the payer.

requiredConsumerData

object

hint

string

length ≤ 2048

Description of required data that need to be provided.

validationExpression

string

length ≤ 2048

Regexp validation expression for requested data.

key

string

length ≤ 2048

Key for required data item.

requiredIntegrationData

array of objects

Provides details for data requested from the application.

requiredIntegrationData

object

hint

string

length ≤ 2048

Description of required integration data that need to be provided.

key

string

length ≤ 2048

Key for required data item.

requiredRedirectionData

object

Redirection details provided to the payer e.g. an external URL to complete processing on the web page of the authorisation system.

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.

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

ipgTransactionId

string

The response transaction ID.

orderId

string

transactionType

string

enum

Type of transaction to perform. Primary transaction types in requests include 'SALE', 'PREAUTH', 'CREDIT' and 'FORCED_TICKET'.

SALE PREAUTH CREDIT FORCED_TICKET VOID RETURN POSTAUTH PAYER_AUTH

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.

transactionOrigin

string

enum

The source of the transaction. The possible values are ECOM (if the order was received via email or Internet), MOTO (mail order, telephone order), MAIL, PHONE and RETAIL (face to face).

ECOM MOTO MAIL PHONE RETAIL

paymentMethodDetails

object

Provides details of the payment method used.

paymentCard

object

Payment card model.

paymentMethodType

string

enum

Type of payment method.

paymentMethodBrand

string

enum

A list of all Payment Method Brands.

country

string

Country of the card issuer.

terminalId

string

The terminal that is processing the transaction.

merchantId

string

length ≤ 30

The unique (on Acquirer level) mechant ID. Usually this value has been chosen from the merchant itself and will be used in communication with the endpoint.

merchantTransactionId

string

length ≤ 40

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

transactionTime

int64

The transaction time in seconds since epoch.

approvedAmount

object

Amount of the transaction.

total

number

required

≥ 0

Sub component values must add up to total amount.

currency

string

required

ISO 4217 currency code.

components

object

Transaction amounts with multiple components.

transactionAmount

object

Amount of the transaction.

total

number

≥ 0

Sub component values must add up to total amount.

currency

string

ISO 4217 currency code.

components

object

Transaction amounts with multiple components.

transactionStatus

string

enum

This field is Deprecated. Point to 'transactionResult'.

APPROVED WAITING PARTIAL VALIDATION_FAILED PROCESSING_FAILED DECLINED

transactionResult

string

enum

This is the result of the operation, unless transaction status that represent financial status of the transaction, this fields helps us to understand if the operation is successfully executed

APPROVED DECLINED FAILED WAITING PARTIAL FRAUD

approvalCode

string

Shows the transaction approvalcode.

errorMessage

string

Shows the transaction errorMessage.

transactionState

string

enum

Shows the state of the current transaction.

AUTHORIZED CAPTURED DECLINED CHECKED COMPLETED_GET INITIALIZED PENDING READY TEMPLATE SETTLED VOIDED WAITING

paymentAccountReferenceNumber

string

length ≤ 30

Payment Account Reference Number from response, if supplied.

secure3dResponse

object

Contains 3DSecure response code.

responseCode3dSecure

string

Code received after successful payer-auth verification.

cardholderInfo

string

length ≤ 128

The cardholder's information supplied by the ACS.

standinResponseDetails

object

Contains Standin response details.

secure3DEnrolmentStatus

string

Secure 3D Enrolment Status.

secure3DECI

string

Secure 3D ECI.

secure3DAuthenticationResponse

string

Secure 3D Authentication Response.

authenticationValue

string

Secure 3D Authentication Value.

xid

string

Secure 3D XID.

authenticationAlgorithm

string

Secure 3D Authentication Algorithm.

redirectURL

string

The endpoint redirection URL.

authenticationResponse

object

Encapsulates 3DS authentication details in transaction responses.

type

string

enum

The type of authentication.

3D_SECURE

version

string

enum

The version of 3DS used to authenticate.

2.1 2.2

params

object

Additional parameters for authentication redirect.

secure3dMethod

object

Encapsulates the 3DS method form and unique transaction identifier.

schemeTransactionId

string

length ≤ 40

The transaction ID received from schemes for the initial transaction of card on file flows.

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.

additionalDetails

object

Additional transaction details for transaction response.

comments

string

length ≤ 1024

Comment for the payment.

invoiceNumber

string

length ≤ 48

Invoice number.

purchaseOrderNumber

string

length ≤ 128

Purchase order number.

receipts

array of objects

length between 1 and 2

Provides receipt response data, if it has been requested.

receipts

object

type

string

enum

required

Defines the consumer of the receipt (e.g. cardholder, merchant).

cardholder merchant

data

array of objects

required

Array of formatted lines that represents the actual receipt data, that can be printed out.

data*

object

endOfLine

boolean

Defaults to true

Flag to indicate if the text ends at the end of this receipt line.

text

string

required

Text that represents a line of the actual receipt data, that can be printed out.

additionalResponseData

object

Additional Response Data.

accountUpdaterResponse

object

Details related to updated account information.

updatedCard

string

Account updater replacement PAN or TransArmor token.

updatedToken

string

Updated value of token.

updatedExpirationDate

string

New account number expiration date in MMYY format.

updatedAccountStatus

string

updatedAccountErrorCode

string

Code for the error encountered when updating account.

originalResponseCode

string

Original Response Code for re-authorized (Optimized) transaction

currencyConversionResponse

object

Currency Conversion Response.

dccApplied

boolean

Dynamic Currency Conversion Applied.

exchangeRateDetails

object

Fields related to Currency Conversion Inquiry.

requiredActions

object

Provides details which actions need to be performed to fulfill requirements of integration data.

requiredConsumerData

array of objects

Consumer data details which need to be provided by the payer.

requiredConsumerData

object

hint

string

length ≤ 2048

Description of required data that need to be provided.

validationExpression

string

length ≤ 2048

Regexp validation expression for requested data.

key

string

length ≤ 2048

Key for required data item.

requiredIntegrationData

array of objects

Provides details for data requested from the application.

requiredIntegrationData

object

hint

string

length ≤ 2048

Description of required integration data that need to be provided.

key

string

length ≤ 2048

Key for required data item.

requiredRedirectionData

object

Redirection details provided to the payer e.g. an external URL to complete processing on the web page of the authorisation system.

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.

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

ipgTransactionId

string

The response transaction ID.

orderId

string

transactionType

string

enum

Type of transaction to perform. Primary transaction types in requests include 'SALE', 'PREAUTH', 'CREDIT' and 'FORCED_TICKET'.

SALE PREAUTH CREDIT FORCED_TICKET VOID RETURN POSTAUTH PAYER_AUTH

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.

transactionOrigin

string

enum

The source of the transaction. The possible values are ECOM (if the order was received via email or Internet), MOTO (mail order, telephone order), MAIL, PHONE and RETAIL (face to face).

ECOM MOTO MAIL PHONE RETAIL

paymentMethodDetails

object

Provides details of the payment method used.

paymentCard

object

Payment card model.

paymentMethodType

string

enum

Type of payment method.

paymentMethodBrand

string

enum

A list of all Payment Method Brands.

country

string

Country of the card issuer.

terminalId

string

The terminal that is processing the transaction.

merchantId

string

length ≤ 30

The unique (on Acquirer level) mechant ID. Usually this value has been chosen from the merchant itself and will be used in communication with the endpoint.

merchantTransactionId

string

length ≤ 40

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

transactionTime

int64

The transaction time in seconds since epoch.

approvedAmount

object

Amount of the transaction.

total

number

required

≥ 0

Sub component values must add up to total amount.

currency

string

required

ISO 4217 currency code.

components

object

Transaction amounts with multiple components.

transactionAmount

object

Amount of the transaction.

total

number

≥ 0

Sub component values must add up to total amount.

currency

string

ISO 4217 currency code.

components

object

Transaction amounts with multiple components.

transactionStatus

string

enum

This field is Deprecated. Point to 'transactionResult'.

APPROVED WAITING PARTIAL VALIDATION_FAILED PROCESSING_FAILED DECLINED

transactionResult

string

enum

This is the result of the operation, unless transaction status that represent financial status of the transaction, this fields helps us to understand if the operation is successfully executed

APPROVED DECLINED FAILED WAITING PARTIAL FRAUD

approvalCode

string

Shows the transaction approvalcode.

errorMessage

string

Shows the transaction errorMessage.

transactionState

string

enum

Shows the state of the current transaction.

AUTHORIZED CAPTURED DECLINED CHECKED COMPLETED_GET INITIALIZED PENDING READY TEMPLATE SETTLED VOIDED WAITING

paymentAccountReferenceNumber

string

length ≤ 30

Payment Account Reference Number from response, if supplied.

secure3dResponse

object

Contains 3DSecure response code.

responseCode3dSecure

string

Code received after successful payer-auth verification.

cardholderInfo

string

length ≤ 128

The cardholder's information supplied by the ACS.

standinResponseDetails

object

Contains Standin response details.

secure3DEnrolmentStatus

string

Secure 3D Enrolment Status.

secure3DECI

string

Secure 3D ECI.

secure3DAuthenticationResponse

string

Secure 3D Authentication Response.

authenticationValue

string

Secure 3D Authentication Value.

xid

string

Secure 3D XID.

authenticationAlgorithm

string

Secure 3D Authentication Algorithm.

redirectURL

string

The endpoint redirection URL.

authenticationResponse

object

Encapsulates 3DS authentication details in transaction responses.

type

string

enum

The type of authentication.

3D_SECURE

version

string

enum

The version of 3DS used to authenticate.

2.1 2.2

params

object

Additional parameters for authentication redirect.

secure3dMethod

object

Encapsulates the 3DS method form and unique transaction identifier.

schemeTransactionId

string

length ≤ 40

The transaction ID received from schemes for the initial transaction of card on file flows.

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.

additionalDetails

object

Additional transaction details for transaction response.

comments

string

length ≤ 1024

Comment for the payment.

invoiceNumber

string

length ≤ 48

Invoice number.

purchaseOrderNumber

string

length ≤ 128

Purchase order number.

receipts

array of objects

length between 1 and 2

Provides receipt response data, if it has been requested.

receipts

object

type

string

enum

required

Defines the consumer of the receipt (e.g. cardholder, merchant).

cardholder merchant

data

array of objects

required

Array of formatted lines that represents the actual receipt data, that can be printed out.

data*

object

endOfLine

boolean

Defaults to true

Flag to indicate if the text ends at the end of this receipt line.

text

string

required

Text that represents a line of the actual receipt data, that can be printed out.

additionalResponseData

object

Additional Response Data.

accountUpdaterResponse

object

Details related to updated account information.

updatedCard

string

Account updater replacement PAN or TransArmor token.

updatedToken

string

Updated value of token.

updatedExpirationDate

string

New account number expiration date in MMYY format.

updatedAccountStatus

string

updatedAccountErrorCode

string

Code for the error encountered when updating account.

originalResponseCode

string

Original Response Code for re-authorized (Optimized) transaction

currencyConversionResponse

object

Currency Conversion Response.

dccApplied

boolean

Dynamic Currency Conversion Applied.

exchangeRateDetails

object

Fields related to Currency Conversion Inquiry.

requiredActions

object

Provides details which actions need to be performed to fulfill requirements of integration data.

requiredConsumerData

array of objects

Consumer data details which need to be provided by the payer.

requiredConsumerData

object

hint

string

length ≤ 2048

Description of required data that need to be provided.

validationExpression

string

length ≤ 2048

Regexp validation expression for requested data.

key

string

length ≤ 2048

Key for required data item.

requiredIntegrationData

array of objects

Provides details for data requested from the application.

requiredIntegrationData

object

hint

string

length ≤ 2048

Description of required integration data that need to be provided.

key

string

length ≤ 2048

Key for required data item.

requiredRedirectionData

object

Redirection details provided to the payer e.g. an external URL to complete processing on the web page of the authorisation system.

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.

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
17
1
curl --request POST \
2
     --url https://cert.api.firstdata.com/gateway/v2/payments \
3
     --header 'Content-Type: application/json' \
4
     --header 'accept: application/json' \
5
     --data '
6
{
7
  "paymentMethod": {
8
    "paymentFacilitator": {
9
      "subMerchantData": {
10
        "document": {
11
          "type": "NATIONAL_IDENTITY"
12
        }
13
      }
14
    }
15
  }
16
}
17
'

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 cannot be authenticated or was submitted with the wrong credentials.

403The request was unauthorized.

404The requested resource doesn't exist.

409The attempted action is not valid according to gateway rules. For example, the merchant is not set-up or the order already exists.

415Format that is not supported by the server for the HTTP method.

422The processor declined the transaction.

500An unexpected internal server error occurred.

502There was a problem communicating with the endpoint.