Payment Adapters

CatalystPay supports multiple payment gateways behind a single, unified API. The adapter layer translates between each gateway's specific formats and behaviors so your integration code stays the same regardless of which gateway processes the payment.

Supported gateways

Gateway	Integration	Real-time API	CSV Reconciliation
EMP (Emerchantpay)	API + CSV	Yes	Yes
Vendo	API	Yes	Yes (via Reconciliation API)
Finxp	CSV only	No	Yes
Novalnet	CSV only	No	Yes

Your code never talks directly to these gateways. CatalystPay handles all gateway communication. You interact only with the Payment Session API and Reconciliation API.

What differs between gateways

Mandate verification

The most important difference for your integration is whether the gateway requires a customer redirect for mandate signing:

Gateway	Mandate Handling	Impact on your integration
EMP	Synchronous	`/pay/` returns `completed` or `declined` immediately. No redirect needed.
Vendo	Asynchronous (redirect)	`/pay/` may return `awaiting_verification` with a `verification_url`. You must redirect the customer, then call `/verify/`.
Finxp	CSV only	Not applicable — no real-time payment flow.
Novalnet	CSV only	Not applicable — no real-time payment flow.

Your integration should always check the /pay/ response status. If it's awaiting_verification, redirect to the verification_url. If it's completed, you're done. This makes your code gateway-agnostic.

Vendo verification flow

When using a Vendo gateway, the customer may need to sign their SEPA mandate on Vendo's hosted page:

sequenceDiagram
    participant Your App
    participant CatalystPay
    participant Vendo

    Your App->>CatalystPay: POST /pay/ (IBAN)
    CatalystPay->>Vendo: Submit transaction
    Vendo-->>CatalystPay: Verification required
    CatalystPay-->>Your App: awaiting_verification + verification_url
    Your App-->>Customer: Redirect to verification_url
    Customer->>Vendo: Signs mandate
    Vendo-->>Customer: Redirect back
    Your App->>CatalystPay: POST /verify/
    CatalystPay->>Vendo: Check verification
    Vendo-->>CatalystPay: Approved
    CatalystPay-->>Your App: completed

Status normalization

All gateway-specific status codes are normalized to a single set of CatalystPay statuses. When you query the Reconciliation API with ?status=approved, you get all approved transactions regardless of which gateway processed them. Webhook payloads also use the normalized status set.

You never need to handle gateway-specific status values — CatalystPay does this for you.

CSV import differences

If you import settlement or chargeback CSVs from your payment processors, be aware of these per-gateway differences:

Gateway	Transaction amounts	Chargeback amounts
EMP	Major units (e.g., `29.99`)	Minor units (e.g., `2999` → divided by 100)
Finxp	Major units	Major units
Novalnet	Minor units (divided by 100)	Minor units (divided by 100)

CatalystPay handles the amount conversion automatically during import. Just upload the CSV as-is from your payment processor.

Each gateway uses different CSV column names. When importing, select the correct adapter and CatalystPay will parse the file accordingly. See CSV Imports for column details.

Gateway selection

Gateways are assigned to your tenant by your account manager. You can:

Let CatalystPay choose — When creating a session in campaign mode, the gateway is resolved from the campaign's offer configuration.
Override per-session — Pass gateway_id when creating a session to route a specific payment to a specific gateway. See the Switch Gateway recipe.

Next steps

S2S Integration — See the verification flow in action
Sandbox Testing — Test with different gateways in staging
Reconciliation — Query transactions across all gateways

Sandbox Testing

CSV Imports