Skip to content

Shift4

Process card payments through Shift4 (Europe): the contract, the supported features and the test cards.

For PayFacs and ISOs that process through Shift4. Ginger connects to the Shift4 gateway in Europe: Shift4 acquires the payments, and each of your merchants' projects is a sub-merchant under your Shift4 merchant account. You configure the Shift4 identifiers and signing key per project, in a contract.

How it works

Shift4 is the card processor of your platform, or of the merchants you assign to it (see Payments). A card payment through Shift4 goes like this:

  1. The customer enters the card details on the hosted payment page, or in the merchant's own checkout. Ginger stores the card in its vault.
  2. Ginger authenticates the customer with 3-D Secure (3DS) through Shift4: a device fingerprint, then a frictionless result or a challenge from the card issuer.
  3. With the authentication result, Ginger sends the payment to Shift4 and gets the result straight away: the transaction is successful, or gets the status error when Shift4 declines it.

Ginger signs every request to Shift4 with the signing key of the contract. Apple Pay and Google Pay payments are processed over the same contract.

Contract

Shift4 gives you a gateway merchant ID, a sub-merchant ID per merchant and a signing key. Fill them in on the Shift4 contract of the project: in the Admin portal, open the project, go to the Payment Method Contracts tab, switch on Shift4 and open it. With the Boarding API, set the shift4 contract of the project.

merchant_id, sub_merchant_id and signing_key are required. The merchant_id is your gateway merchant ID at Shift4, not the ID of your merchant on Ginger. Optionally limit the currencies and brands, and allow pre-authorisations. See the shift4 fields of Update a project contract in the API reference.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/shift4/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "merchant_id": "<your gateway merchant ID>",
    "sub_merchant_id": "<sub-merchant ID>",
    "signing_key": "<signing key>",
    "currencies": ["EUR", "GBP"],
    "manual_capture_enabled": true
  }'

The project also needs permission for /payment-methods/credit-card/ with POST: see Permissions.

A project without a merchant_id, sub_merchant_id or signing_key can't start Shift4 payments: the transaction is refused with a message that names the missing field.

Keep the signing key secret

Anyone with the signing key can sign requests for your Shift4 account. Only enter it in the contract.

Payment methods and features

Shift4
Payment methodscredit-card, apple-pay, google-pay
3-D SecureThrough Shift4
SaleYes
Pre-authorisation, capture and voidYes, when enabled in the contract (since July 2025)
RefundYes, of sales and of captured pre-authorisations
One-click paymentsNo
Recurring paymentsNo

For the requests, see Pre-authorizations and Refunds in the payment acceptance docs.

Test cards

Test with a project in test mode (status active-testing). Test payments go to the Shift4 test environment. For a test project, Ginger can use the test credentials of your platform instead of the contract.

BrandCard number3DS flowChallenge code
Visa4018810000100036Frictionless
Mastercard5420711000210016Frictionless
American Express375987000169677Frictionless
Diners Club36849800000679Frictionless
Visa4018810000150015Challenge0101 succeeds, 3333 fails
Mastercard5299910010000015Challenge4445 succeeds, 9999 fails
American Express375987000000005Challenge5678 succeeds, 3333 fails
Discover6011947300799885Challenge5678 succeeds, 3333 fails

American Express isn't in the default brands of a Shift4 contract: ask your Ginger contact whether it's available through Shift4 before you test it.

Next steps