Stripe

Supports in this guide: Payments

Provider website: stripe.com

What you need to do for start processing transactions (brief summary)

1. Choose account type
2. Get your credentials (from Stripe)
3. Connect in Dashboard
4. Send an API request

Choose account type

Stripe can be connected in different ways (depending on your needs):

• If you do H2H card payments (card data sent directly to Stripe) -> choose H2H Merchant account
• If you do redirect payments via Stripe Checkout (customer redirected to Stripe's hosted page, with access to many local payment methods beyond cards) -> choose Provider account

If you're not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from Stripe

Get the following values from your Stripe Dashboard (both account types use the same API keys, issued per Stripe account):

• Publishable Key -> Corefy field public_key -> example: pk_live_51H... -> where to find: Stripe Dashboard, Developers -> API keys.
• Secret Key -> Corefy field private_key -> example: sk_live_51H... -> where to find: Stripe Dashboard, Developers -> API keys. Sent as the Bearer token on every request - store it securely.
• Webhook Signing Secret (optional) -> Corefy field webhook_secret -> example: whsec_abc123... -> where to find: Stripe Dashboard, Developers -> Webhooks, after adding the endpoint (see Additional info below). Only needed if you want Corefy to receive and verify Stripe's callbacks - without it, final status still reaches you via status polling/reconciliation, just slower.

Additional, for H2H Merchant account only:

• Stripe Account ID -> Corefy field account_id -> example: acct_1H... -> where to find: Stripe Dashboard, Settings -> Business details. Sent as the Stripe-Account header when the Send Account ID toggle below is enabled (Stripe Connect-style "act as this connected account" mode) - if that toggle is left off, this field isn't actually used, but the connection form still asks for a value.
• Apple Merchant ID (optional) -> Corefy field apple_id -> where to find: Apple Developer account, only needed if you plan to enable Apple Pay for H2H.
• Apple Pay Domain (optional) -> Corefy field apple_pay_domain -> the domain you've registered and verified for Apple Pay merchant validation (see Apple Pay docs) -> only needed if you plan to enable Apple Pay for H2H.

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "8e3dbbb0-17af-4c9a-bedb-93bdac6900a2",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10
    }
  }
}

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6795502c-e27d-4d07-85e0-93245aab9a3f",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10.04,
      "descriptor": "MY SHOP ORDER 123",
      "customer": {
        "reference_id": "cus_123",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "name": "John Smith"
      }
    }
  }
}

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "0dde9e79-2c64-4703-adaf-93d710633401",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10
    }
  }
}

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "7976b4ce-fadd-4585-baa0-6b02c65351dc",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10
    }
  }
}

Additional info

H2H Merchant account:

1. Callback authentication and routing. Stripe signs every webhook with a Stripe-Signature header (HMAC-SHA256 over <timestamp>.<raw body>, using your Webhook Signing Secret); Corefy verifies this automatically once that field is set. The callback endpoint is /stripe/callback - add it as a webhook endpoint in your Stripe Dashboard and subscribe to payment_intent.succeeded and payment_intent.payment_failed (disputes that resolve as lost are also picked up via charge.dispute.closed).

2. Apple Pay is supported with decryption on Stripe's side - Stripe validates your registered domain/merchant ID and handles the decrypted payment data server-side. Requires Apple Merchant ID and Apple Pay Domain above, plus enabling Apple Pay in your Stripe Dashboard.

   For more information, visit:

   • How to Integrate Apple Pay with Corefy: Full Technical Walkthrough

Provider account:

1. Callback authentication and routing. Same mechanism as H2H above (Stripe-Signature header, HMAC-SHA256, your Webhook Signing Secret) via the same /stripe/callback endpoint - subscribe to payment_intent.succeeded and payment_intent.payment_failed in your Stripe Dashboard's webhook settings.

2. Local payment methods available on this flow (per the connection's own configuration - not every connection enables every method):

   Method	Currencies
   Cards	EUR, USD, GBP
   Link	EUR, USD, GBP
   Klarna	EUR, USD, GBP
   Revolut Pay	EUR, GBP
   MobilePay	EUR
   Multibanco	EUR
   Bancontact	EUR
   BLIK	PLN
   EPS	EUR
   iDEAL	EUR
   Przelewy24	EUR, PLN
   TWINT	CHF
   Amazon Pay	EUR, USD, GBP

   Apple Pay and Google Pay don't have their own method/service code on this flow - Stripe only accepts them as part of the Cards method and auto-detects them on its own hosted Checkout page once enabled in your Stripe Dashboard's Payment Methods settings; nothing extra needs to be configured on Corefy's side beyond the Cards currency/feature. 5. The product name shown on Stripe's Checkout page is a fixed placeholder generated by Corefy, not something you control. Stripe's Checkout session requires a product name on every line item; Corefy's connector currently sends a generic placeholder value rather than anything derived from your request - don't rely on it to reflect what's actually being purchased. 6. The Checkout session link is valid for 24 hours. If the customer enters invalid payment details, they can reopen the same link and try again within that window - it's still the same transaction. A session only reaches a final failed state once it expires after 24 hours; there's no way to force an earlier expiry from Corefy's side.

FAQ / Troubleshooting

• Invalid credentials / auth error -> verify you used the correct keys for the chosen environment (sandbox vs production), and that the Secret Key matches the account the Publishable Key belongs to
• H2H: CVV missing / invalid card -> a CVV is required for every H2H sale; a request without one fails before reaching Stripe
• H2H: Stripe-Account header errors -> only relevant when Send Account ID is enabled; verify the Stripe Account ID field matches a real, connected Stripe account
• Provider account: Invalid payment_method_types error from Stripe -> the configured route's external method code isn't one Stripe's Checkout API accepts directly; Apple Pay/Google Pay in particular must route through Cards, not their own code - contact your Corefy account manager to review the connection's routes
• Webhook signature invalid -> verify the Webhook Signing Secret matches the endpoint actually configured in your Stripe Dashboard (each webhook endpoint has its own secret)
• Not sure which account type to use? -> ask your Corefy account manager