Migration from another E-PRO gateway

Why this is straightforward

SettleFlow's V1 public API reuses the E-PRO wire contract: request field names, response envelope, and the numeric error code catalog. In most cases, migrating from another E-PRO-compliant gateway means changing the host and the API key header — no payload changes.

Key differences to verify

Before you change any configuration, review the short list of things that differ from a typical legacy E-PRO provider:

Step-by-step migration

1. Request credentials

Ask SettleFlow for:

• A sandbox API key (sk_test_...) and webhook secret.
• A production API key (sk_live_...) and webhook secret (issued once sandbox validation passes).

2. Update your HTTP client

In your existing code, swap:

- POST https://legacy-epro.example.com/payment/direct
- Header:  API-KEY: <legacy-key>
+ POST https://api.settleflow.io/v1/payment/direct
+ Header:  epro-api-key: sk_test_...

The request body can remain identical — SettleFlow accepts the canonical E-PRO field names as well as the common casing variants (firstName, FirstName, firstname…). See Payment → Field-name normalization.

3. Validate response handling

Confirm that your existing response parsing handles the E-PRO envelope unchanged:

{
  "Code": 0,
  "Result": {
    "OperationType": "payment",
    "Status": "captured",
    "Tid": "order-2026-001",
    "Reference": "pr_abc123",
    "Amount": 49.99,
    "Currency": "EUR",
    "UserId": "customer-42",
    "Message": "Payment was successful",
    "Date": "2026-04-22 14:30:45",
    "3DSecure": "no"
  }
}

If your previous provider returned non-200 HTTP codes for errors, adjust the client: SettleFlow always returns HTTP 200.

4. Re-validate error handling

E-PRO numeric error codes in SettleFlow follow the same catalog you already know — see Error codes. The full list is identical in numbering to E-PRO Integration Guideline v1.12.

A few codes are worth reviewing explicitly during migration:

• 3 / 4 — authentication. Different from your previous provider's auth errors; wire them up to the same alerting you had before.
• 104 ("TID already used") — same semantics, triggered if you replay the same Tid.
• 222 — only fires when the merchant configuration demands extra fields (e.g. BirthDate). Check with SettleFlow if any appear unexpectedly.

5. Webhooks

Legacy E-PRO providers typically let you register a single static callback URL. SettleFlow V1 takes the callback URL per request instead:

  POST /v1/payment/direct
  {
    "Amount": "4999",
    …
+   "CallbackUrl": "https://your-shop.com/webhooks/settleflow"
  }

The payload delivered is the same E-PRO "standard response" shape, so your existing webhook handler should accept it unchanged. What's new:

• Your handler must verify the X-SettleFlow-Signature header (see Webhooks → Signature verification).
• Retries are capped at three attempts (5s, 1min, 5min).

6. 3DS flow

If your legacy integration already handles a 3DSecureUrl redirect + polling, nothing changes. SettleFlow emits the same field — see 3D Secure. Make sure your ReturnUrl points at your production domain before going live, and that you have a fallback to /v1/status/direct if the customer never returns.

7. Dual-run in sandbox, then cut over

Recommended rollout:

1. Point your sandbox / staging traffic at SettleFlow while leaving production on the legacy gateway.
2. Replay a representative set of payment, 3DS, refund and status flows. Validate the webhook delivery against the sandbox checklist.
3. Promote the SettleFlow credentials to production. Keep the legacy integration's code behind a feature flag for one billing cycle in case of rollback.

Field mapping cheat-sheet

Commonly asked — here is the spelling SettleFlow expects for the most-used fields (E-PRO canonical naming). Casing variants are accepted too:

Getting help

If you run into migration-specific edge cases — custom fields, dual-routing, account-level requirements — contact your SettleFlow account manager. Keep a handful of Tid / Reference pairs from failed transactions so support can reproduce.