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:
- 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.
- 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.
- With the authentication result, Ginger sends the payment to Shift4 and gets the result straight away: the transaction is successful, or gets the status
errorwhen 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_, sub_ and signing_ are required. The merchant_ 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 / with POST: see
Permissions.
A project without a merchant_, sub_ or signing_ 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 methods | credit-card, apple-pay, google-pay |
| 3-D Secure | Through Shift4 |
| Sale | Yes |
| Pre-authorisation, capture and void | Yes, when enabled in the contract (since July 2025) |
| Refund | Yes, of sales and of captured pre-authorisations |
| One-click payments | No |
| Recurring payments | No |
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.
| Brand | Card number | 3DS flow | Challenge code |
|---|---|---|---|
| Visa | 4018810000100036 | Frictionless | |
| Mastercard | 5420711000210016 | Frictionless | |
| American Express | 375987000169677 | Frictionless | |
| Diners Club | 36849800000679 | Frictionless | |
| Visa | 4018810000150015 | Challenge | 0101 succeeds, 3333 fails |
| Mastercard | 5299910010000015 | Challenge | 4445 succeeds, 9999 fails |
| American Express | 375987000000005 | Challenge | 5678 succeeds, 3333 fails |
| Discover | 6011947300799885 | Challenge | 5678 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
- Processor contracts: contracts and capture modes.
- Board a merchant
- Test data for the merchants' developers.