Skip to main content

First Data IPG

Overview​

Gateway Website: https://docs.firstdata.com/org/gateway
Developer Documentation: https://developer.fiserv.com/product/IPGNA/api/?type=post&path=/payments&branch=main&version=1.0.0
Default Currency: USD

Reqest Objects: BillingAddress, ShippingAddress, CreditCard, OrderInfo,SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
This implementation of First Data IPG forwards requests to the below endpoints.
Production: prod.api.firstdata.com/gateway/v2
Sandbox: cert.api.firstdata.com/gateway/v2

Supported Parameters​

* denotes a required field
Field NameTypeIPG MappingNotes
gateway*stringN/AFirstDataIPG
PublicKey*stringApi-Key (header)Key given to merchant after boarding associating their requests with the appropriate app in Apigee.
PrivateKey*stringMessage-Signature (header)Used in creation of message signature hash header.
ProcessingRegionstringRegion (header)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.
StoreIdstringStoreIdOutlet ID for clients that support multiple stores in the same app.
CurrencyCodestringTransactionAmount.​CurrencyISO 4217 three-letter alphabetic code for the currency.
Defaults to "USD".
AmountintTransactionAmount.​TotalTransaction amount in whole units. Example: $10.00 USD should be sent as 1000.
CreditCard.​BrandstringPaymentMethod.​PaymentCard.​BrandRequired only if using dual branded card.
CreditCard.​NumberstringPaymentMethod.​PaymentCard.​NumberCard's PAN or TokenEx token
CreditCard.​ExpMonthintPaymentMethod.​PaymentCard.​ExpiryDate.​Month1 or 2 digit month.
CreditCard.​ExpYearintPaymentMethod.​PaymentCard.​ExpiryDate.​Year4 digit year.
CreditCard.​FullNamestringPaymentMethod.​PaymentCard.​CardholderNameCardholder's full name.
CreditCard.​CVVstringPaymentMethod.​PaymentCard.​SecurityCode3 or 4 digit Card Verification Code. If the CVV has been associated with a TokenEx token, send a non-numeric value here, such as "cvv". The CVV associated with the token will be retrieved and forwarded.
CreditCard.​BinstringPaymentMethod.​PaymentCard.​BinThe payment card BIN.
N/AstringPaymentMethod.​PaymentCard.​Last4When the card's Bin is sent, this field is auto-populated with the last four digits of the card number.
BillingAddress.​PhonestringOrder.​Billing.​Contact.​PhonePrimary phone number.
BillingAddress.​FaxstringOrder.​Billing.​Contact.​FaxFax number.
BillingAddress.​EmailstringOrder.​Billing.​Contact.​EmailEmail address.
BillingAddress.​FirstNamestringOrder.​Billing.​FirstNameBilling first name. Note - Only supported for AMEX.
BillingAddress.​LastNamestringOrder.​Billing.​LastNameBilling last name. Note - Only supported for AMEX.
BillingAddress.​FullNamestringOrder.​Billing.​NameBilling name.
BillingAddress.​CompanystringOrder.​Billing.​Address.​CompanyCompany name associated with the address.
BillingAddress.​Address1stringOrder.​Billing.​Address.​Address1First line of the street address.
BillingAddress.​Address2stringOrder.​Billing.​Address.​Address2Second line of the street address.
BillingAddress.​CitystringOrder.​Billing.​Address.​CityCity or locality.
BillingAddress.​StatestringOrder.​Billing.​Address.​RegionState or province.
BillingAddress.​ZipstringOrder.​Billing.​Address.​PostalCodeZIP code or postal code.
BillingAddress.​CountrystringOrder.​Billing.​Address.​CountryCustomer country. Input Alpha 3
OrderInfo.​CustomerIdstringOrder.​Billing.​CustomerIdCustomer ID for billing purpose.
OrderInfo.​PurchaseOrderNumberstringOrder.​AdditionalDetails.​PurchaseOrderNumberPurchase order number.
OrderInfo.​InvoiceNumberstringOrder.​AdditionalDetails.​InvoiceNumberInvoice number.
StoredCredentials.​InitiatorstringStoredCredentials.​IntitiatorValid values: "cardholder" or "merchant". These values are made upper case and then forwarded.
StoredCredentials.​CredentialStoredbooleanStoredCredentials.​SequenceSee usage in The Basics - Stored Credentials. . True = "SUBSEQUENT", False = "FIRST"
StoredCredentials.​PreviousNetworkTransactionIdstringStoredCredentials.​ReferencedSchemeTransactionIdSee usage in The Basics - Stored Credentials.
Matches IPG response field "ipgTransactionId".
StoredCredentials.​TransactionTypestringStoredCredentials.​ScheduledValid value mappings:
"recurring" = true
"installment" = true
"unscheduled" = false
any other string value = false
OrderInfo.​OrderIdstringOrder.​OrderIdClient 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).
MerchantTransactionIdstringMerchantTransactionIdA unique value per request. This field is utilized in both the body and in the generation of the message-signature header. If not supplied, a GUID is auto-generated and returned in the response.
ShippingAddress.​PhonestringOrder.​Shipping.​Contact.​PhonePrimary phone number.
ShippingAddress.​FaxstringOrder.​Shipping.​Contact.​FaxFax number.
ShippingAddress.​EmailstringOrder.​Shipping.​Contact.​EmailEmail address.
ShippingAddress.​FullNamestringOrder.​Shipping.​NameName of customer for shipping.
ShippingAddress.​CompanystringOrder.​Shipping.​Address.​CompanyCompany name associated with the address.
ShippingAddress.​Address1stringOrder.​Shipping.​Address.​Address1First line of the street address.
ShippingAddress.​Address2stringOrder.​Shipping.​Address.​Address2Second line of the street address.
ShippingAddress.​CitystringOrder.​Shipping.​Address.​CityCity or locality.
ShippingAddress.​StatestringOrder.​Shipping.​Address.​RegionState or province.
ShippingAddress.​ZipstringOrder.​Shipping.​Address.​PostalCodeZIP code or postal code.
ShippingAddress.​CountrystringOrder.​Shipping.​Address.​CountryCustomer country. Input Alpha 3
SoftDescriptors.​MerchantNamestringOrder.​SoftDescriptor.​DynamicMerchantNameStore "doing-business-as" name.
SoftDescriptors.​MerchantCategoryCodestringOrder.​SoftDescriptor.​MccThe 4-digit merchant category code (MCC). The merchant might be associated with multiple MCCs. In that case the MCC provided here will be the one that better describes the current transaction.
SoftDescriptors.​MerchantPhonestringOrder.​SoftDescriptor.​CustomerServiceNumberCustomer service phone number information that is passed to the issuer (it may appear on the cardholder’s statement) or if merchant wants to pass information that differs from the information stored on our master File.
SoftDescriptors.​MerchantCitystringOrder.​SoftDescriptor.​DynamicAddress.​CityCity or locality. Can also be sent in SoftDescriptors.MerchantAddress.City.
SoftDescriptors.​MerchantAddress.​CompanystringOrder.​SoftDescriptor.​DynamicAddress.​CompanyCompany name associated with the address.
SoftDescriptors.​MerchantAddress.​Address1stringOrder.​SoftDescriptor.​DynamicAddress.​Address1First line of the street address.
SoftDescriptors.​MerchantAddress.​Address2stringOrder.​SoftDescriptor.​DynamicAddress.​Address2Second line of the street address.
SoftDescriptors.​MerchantAddress.​CitystringOrder.​SoftDescriptor.​DynamicAddress.​CitySee SoftDescriptors.MerchantAddress.City.
SoftDescriptors.​MerchantAddress.​StatestringOrder.​SoftDescriptor.​DynamicAddress.​RegionState or province.
SoftDescriptors.​MerchantAddress.​ZipstringOrder.​SoftDescriptor.​DynamicAddress.​PostalCodeZIP code or postal code.
SoftDescriptors.​MerchantAddress.​CountrystringOrder.​SoftDescriptor.​DynamicAddress.​CountryCustomer country. Input Alpha 3
ThreeDSecure.​CAVVstringAuthenticationResult.​CavvThe Cardholder Authentication Verification Value (CAVV) is a cryptographic value derived by the issuer during payment authentication that can provide evidence of the results of payment authentication during an online purchase.
ThreeDSecure.​DSTransIdstringAuthenticationResult.​DsTransactionIdThe response transaction UUID from the DS (directory server)
ThreeDSecure.​AuthenticationResponsestringAuthenticationResult.​AuthenticationResponseThe result of authentication attempt returned by the 3D Secure authentication process (ARes).
ThreeDSecure.​ChallengeResponsestringAuthenticationResult.​TransactionStatusThe transaction status as returned by the 3D Secure authentication process (CRes).

