Migrating to Exirom

This guide covers what changes when you move from another payment provider to Exirom — credentials, endpoint mapping, webhook format, and cutover strategy.

---

#Before You Start

Gather these from your current PSP before switching:

• Your current transaction volume per method (cards, APMs, payouts) — tells you which Exirom integrations to prioritize
• List of payment methods you currently accept — verify each is supported in Exirom (see APM Method Reference)
• Your current webhook endpoint URLs — you'll repoint them to Exirom callbacks
• List of stored card tokens — Exirom issues its own tokens; existing PSP tokens cannot be migrated
• Your active subscriptions / recurring schedules — these need to be recreated after re-tokenizing cards
• Current refund window policy — confirm Exirom refund timeframes with your account manager

Contact your Exirom account manager to receive sandbox and production credentials before starting.

---

#What Changes

#Authentication

Most PSPs use static API keys in request headers. Exirom uses short-lived JWT tokens obtained by calling POST /api/v1/auth with your merchantKey and merchantSecret.

→ See Quick Start: Authentication for the full auth flow with code examples.

#Endpoint Structure

Exirom uses a RESTful API under /api/v1/. All endpoints require the Authorization: Bearer {token} header.

#Merchant Identifier

Exirom uses two identifiers depending on the API:

These are separate identifiers for the same merchant account. Both are provided by Exirom at onboarding.

#Idempotency

Exirom uses a requestId field (in the request body) as the idempotency key — not an Idempotency-Key header. Submitting the same requestId twice returns the original result rather than creating a duplicate charge.

#Webhooks

Exirom POSTs callbacks to your callbackUrl (provided per-request, not globally configured). The payload uses transactionStatus rather than provider-specific event names.

→ See Webhook Quick Start for signature verification code.

#3D Secure

Exirom returns transactionStatus: "CUSTOMER_VERIFICATION" and a challengeUrl when 3DS is required. Redirect the customer to challengeUrl — the final result arrives via webhook after the challenge completes.

This is the same model as most modern PSPs. The key difference: do not use the redirect back to successRedirectUrl as payment confirmation — always wait for the webhook.

---

#Card Tokens

Existing card tokens from your previous PSP cannot be transferred to Exirom. Each PSP issues its own tokens tied to their vault.

Your migration options:

---

#Testing Your Migration

Run through these scenarios in sandbox before switching production traffic:

#Core flows

• Authenticate and cache token
• Card payment — success (4111111111111111)
• Card payment — 3DS challenge (4000000000003220)
• Card payment — decline (4000000000000002)
• Webhook received, signature verified, order fulfilled
• Status poll fallback (GET /api/v1/payments/card/status/{id})

#If you use tokenization

• Tokenize a card (POST /api/v1/payments/card/tokenize)
• Charge the token (POST /api/v1/payments/card/charge)
• Recurring charge (POST /api/v1/payments/card/recurring)

#If you use APMs

• APM redirect flow (actionType: REDIRECTION)
• APM webhook received with ?paymentMethod=apm&apmType=...

#If you use payouts / refunds

• Payout (POST /api/v1/payouts/card or /payouts/apm)
• Refund (POST /api/v1/refunds/card)

→ See Sandbox Test Data for all test cards and APM scenarios.

---

#Cutover Strategy

Recommended approach for zero-downtime migration:

1. Run in parallel — deploy Exirom integration alongside the existing PSP. Route a small percentage of new transactions to Exirom first.
2. Validate in production — monitor success rates, webhook delivery, and decline patterns for 24–48 hours before full cutover.
3. Shift all new traffic — once validated, route 100% of new transactions to Exirom.
4. Handle legacy transactions — keep the old PSP integration active for refunds and disputes on transactions that processed there. Decommission only after your refund window has passed (typically 180 days).

---

#See Also

• Quick Start: Authentication — token flow with code
• Quick Start: Card Payment — first card payment
• Quick Start: APM Payment — first APM payment
• Webhook Quick Start — signature verification and handler setup
• Going to Production — credential management and pre-launch checklist
• Integration Checklist — track your go-live progress