SupportBlog
Guides

Shift4 REST gateway guide

Shift4 REST fact sheet

Quick Start

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

  1. Retrieve your Shift4 Rest credentials:
    1. Contact your Shift4 representative to enable REST API access for your merchant account.
    2. Collect your Client GUID and Auth Token. Shift4 issues separate credentials for its test and production environments.
  2. Get familiar with the Spreedly API:
    1. Review Spreedly API basics.
    2. Review Gateways, Payment Methods, and Transactions.
  3. Add an Shift4 Rest gateway to Spreedly in sandbox mode.
📘

Review this documentation to understand more about how to test transactions.

Additional notes
  1. Required credentials:client_guid and auth_token.
  2. Endpoints: Test https://utgapi.shift4test.com/api/rest/v1/ .Live https://utg.shift4api.net/api/rest/v1/.
  3. Region / country: North America, Latin America.
  4. Default currency:USD; transaction amounts are sent in cents.
  5. Supported card brands: Visa, Mastercard, American Express, Discover.
  6. Supported payment methods: credit card, third-party token (Shift4 card token).
  7. Purchase runs a Shift4 sale; Authorize runs a Shift4 authorization.
  8. Capture completes an authorization for the full amount. Partial capture is not supported.
  9. Void cancels a transaction by its Shift4 invoice number.
  10. Refund (credit) supports the full amount only. General credit (unreferenced refund to a card) is supported.
  11. Verify validates a card and supports stored credential fields.
  12. Store creates a Shift4 card token, returned as a third-party token you can use on later transactions.
  13. 3DS2: neither Spreedly 3DS2 Global nor gateway-specific 3DS2 is supported.
  14. Every Shift4 transaction has an invoice number. On an approved transaction it is returned as the gateway_transaction_id and in gateway_specific_response_fields.shift4.invoice. On a declined transaction, gateway_transaction_id is empty and the invoice number is in gateway_specific_response_fields.shift4.invoice. If Shift4 returns an error such as a timeout or "Unable to communicate with the payment system," gateway_transaction_id is empty and the invoice number is returned in gateway_specific_response_fields.shift4.invoice_id. Look it up in your Shift4 account to confirm the final status before retrying.

Adding a Shift4 REST Gateway

Required Credentials

  • client_guid: Your Shift4 Client GUID.
  • auth_token: Your Shift4 Auth Token. Spreedly uses it to obtain the access token sent on every request.

REQUEST

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
  <gateway_type>shift4</gateway_type>
  <client_guid>your_client_guid</client_guid>
  <auth_token>your_auth_token</auth_token>
</gateway>'

RESPONSE

<gateway>
    <token>XXXXXXXXXXXXXXXXXXXXXXXXXX</token>
    <gateway_type>shift4</gateway_type>
    <name>Shift4 REST API</name>
    <description nil="true"/>
    <merchant_profile_key nil="true"/>
    <sub_merchant_key nil="true"/>
    <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">false</supports_partial_capture>
        <supports_credit type="boolean">true</supports_credit>
        <supports_partial_credit type="boolean">false</supports_partial_credit>
        <supports_general_credit type="boolean">true</supports_general_credit>
        <supports_void type="boolean">true</supports_void>
        <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">false</supports_3dsecure_2_mpi_purchase>
        <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
        <supports_store type="boolean">true</supports_store>
        <supports_remove type="boolean">false</supports_remove>
        <supports_fraud_review type="boolean">false</supports_fraud_review>
        <supports_network_tokenization type="boolean">false</supports_network_tokenization>
        <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
        <supports_inquire_by_order_id type="boolean">false</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_refund type="boolean">true</supports_refund>
        <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    </characteristics>
    <credentials>
  </credentials>
    <gateway_settings>
  </gateway_settings>
    <gateway_specific_fields>
        <gateway_specific_field>numeric_id</gateway_specific_field>
        <gateway_specific_field>notes</gateway_specific_field>
        <gateway_specific_field>tax</gateway_specific_field>
        <gateway_specific_field>customer_reference</gateway_specific_field>
        <gateway_specific_field>destination_postal_code</gateway_specific_field>
        <gateway_specific_field>product_descriptors</gateway_specific_field>
        <gateway_specific_field>merchant_time_zone</gateway_specific_field>
        <gateway_specific_field>date_time</gateway_specific_field>
        <gateway_specific_field>usage_indicator</gateway_specific_field>
        <gateway_specific_field>indicator</gateway_specific_field>
        <gateway_specific_field>scheduled_indicator</gateway_specific_field>
        <gateway_specific_field>transaction_id</gateway_specific_field>
        <gateway_specific_field>interface_name</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">true</sandbox>
    <mode>default</mode>
    <created_at type="dateTime">2026-10-07T10:54:55Z</created_at>
    <updated_at type="dateTime">2026-10-07T10:54:55Z</updated_at>
</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": 1000,
      "currency_code": "USD",
      "order_id": "ABC123",
      "retain_on_success": true,
      "gateway_specific_fields": {
        "shift4": {
          "numeric_id": "7158",
          "notes": "Online order"
        }
      }
    }
  }'

Note

order_id is mapped to Shift4's transaction.vendorReference. email, ip, billing_address.address1, billing_address.zip, and the card holder's first and last name are sent in Shift4's customer object.

Gateway Specific Fields

