Shift4

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

Open Shift4 in the provider directory and press Connect at Shift4 Provider Overview page in the New connection section. Choose H2H Merchant account.

Step 2 - Fill in fields and select settings

• Client GUID
• Auth Token (or Access Token)
• Clerk ID
• Company Name
• Interface Name
• Save Instant Token -> must be explicitly set to true or false
• Test Mode -> (enable if you are using sandbox credentials)

Corefy doesn't restrict currencies for this connector in advance - available currencies depend entirely on what's enabled for your Shift4 account; confirm with your account manager.

First request to Corefy API (MIN)

What it does: creates a payment-invoice; card data itself is collected and submitted separately by Corefy's checkout/SDK layer, not as part of this request. CVV is always required - non-CVV sales aren't supported. Shift4 runs full 3D Secure 2 and may return a challenge redirect depending on the card.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "7c1e2f4a-9b3d-4e6a-8f12-5a6d7c8e9f01",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "3b4c5d6e-7f8a-49b0-91c2-d3e4f5a6b7c8",
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "address": {
          "city": "New York",
          "street": "1 Main street",
          "post_code": "10001"
        },
        "metadata": {
          "ip": "203.0.113.5"
        }
      }
    }
  }
}

customer is entirely optional and is only used to enrich the sale.

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Positively influence conversion rate - Include optional fields required by your specific flow

Options

• charge_after_failed_challenge -> optional, boolean - allows the charge to proceed even when the 3D Secure challenge fails, instead of cancelling the payment.
• finalize_by_r_status -> optional, boolean - if Shift4 reports a specific "R" status for the transaction, treats it as a hard decline instead of whatever the generic status mapping would otherwise report.
• merchant_timezone -> optional, enum (UTC offset) - the timezone used for the date/time sent with every request; matters for day-boundary/settlement timing on Shift4's side.
• merchant_initiated_transaction -> optional, boolean - marks recurring charges as merchant-initiated instead of customer-initiated (card network stored-credential indicator - see Recurring below).
• fail_on_sale -> optional, boolean - if Shift4 returns an error on the initial sale request, reports it as a definitive decline instead of an ambiguous error status.
• provider_test_env -> optional, boolean - routes this specific request to Shift4's test environment regardless of the connection's own Test Mode setting.

Constants (fallback fields)

• DESCRIPTOR -> the text shown on the customer's card statement. Unlike most connectors, when this constant is set it's used instead of your own transaction descriptor, not just as a fallback for it.

Recurring (save and charge a token)

If Save Instant Token is enabled on your connection, every sale is registered with Shift4 as card-on-file and the resulting token can be charged again later via Corefy's standard recurring request. By default a recurring charge is flagged to Shift4 as customer-initiated; enable merchant_initiated_transaction if you're the one initiating the charge rather than the customer.

Refunds

Shift4 supports partial refunds, but only one refund per payment (no multiple partial refunds against the same payment). Refunds use the card token saved during the original sale - you don't need to resubmit card details.