(c) PCI Pal 2020. The content on this page is subject to the Disclaimer Section (found on the Introduction page)
FirstData FirstAPI (Fiserv) Payment Gateway
This page details the inputs, secure inputs and outputs available for the FirstData FirstAPI Payment Gateway, how to complete each field, and an external link to the FirstData FirstAPI integration documentation.
PCI Pal must check any payment gateway integrations prior to going live. The documentation disclaimer (which applies throughout this guide) should be read before commencing any configuration of payment gateways.
Inputs
Input Fields
Required
Character Limits/
Required Input
Description
ApiKey
Y
n/a
Key given to merchant after boarding associating their requests with the appropriate app in Apigee.
ApiSecret
Y
n/a
Unique API Secret Key provided to the client by FirstData for a FirstAPI account
Region
N
n/a
Indicates the region where the client wants the transaction to be processed. This will override the default processing region identified for the client. Available options are argentina, brazil, germany, india and northamerica. Region specific store setup and APIGEE boarding is required in order to use an alternate region for processing.
clientRequestId
Y
128-bit UUID
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.
storeId
Y
20 char
An optional outlet ID for clients that support multiple stores in the same app.
merchantTransactionId
Y
40 char
The unique merchant transaction ID from the request header, if supplied.
total
Y
decimal
Sub component values must add up to total amount.
currency
Y
3 char
ISO 4217 currency code.
orderId
Y
100 an
Client Order ID if supplied by client.
billingName
N
96 char
Billing name.
billingCustomerId
N
32 char
Customer ID for billing purpose.
billingPhone
N
32 num
Primary phone number.
bilingMobilePhone
N
32 num
Mobile phone number.
billingEmail
N
254 char
Email address.
billingCompany
N
96 char
Company name associated with the address.
billingAddress1
N
96 char
First line of the street address.
billingAddress2
N
96 char
Second line of the street address.
billingCity
N
96 char
City or locality.
billingRegion
N
96 char
State or province.
billingPostalCode
N
24 char
ZIP code or postal code.
billingCountry
N
32 char
ISO-3166-1 ALPHA-2, ALPHA-3, numeric or full country name. In the case of PaySecure endpoints, pass the country code in an ISO format.
shippingName
N
96 char
Shipping name
shippingPhone
N
32 num
Primary phone number.
shippingMobilePhone
N
32 num
Mobile phone number.
shippingEmail
N
254 char
Email address.
shippingCompany
N
96 char
Company name associated with the address.
shippingAddress1
N
96 char
First line of the street address.
shippingAddress2
N
96 char
Second line of the street address.
shippingCity
N
96 char
City or locality.
ShippingRegion
N
96 char
State or province.
shippingPostalCode
N
24 char
ZIP code or postal code.
shippingCountry
N
32 char
ISO-3166-1 ALPHA-2, ALPHA-3, numeric or full country name. In the case of PaySecure endpoints, pass the country code in an ISO format.
comments
N
1024 an
Comments for the payment.
invoiceNumber
N
48 num
Invoice number.
purchaseOrderNumber
N
128 num
Purchase order number.
cardholderName
N
254 char
Card Holder Name
Secure Inputs
Input Fields
Required
Character Limits/
Required Input
Description
number
Yes
19 num
Secure input of the card number
expiryDate
Yes
2 num
Secure input of the card expiry - in the format MM
securityCode
Yes
3 or 4 num
Secure input of the card CVV, either three or four digits long depending on the card
Outputs
Output Fields
Description
country
Country of the card issuer.
orderIdOut
Client order ID if supplied by client, otherwise the order ID.
apiTraceId
Request identifier in API, can be used to request logs from the support team.
code
Response code for the transaction
merchantId
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.
terminalId
Terminal ID linked to the merchant account
streetMatch
Response if street matches that on file.
responseTypeOut
The type of the response.
message
A generic description of the error condition.
clientRequestId
Echoes back the value in the request header for tracking.
postalCodeMatch
Response if postal code matches that on file.
transactionTime
The transaction time in seconds since epoch.
transactionType
Type of transaction to perform. Primary transaction types in requests include 'SALE', 'PREAUTH', 'CREDIT' and 'FORCED_TICKET'.
ipgTransactionId
The response transaction ID.
transactionState
Shows the state of the current transaction.
type
Inidcates the type of tokenization source.
transactionStatus
Represents the status of a transaction immediately following the original processing request. This value is not stored for the transaction and is only available in the response when the transaction is processed. TransactionStatus is not returned on either the transaction inquiry or on the order inquiry.
brand
Required only if using dual branded card.
last4
The last 4 numbers of a payment card.
value
Client-supplied payment token value. Only applicable for DataVault tokenization scheme.
schemeTransactionId
The transaction ID received from schemes for the initial transaction of card on file flows.
totalOut
Sub component values must add up to total amount.
merchantTransactionIdOut
Transaction ID echoed back that is passed in the reques to the gateway
reusable
If the token is reusable.
responseCode
Response code from endpoints.
currencyOut
ISO 4217 currency code.
responseMessage
Message returned from endpoints.
comments
Comments passed in on the transaction, sent back on the response
authorizationCode
Code returned to confirm transaction.
declineDuplicates
Decline duplicate payment info if client token is supplied.
securityCodeResponse
Code returned for CVV.
invoiceNumberOut
invoice number associated with the payment echoed back from the gateway
accountVerification
If the account the token was created from has been verified.