<gateway_specific_fields>
  <shift4>
    <gateway_specific_field>numeric_id</gateway_specific_field>
    <gateway_specific_field>notes</gateway_specific_field>
    <gateway_specific_field>tax</gateway_specific_field>
    <gateway_specific_field>customer_reference</gateway_specific_field>
    <gateway_specific_field>destination_postal_code</gateway_specific_field>
    <gateway_specific_field>product_descriptors</gateway_specific_field>
    <gateway_specific_field>merchant_time_zone</gateway_specific_field>
    <gateway_specific_field>date_time</gateway_specific_field>
    <gateway_specific_field>usage_indicator</gateway_specific_field>
    <gateway_specific_field>indicator</gateway_specific_field>
    <gateway_specific_field>scheduled_indicator</gateway_specific_field>
    <gateway_specific_field>transaction_id</gateway_specific_field>
    <gateway_specific_field>interface_name</gateway_specific_field>
  </shift4>
</gateway_specific_fields>
  • customer_reference / destination_postal_code / product_descriptors: Level 2 purchase-card data, sent in Shift4's purchaseCard object.
  • merchant_time_zone / date_time: control the transaction timestamp Shift4 receives. Use merchant_time_zone when your business is not on US Pacific time.
  • usage_indicator / indicator / scheduled_indicator / transaction_id: override the card-on-file values Spreedly sets from the stored credential fields (see Stored Credentials).

The Shift4 field each one maps to is in parentheses in the Description column.

Field NameTypeRequiredApplies ToDescriptionExample Value
numeric_idStringNoPurchase, Authorize, Capture, Refund, General CreditClerk ID (clerk.numericId). Defaults to 1.7158
notesStringNoPurchase, Authorize, Capture, Refund, General CreditFree-text notes on the transaction (transaction.notes).Online order
taxDecimalNoPurchase, Authorize, Capture, Refund, General CreditTax amount included in the total, in major units (amount.tax). Defaults to 0.2.50
customer_referenceStringNoPurchase, AuthorizeLevel 2 customer reference (purchaseCard.customerReference).CUSTREF123
destination_postal_codeStringNoPurchase, AuthorizeLevel 2 destination postal code (purchaseCard.destinationPostalCode).98721
product_descriptorsArray of stringsNoPurchase, AuthorizeLevel 2 product descriptors (purchaseCard.productDescriptors).["Tickets", "Parking"]
merchant_time_zoneStringNoAllTime zone used to build the transaction timestamp (dateTime) when date_time is not sent. Values follow the Rails time zone names, or IANA names such as America/New_York. Defaults to Pacific Time (US & Canada).Eastern Time (US & Canada)
date_timeStringNoAllTransaction timestamp in ISO 8601 with offset (dateTime). Overrides merchant_time_zone.2026-10-07T10:15:00.000-04:00
usage_indicatorStringNoPurchase, Authorize, VerifyCard-on-file usage indicator (cardOnFile.usageIndicator).02
indicatorStringNoPurchase, Authorize, VerifyCard-on-file indicator (cardOnFile.indicator). Defaults to 01.01
scheduled_indicatorStringNoPurchase, Authorize, VerifyCard-on-file scheduled indicator (cardOnFile.scheduledIndicator).01
transaction_idStringNoPurchase, Authorize, VerifyNetwork transaction ID from the initial card-on-file transaction (cardOnFile.transactionId).000000000000000
interface_nameStringNoAllIdentifies your integration to Shift4 (InterfaceName header). Defaults to Spreedly.MyStore

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <shift4>
    <network_transaction_id>000000000000000</network_transaction_id>
    <invoice>1234567890</invoice>
    <response_code>A</response_code>
  </shift4>
</gateway_specific_response_fields>
  • invoice: Shift4 invoice number. Capture and void use it automatically.
  • response_code: Shift4 transaction response code. A means approved.
  • network_transaction_id: Spreedly stores this value and sends it on subsequent stored credential transactions.
Field NameTypeDescriptionExample Value
invoicestringShift4 invoice number (transaction.invoice).1234567890
response_codestringShift4 transaction response code (transaction.responseCode).A
network_transaction_idstringCard-on-file transaction ID (transaction.cardOnFile.transactionId).000000000000000

Note

Spreedly's gateway_transaction_id is the Shift4 invoice number.

Stored Credentials

Shift4 REST supports Spreedly's stored credentials fields (stored_credential_initiator / stored_credential_reason_type) on purchase, authorize, and verify. Spreedly maps them to Shift4's cardOnFile object:

Shift4 fieldValue Spreedly sends
usageIndicator01 on the initial transaction, 02 on subsequent transactions
indicator01
scheduledIndicator01 when stored_credential_reason_type is recurring or installment; 02 otherwise
transactionIdThe network transaction ID from the initial transaction, on subsequent transactions

To set any of these values directly, send the usage_indicator, indicator, scheduled_indicator, or transaction_id gateway specific fields. They take precedence over the values above.

📘

Learn more about how spreedly enables use of stored credentials by reviewing our Stored credentials Guide

Mastercard Transaction Link ID

For Mastercard stored credential transactions, Spreedly sends the Transaction Link ID (cardOnFile.transactionLinkId) and saves the value Shift4 returns for later merchant-initiated transactions.

📘

Learn more about how spreedly enables use of Mastercard Transaction Link ID by reviewing our Mastercard Transaction Link ID guide

Additional resources

📘

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

📘

Updated 1 day ago

Did this page help you?