IPG Gateway Guide

IPG fact sheet

Quick Start

New to integrating IPG with Spreedly? Here's your setup guide:

Retrieve your IPG credentials
1. Log into your IPG merchant dashboard.
2. Open the API Soap section.
3. Copy the User string. Send the full value as Spreedly user_id (for example WS00000000000..1).
4. Copy the Password. This maps to Spreedly password.
5. Copy the Certificate password. This maps to Spreedly pem_password.
6. Download the certificate and private key. Concatenate them into a single pem value. One way to do that is:
```
awk -v ORS='\
' '1' {private_key_file_name}.key {public_certificate_file_name}.pem
```
  Copy the output into pem. Do not include trailing whitespace or % characters.
7. If you have a single store, copy Store ID and pass it when you create the gateway. Aggregators or merchants with multiple stores should pass store_id per transaction as a gateway specific field instead.
Get familiar with the Spreedly API
1. Review Spreedly API basics
2. Understand the core concepts: Gateways, Payment Methods, and Transactions
Add IPG gateway to Spreedly in sandbox mode

Additional notes
IPG in Spreedly is the SOAP API integration (`gateway_typeipg`). Production endpoint: https://www5.ipg-online.com/ipgapi/services. Test endpoint: https://test.ipg-online.com/ipgapi/services.
Onboarding region is South America (Argentina). Default currency is ARS. Supported card brands: Visa, Mastercard, American Express, and Discover. Payment methods on this gateway: `credit_card` and `third_party_token`.
`store_id` is required on every transaction. Use the gateway setting, or override it with the `store_id` gateway specific field. If both are missing, IPG returns an unauthorized response.
Verify performs an authorize of `100` (minor units) followed by a void. Currency defaults to `ARS` when omitted.
Store vaults the card at IPG and returns a Spreedly `third_party_token`. Pass optional `hosted_data_id` on `store`; otherwise IPG/Spreedly generate one. `Remove` / `redact` with `remove_from_gateway` unstores that hosted data id.
Partial capture and partial refund are supported.
General credit (unreferenced credit) is supported.
Inquire is supported by `gateway_transaction_id` (`IpgTransactionId`) and by `order_id`.
Stored credentials map to `IPGrecurringType FIRST` or `REPEAT`. `SchemeTransactionId` is returned as Spreedly `response.network_transaction_id`.
Third-party 3DS2 MPI is supported on purchase and authorize. Gateway-owned 3DS2 is not supported.
Network tokenization is supported. Spreedly sends the cryptogram as `IPGTokenCryptogram` and maps brand (`VISA`, `MASTERCARD`, `AMEX`, DISCOVER).
LATAMQR wallet reporting uses `wallet_id`, `wallet_transaction_id`, and `wallet_transaction_type` (`IPGWalletType` is always `LATAM_QR_WALLET`). These fields are not Apple Pay or Google Pay.

Adding an IPG Gateway

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. Visit your Connections area to review all gateways and add new ones. When creating your gateways, select IPG before completing the required fields. Select Sandbox to create a gateway in Sandbox mode.

Required Credentials

user_id: Full IPG User string from the API Soap section (for example WS00000000000..1)
password: IPG API password
pem: Concatenated certificate and private key
pem_password: Certificate password

Optional Gateway Settings

store_id: Default IPG store id. Required if you do not pass store_id as a gateway specific field on each transaction.

REQUEST

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>ipg</gateway_type>
        <user_id>Your User Id</user_id>
        <password>Your Password</password>
        <pem>Your Pem Certificate with Private Key</pem>
        <pem_password>Your Pem Password</pem_password>
        <store_id>Your Store Id</store_id>
      </gateway>'

RESPONSE

