Bring your own processor

Processor plugins

Hosted checkout and S2S sale, refund, and payout call the merchant’s assigned adapter. This is a sandbox orchestrator — not live acquiring and not PCI Level 1.

Connect in three steps

1. Pick — open My Profile → Processor management and click Use this processor on Card processor 1, Card processor 2, or any enabled assigned card processor. Platform admins enable slots on /pgui/jsp/acquirers.
2. Paste keys — expand Connect Card processor N and enter that processor’s sandbox credentials (only the fields it needs). Save. Secrets are stored on the merchant record for this APP_ID and redisplay as last 4 / “Configured”. Never paste live production keys.
3. Go live — hosted checkout, S2S, refunds, and payouts call routeForMerchant → plugin.sale (or refund/payout) using that merchant’s keys. You never integrate the processor yourself. PAN/CVV stay on the hosted CDE.

The default assignment is sandbox (local simulator). Switching adapter does not move money to a bank. Sale Report shows the plugin id on captured rows.

Credential precedence

When a charge or refund runs, the assigned plugin resolves keys in this order:

1. Merchant keys saved on the merchant record for that acquirerId.
2. Platform env (adapter env vars) as a sandbox demo fallback.
3. None — the adapter fails closed (keys missing), except the sandbox simulator.

Field-level: a saved merchant value wins for that field; empty merchant fields still fall back to env. Admins see a Yes/No “Merchant keys” flag only — never the secret.

Charge routing

After HASH and field checks, the CDE classifies the test card (Captured / Declined / Enrolled). Then the assigned plugin runs:

• No keys — the adapter fails closed (keys missing), except the sandbox simulator.
• Keys set, no processor token — the plugin reuses the local card decision. Same test cards as test cards. PAN is already gone.
• Keys set + {ADAPTER}_TEST_PAYMENT_METHOD — the plugin may call that processor’s official sandbox HTTP with the token only. Never a PAN.

Results write STATUS, RESPONSE_CODE, ACQ_ID, and ACQUIRER_PLUGIN so the panel and checkout stay in sync.

Sandbox env keys (platform fallback)

Merchants should paste keys on My Profile. Process env remains a platform fallback for sandbox demos. Do not put live secrets in config.json. Test-prefixed keys only.

Optional token to hit official sandbox HTTP: {ADAPTER}_TEST_PAYMENT_METHOD (adapter id uppercased, hyphens to underscores). Copy the full list from .env.example — never commit filled values.

Banking, payouts & cards (white-label rail, not card eCom)

This is a Mr Ivory product rail for banking, rail onboarding, FX, fiat payouts, and virtual prepaid cards. Merchants and customers stay on Mr Ivory. It is not card eCom acquiring — hosted checkout and S2S sale will not charge a card through this slot. Platform KYC stays on Business Summary. Card issuing never stores PAN/CVV. This host is not PCI certified.

1. Platform keys first. A platform admin pastes the Partner API key + API secret on Acquirer Detail, or sets UPP_* env. Mr Ivory owns the partner merchant account. Per-merchant fields exist for ops flexibility — they are not the default go-live path, and merchants are not sent to a partner dashboard.
2. Optional base URL. Default sandbox is https://sandbox.getupp.net/api/v1. https://uppdev.io/api/v1 is an alternate sandbox only. Production is TBD. Only those two hosts are allowlisted.
3. Optional webhook signing secret. Mr Ivory receives events (HTTPS port 443) at POST /webhooks/upp or POST /webhooks/upp/<APP_ID>. Known and unknown types (banking, card issuing) are stored and acknowledged. Hosted verification: Mr Ivory opens the URL with a return_url back to this origin. Prefer a full-page or native webview — the provider may send X-Frame-Options / CSP frame-ancestors that block iframe embed. Funding/banking follows the rail-shaped account payload — there is no AED virtual-account product; UAE is card-holder nationality AE / +971. See Webhooks.
4. Merchant panel. Sidebar Banking walks Customer → Verify → rail KYC → Funding account → Fiat payout on Mr Ivory only. Hosted verification returns to /pgui/jsp/bankingReturn. Missing platform keys fail closed with “Banking rail not configured” — no live call and no invented success. Status chips read stored processor events plus an optional adapter refresh. FX swap and card issuing stay out of this panel. Platform KYC stays on Business Summary.