Example Requests​

{
  "gateway": "FirstDataIPG",
  "testMode": true,
  "publicKey": "<Your IPG Public Key>",
  "privateKey": "<Your IPG Private Key>",
  "storeId": "<Your IPG Store Id, if applicable>",
  "amount": 1000,
  "currencyCode": "USD",
  "shippingAddress": {
    "phone": "444-444-4444",
    "fax": "444-444-6666",
    "email": "[email protected]",
    "fullName": "Jane Doe",
    "company": "Test Co.",
    "address1": "456 Someplace Drive",
    "address2": "Some Place",
    "city": "Tulsa",
    "state": "OK",
    "zip": "74112",
    "country": "USA"
  },
  "creditCard": {
    "bin": "411111",
    "brand": "Visa",
    "number": "4111111111111111",
    "expMonth": 6,
    "expYear": 2026,
    "fullName": "John Doe",
    "cvv": "123"
  },
  "billingAddress": {
    "phone": "555-555-5555",
    "fax": "555-555-6666",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "company": "Test Co.",
    "address1": "123 Someplace Lane",
    "address2": "Some Place",
    "city": "Tulsa",
    "state": "OK",
    "zip": "74111",
    "country": "USA"
  },
  "orderInfo": {
    "invoiceNumber": "A456789A",
    "customerId": "9876543210"
  },
  "threeDSecure": {
    "authenticationResponse": "Y",
    "cavv": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "dsTransId": "5a56fdc9-6d47-5fee-8000-000000296743"
  },
  "storedCredentials": {
    "initiator": "merchant",
    "credentialStored": true,
    "previousNetworkTransactionId": "84558721076",
    "transactionType": "recurring"
  },
  "softDescriptors": {
    "merchantAddress": {
      "company": "Jay's Widgets",
      "address1": "123 W. Brie Street",
      "address2": "#3",
      "city": "Denver",
      "state": "CO",
      "zip": "00001",
      "country": "USA"
    },
    "merchantCategoryCode": "0001",
    "merchantPhone": "9180000000",
    "merchantCity": "Denver",
    "merchantName": "Jay's Widgets, LLC"
  }
}