<gateway>
  <token>ZOsUb8WXgy1N6WCPkaSZEvnxyz</token>
  <gateway_type>ipg</gateway_type>
  <name>IPG</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <store_id>Your Store Id</store_id>
  <user_id>Your User Id</user_id>
  <pem_password>Your Pem Password</pem_password>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_partial_capture type="boolean">true</supports_partial_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_partial_credit type="boolean">true</supports_partial_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_inquire_by_gateway_transaction_id type="boolean">true</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">true</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
    <credential>
      <name>store_id</name>
      <value>Your Store Id</value>
    </credential>
    <credential>
      <name>user_id</name>
      <value>Your User Id</value>
    </credential>
    <credential>
      <name>pem_password</name>
      <value>Your Pem Password</value>
    </credential>
  </credentials>
  <gateway_settings>
    <store_id>Your Store Id</store_id>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>hosted_data_id</gateway_specific_field>
    <gateway_specific_field>number_of_installments</gateway_specific_field>
    <gateway_specific_field>submerchant</gateway_specific_field>
    <gateway_specific_field>recurring_type</gateway_specific_field>
    <gateway_specific_field>store_id</gateway_specific_field>
    <gateway_specific_field>wallet_id</gateway_specific_field>
    <gateway_specific_field>wallet_transaction_id</gateway_specific_field>
    <gateway_specific_field>wallet_transaction_type</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
</gateway>

Purchase

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 500,
    "currency_code": "ARS",
    "retain_on_success": true
  }
}'

Authorize, capture, void, credit, verify, store, general credit, and inquire use the standard Spreedly transaction endpoints. Capture and credit accept a lower amount for partial capture and partial refund.

Gateway Specific Fields

<gateway_specific_fields>
  <ipg>
    <number_of_installments>4</number_of_installments>
    <hosted_data_id>123456abc</hosted_data_id>
    <recurring_type>FIRST</recurring_type>
    <store_id>1234</store_id>
    <submerchant>
      <mcc>6513</mcc>
      <legal_name>KINDERLAND</legal_name>
      <address>
        <address1>ALVARADO 494</address1>
        <address2>Street 2</address2>
        <zip>1704</zip>
        <city>BUENOS AIRES</city>
        <state>BUENOS AIRES</state>
        <country>ARG</country>
      </address>
      <document>
        <type>SINGLE_CODE_OF_LABOR_IDENTIFICATION</type>
        <number>30710655479</number>
      </document>
      <merchant_id>12345678</merchant_id>
    </submerchant>
    <wallet_id>wallet_123</wallet_id>
    <wallet_transaction_id>abcd12345</wallet_transaction_id>
    <wallet_transaction_type>DYNAMIC_QR_CARD_PAYMENT</wallet_transaction_type>
  </ipg>
</gateway_specific_fields>

hosted_data_id is passed on store and should be unique per cardholder. If omitted, the gateway returns a unique hosted data id to use for later vaulted purchases.
recurring_type overrides Spreedly stored-credential mapping. Use IPG values FIRST or REPEAT. See IPG’s API integration guide.
store_id overrides the gateway setting for that transaction.
wallet_id, wallet_transaction_id, and wallet_transaction_type report LATAMQR wallet origin on authorize, purchase, and (for wallet_transaction_id) refund. They are not used for Apple Pay or Google Pay

Field Name	Type	Required	Use Case (Description)	Example Value
hosted_data_id	String	No	Unique vault id on `store`. If omitted, IPG/Spreedly generate one for later `third_party_token` purchases.	123456abc
number_of_installments	Integer	No	Number of installments sent as IPG `numberOfInstallments`.	4
recurring_type	String	No	Override stored-credential `recurringType`. Accepted values: `FIRST`, `REPEAT`.	FIRST
store_id	String	Yes (if not on gateway)	Per-transaction IPG store id. Overrides the gateway setting.	1234
submerchant	Object	No	PFAC / sub-merchant data: `mcc`, `legal_name`, nested `address`, nested `document`, `merchant_id`.	See XML example
wallet_id	String	No	LATAM QR wallet identifier. Max 11 characters. Sent as `WalletID` with `WalletType=LATAM_QR_WALLET`.	wallet_123
wallet_transaction_id	String	No	LATAM QR wallet transaction id. Max 26 characters. Also accepted on refund.	abcd12345
wallet_transaction_type	String	No	QR type. Accepted values: `STATIC_QR_CARD_PAYMENT`, `DYNAMIC_QR_CARD_PAYMENT`.	DYNAMIC_QR_CARD_PAYMENT