Mr Ivory remittance (outbound remit, not acquiring)

Mr Ivory remittance is a payout rail, not a card acquirer. Do not assign it as the collect processor. Paste remittance credentials on My Profile → Outbound remittance. Env fallback: TERRAPAY_USERNAME, TERRAPAY_PASSWORD (raw; SHA-256 sent), TERRAPAY_ORIGINCOUNTRY, optional TERRAPAY_BASE_URL. Panel: Remit / Payout — View Account Status, Create Quotation, Create Transaction, View Transaction. Bank and mobile wallet only. Remit-to-card is out of scope. See Payout.

Assigned card processors (UAE T0)

Same bring-your-own-processor model: pick the assigned card processor on My Profile, paste your sandbox credentials, then hosted checkout / S2S go through MrIvory. This host is not PCI certified and is not live acquiring. Sandbox keys and sandbox hosts only — never paste sk_live_ or production keys with test=0.

1. Card processor 23 — paste a test secret key on Connect Card processor 23 (sk_test_…). Optional merchant id. Charges use a processor token only (never PAN/CVV). Authorize / capture / refund / void follow that rail’s public charge APIs. Webhooks verify the hashstring header (HMAC-SHA256 of the documented x_id… fields, keyed with the secret key).
2. Card processor 24 — store id + remote authentication key (Remote Integration must be enabled). Requests always send test=1. Sale/auth send the processor token as card.token; capture/refund/void send the prior tran.ref. Webhooks verify SHA-1 tran_check over the documented colon-separated fields.
3. Card processor 25 — you can select this slot and store BYO merchant id, API key, and terminal id. Live API hosts and paths need partner confirmation; the adapter talks only to the reserved sandbox hostname and never sends PAN/CVV. Treat readiness as Stub until a partner pack confirms the contract.

Acquirers are not one universal charge. Each adapter publishes its own catalog: offered (public processor docs list the product) and wired (this adapter implements it). Payment methods (Settings → Payment methods) lists shopper methods: wired methods are toggles, offered-but-not-wired stay disabled with a short note. Do not treat a documented-but-unwired flag as live in MrIvory. See Payment methods.

Apple Pay, Tabby, Tamara, and SoftPOS stay out of scope for this slice.

UAE e-invoicing via Flick ASP

Flick is Mr Ivory’s first UAE Accredited Service Provider path. Merchants do not integrate Flick themselves. Paste sandbox credentials on My Profile → UAE e-invoicing (or a platform fallback on Acquirers):

• X-Flick-Auth-Key (flick_ae_… API key, or Bearer flick_at_…)
• participant_id
• Base URL — https://sandbox-api.flick.network (sandbox) or https://api.flick.network (live)

Create Invoice / Invoice Records show Submit e-invoice (Flick) when keys are configured. Mr Ivory maps the invoice to Flick’s UAE Regional JSON (POST /v1/participants/{participant_id}/documents) and reads Peppol / FTA status from GET …/documents/{document_id}. HTTP 202 means queued, not delivered. Delivery and FTA reporting fail independently (DCTCE — no clearance).

Mandate: UAE Peppol / FTA pilot 2026 / go-live 2027. B2B and B2G. B2C is out of scope today.

Required merchant fields (never invented): buyer legal name, buyer Peppol ID (scheme 0235), street, city, country, emirate when AE, buyer TRN when VAT-registered, line names and amounts. Seller legal name / TRN are optional overrides — Flick uses the onboarded participant profile if omitted. Non-AED invoices need an AED exchange rate you supply. Missing Flick keys leaves hosted pay-by-link invoices unchanged.

Env fallback: FLICK_AUTH_KEY, FLICK_PARTICIPANT_ID, FLICK_BASE_URL. Official docs: Flick UAE e-invoicing. This host is not PCI certified.

Honest limits

Stub adapters are listed as Stub. Enabling them without keys still fails closed. This host does not claim a scheme licence or PCI Level 1. Production move still requires KYB Approved — that flag is not live acquiring.