Gateway Response Parameters​

Field NameTypeIPG Response MappingNotes
ApprovalCodestringApprovalCodeTransaction approval code.
ApprovedbooleanTransactionStatusIf TransactionStatus equals "APPROVED" or "PARTIAL", this field is true.
ProviderTransactionCodestringIpgTransactionIdThe response transaction ID.
NetworkTransactionIdstringSchemeTransactionIdThe transaction ID received from schemes for the initial transaction of card on file flows.
GatewayTokenstringPaymentToken.ValueClient-supplied payment token value. Only applicable for DataVault tokenization scheme.
MerchantReferenceIdstringOrderIdClient Order ID if supplied by client. If not supplied by client, IPG will generate.
VerificationResult.CvvRawstringProcessor.SecurityCodeResponseCVV match value returned by issuer
VerificationResult.AvsRawstringProcessor.AvsResponse.AssociationAvsResponseAVS matching value returned by issuer
VerificationResult.ProviderParsed.StreetMatchstringProcessor.AvsResponse.StreetMatchAVS Street match, as parsed by First Data IPG
VerificationResult.ProviderParsed.PostalCodeMatchstringProcessor.AvsResponse.PostalCodeMatchPostal Code match, as parsed by First Data IPG

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "{\"clientRequestId\":\"7b21b860-643c-4e6d-bd4d-1f5011d1ec85\",\"apiTraceId\":\"ZXH2IXDbEVHj4RmYjrsBuQAAA2Y\",\"ipgTransactionId\":\"84643453089\",\"orderId\":\"R-337f7da4-e0eb-4e8b-95ae-f008a6ea720a\",\"transactionType\":\"PREAUTH\",\"paymentToken\":{\"reusable\":true,\"declineDuplicates\":false,\"brand\":\"VISA\",\"type\":\"PAYMENT_CARD\"},\"transactionOrigin\":\"ECOM\",\"paymentMethodDetails\":{\"paymentCard\":{\"expiryDate\":{\"month\":\"12\",\"year\":\"2000\"},\"bin\":\"411111\",\"last4\":\"1111\",\"brand\":\"VISA\"},\"paymentMethodType\":\"PAYMENT_CARD\",\"paymentMethodBrand\":\"VISA\"},\"terminalId\":\"1567065\",\"merchantId\":\"323254102995\",\"transactionTime\":1701967393,\"approvedAmount\":{\"total\":10.00,\"currency\":\"USD\",\"components\":{\"subtotal\":10.00}},\"transactionAmount\":{\"total\":10.00,\"currency\":\"USD\",\"components\":{\"subtotal\":10.00}},\"transactionStatus\":\"APPROVED\",\"approvalCode\":\"Y:OK7807:4643453089:YYYX:685976\",\"schemeTransactionId\":\"013341105228347\",\"processor\":{\"referenceNumber\":\"84643453089\",\"authorizationCode\":\"OK7807\",\"responseCode\":\"00\",\"network\":\"VISA\",\"associationResponseCode\":\"000\",\"responseMessage\":\"APPROVAL\",\"avsResponse\":{\"streetMatch\":\"Y\",\"postalCodeMatch\":\"Y\",\"associationAvsResponse\":\"Y\"},\"securityCodeResponse\":\"NOT_CHECKED\"},\"additionalDetails\":{\"additionalResponseData\":{\"cardProductID\":\"?\",\"detailedProductID\":\"H\",\"associationResponseCodeAdtl\":\"00\",\"cardBrand\":\"V\"}}}",
    "gatewayErrors": [],
    "tokenExTransactionCode": "ODQ2NDM0NTMwODk7MDtVU0Q7MTAwMA==",
    "approvalCode": "Y:OK7807:4643453089:YYYX:685976",
    "providerTransactionCode": "84643453089",
    "approved": true,
    "verificationResult": {
      "avsRaw": "Y",
      "cvvRaw": "NOT_CHECKED",
      "providerParsed": {
        "streetMatch": "Y",
        "postalCodeMatch": "Y"
      }
    },
    "networkTransactionId": "013341105228347",
    "merchantReferenceId": "R-337f7da4-e0eb-4e8b-95ae-f008a6ea720a"
  },
  "referenceNumber": "23120710431273630926",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on