REQUEST

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIxyz</payment_method_token>
        <amount>500</amount>
        <currency_code>ARS</currency_code>
        <gateway_specific_fields>
          <ipg>
            <number_of_installments>4</number_of_installments>
            <hosted_data_id>123456abc</hosted_data_id>
            <recurring_type>FIRST</recurring_type>
            <store_id>1234</store_id>
            <submerchant>
              <mcc>6513</mcc>
              <legal_name>KINDERLAND</legal_name>
              <address>
                <address1>ALVARADO 494</address1>
                <address2>Street 2</address2>
                <zip>1704</zip>
                <city>BUENOS AIRES</city>
                <state>BUENOS AIRES</state>
                <country>ARG</country>
              </address>
              <document>
                <type>SINGLE_CODE_OF_LABOR_IDENTIFICATION</type>
                <number>30710655479</number>
              </document>
              <merchant_id>12345678</merchant_id>
            </submerchant>
            <wallet_id>wallet_123</wallet_id>
            <wallet_transaction_id>abcd12345</wallet_transaction_id>
            <wallet_transaction_type>DYNAMIC_QR_CARD_PAYMENT</wallet_transaction_type>
          </ipg>
        </gateway_specific_fields>
      </transaction>'

Gateway Specific Response Fields

A response from IPG may contain additional fields in gateway_specific_response_fields. Fields are included only when IPG returns the mapped value.

<gateway_specific_response_fields>
  <ipg>
    <approval_code>ABC123</approval_code>
    <processor_response_message>Function performed error free</processor_response_message>
    <processor_response_code>00</processor_response_code>
    <processor_association_response_code>AABBCC</processor_association_response_code>
    <processor_approval_code>12345</processor_approval_code>
    <processor_receipt_number>12345</processor_receipt_number>
    <external_merchant_id>8675309</external_merchant_id>
    <terminal_id>1010101</terminal_id>
    <brand>MASTERCARD</brand>
    <processor_trace_number>98765</processor_trace_number>
    <processor_batch_number>72186</processor_batch_number>
    <processor_reference_number>1234567890</processor_reference_number>
    <country>ARG</country>
    <commercial_service_provider>FDCS</commercial_service_provider>
    <payment_type>CREDITCARD</payment_type>
  </ipg>
</gateway_specific_response_fields>

approval_code: IPG approval code for the transaction.
processor_response_message / processor_response_code: Processor result text and code.
brand / payment_type: Card brand and payment type returned by IPG.
external_merchant_id / terminal_id: Merchant and terminal identifiers from the processor.
IPGSchemeTransactionId is not a gateway specific response field. Spreedly returns it as first-class response.network_transaction_id.
Spreedly gateway_transaction_id is IPGIpgTransactionId.

Field Name	Type	Description
approval_code	string	IPG approval code for the transaction.
processor_response_message	string	Processor response message (for example `Function performed error free`).
processor_response_code	string	Processor response code (for example `00`).
processor_association_response_code	string	Card-scheme / association response code.
processor_approval_code	string	Processor approval code.
processor_receipt_number	string	Processor receipt number.
external_merchant_id	string	External merchant identifier returned by IPG.
terminal_id	string	Terminal identifier returned by IPG.
brand	string	Card brand (for example `MASTERCARD`).
processor_trace_number	string	Processor trace number.
processor_batch_number	string	Processor batch number.
processor_reference_number	string	Processor reference number.
country	string	Country code returned by IPG (for example `ARG`).
commercial_service_provider	string	Commercial service provider (for example `FDCS`).
payment_type	string	Payment type returned by IPG (for example `CREDITCARD`).

If you'd like to request additional gateway_specific_fields or gateway_specific_response_fields, contact Support with the gateway documentation for the fields of interest.

Third-party 3DS2

