Migration from another E-PRO gateway

Why this is straightforward

Our 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.

Separate hosts are used per environment: https://api.sandbox.settleflow.io (test, pk_test_ keys) and https://api.settleflow.io (production, pk_live_ keys).

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 your account manager for:

• A sandbox API key (pk_test_...) and webhook secret.
• A production API key (pk_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.sandbox.settleflow.io/v1/payment/direct
+ Header:  epro-api-key: pk_test_...

The request body can remain identical — the canonical E-PRO field names are accepted. See the Payment reference for the full field list.

Endpoint URLs

Our V1 paths mirror the original E-PRO shape under the /v1 prefix:

So an existing E-PRO integration calling /payment/direct, /status and /refund only needs to prefix the path with /v1 (and change host + API key header). The /direct form of status/refund is kept as an alias, so integrations that already use it keep working.

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: we always return HTTP 200.

Value formats

These match the legacy E-PRO gateway exactly, on all three surfaces: this reply, the ReturnUrl POST, and the notification.

4. Re-validate error handling

The E-PRO numeric error codes 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). Ask your account manager if any appear unexpectedly.

5. Webhooks

Just like legacy E-PRO (where the notification URL is set in the portal account preferences), webhooks are configured at the account level — in the merchant dashboard, separately for each mode (Live / Sandbox). There is no per-request callback parameter; register your endpoint once per mode and every matching event is posted to it.

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. We emit the same field — see 3D Secure. The return to your ReturnUrl is also a POST by default, exactly as on the legacy gateway, so your existing return handler keeps reading the outcome from the request body. Make sure your ReturnUrl points at your production domain before going live, and that you have a fallback to /v1/status if the customer never returns.

7. Dual-run in sandbox, then cut over

Recommended rollout:

1. Point your sandbox / staging traffic here 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 new 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 we expect for the most-used fields (E-PRO canonical naming):

Getting help

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