Spreedly maps third-party 3DS2 authentication data to IPG on purchase and authorize (supports_3dsecure_2_mpi_purchase, supports_3dsecure_2_mpi_authorize). Gateway-specific 3DS2 is not supported. See the 3DS2 Third-party Authentication Guide.

Spreedly field	IPG field
three_ds_version / version	Secure3DProtocolVersion
authentication_value (cavv)	AuthenticationValue
directory_server_transaction_id	DirectoryServerTransactionId
xid	XID
directory_response_status	Secure3D2TransactionStatus
authentication_response_status	Secure3D2AuthenticationResponse

REQUEST

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 500,
    "currency_code": "ARS",
    "three_ds_version": "2.1.0",
    "three_ds": {
      "ecommerce_indicator": "05",
      "authentication_value": "jEET5Odser3oCRAyNTY5BVgAAAA=",
      "xid": "jHDMyjJJF9bLBCFT/YUbqMhoQ0s=",
      "directory_server_transaction_id": "925a0317-9143-5130-8000-0000000f8742"
    }
  }
}'

Stored Credentials

For IPG, send stored credential fields using Spreedly’s first-class support. On any Authorize or Purchase, include:

stored_credential_initiator
stored_credential_reason_type

Spreedly maps stored_credential.initial_transaction to IPGrecurringType

Scenario	stored_credential_initiator	Initial transaction	IPG recurringType
First / credential-on-file setup	cardholder or merchant	yes	FIRST
Subsequent use	cardholder or merchant	no	REPEAT

The recurring_type gateway specific field overrides this mapping when present (FIRST or REPEAT).

On a successful first transaction, IPG may return SchemeTransactionId. Spreedly exposes that value as response.network_transaction_id for follow-on MIT requests.

Learn more in the Stored Credentials guide.

Network Tokenization

IPG supports Spreedly network tokenization. Your IPG merchant account must be configured for network tokens. Contact IPG support to enable it.

When attempt_network_token is true (or the payment method has a network token), Spreedly sends:

Device PAN, expiry, and brand in CreditCardData (Brand mapped to VISA, MASTERCARD, AMEX, or DISCOVER)
The cryptogram as IPGTokenCryptogram

REQUEST

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 100,
    "currency_code": "ARS",
    "attempt_network_token": true
  }
}'

Apple Pay

IPG can process Apple Pay through Spreedly’s decrypted-wallet / network-tokenization path. Spreedly decrypts the Apple Pay payload and sends the device PAN, expiry, brand, and payment cryptogram to IPG as TokenCryptogram.

Your IPG merchant account must be enabled for network tokenization. Contact IPG support to configure it.

The current IPG gateway lists credit_card and third_party_token as payment methods. Use Spreedly’s standard Apple Pay tokenization, then purchase or authorize against IPG with network tokenization enabled on the environment.

See the Apple Pay guide for how Apple Pay works with Spreedly.

wallet_id / wallettransaction* gateway specific fields are for LATAMQR reporting only. Do not use them for Apple Pay.

Google Pay

IPG can process Google Pay through Spreedly’s decrypted-wallet / network-tokenization path. Spreedly decrypts the Google Pay payload and sends the device PAN, expiry, brand, and payment cryptogram to IPG as TokenCryptogram.

Your IPG merchant account must be enabled for network tokenization. Contact IPG support to configure it.

The current IPG gateway lists credit_card and third_party_token as payment methods. Use Spreedly’s standard Google Pay tokenization, then purchase or authorize against IPG with network tokenization enabled on the environment.

See the Google Pay guide for how Google Pay works with Spreedly.

wallet_id / wallettransaction* gateway specific fields are for LATAMQR reporting only. Do not use them for Google Pay.

Additional resources

📘
If you need support with this gateway, please contact Support at [email protected].

📘
IPG: https://www.ipg-online.com/,
IPG Documentation: https://www.firstdata.com/downloads/pdf/sg/FirstDataGateway_IntegrationGuide_API_ver1.pdf
API Endpoint: https://www5.ipg-online.com/ipgapi/services (Production)
Test Endpoint: https://test.ipg-online.com/ipgapi/services (Sandbox)