Implementing the Ewity Connect Flow

The connect flow is how a merchant links their Ewity account to your
platform — self-serve, with no human-in-the-loop on Ewity's side. Instead of
a full OAuth dance, the merchant generates a one-shot pairing code in your
dashboard and pastes it into Ewity. Ewity calls back to verify the code, and
the two accounts are linked.

This guide walks through the whole merchant journey, screen by screen, so you
can see exactly what you build and where each API call happens. For the exact
request and response schemas, follow the links to the reference pages as you
go.

What you build

Three pieces. The first lives entirely in your product; the other two are the
one Connect URL you set on your application in the
Developer Portal (Ewity hits the same URL with GET for
instructions and POST to verify).

You configure one Connect URL, not two. The GET and the POST
hit the same URL — branch on the HTTP method. Set it on your application's
Configuration tab in the Developer Portal. Both carry the same
Authorization: Bearer token you already use for platform-v1.

The merchant journey, step by step

Step 1 — The merchant starts in your dashboard

The journey begins on your side. A logged-in merchant finds your Ewity
integration and clicks a button to begin. No Ewity API call happens yet —
this surface is entirely yours.

Merchants can start from either side. Some will open Ewity first and
click Enable on your platform before ever visiting your dashboard — that's
fine, because the instructions Ewity shows them (Step 3) are the ones you
return from GET {connect_url}, and they point the merchant right back to
this screen. Build this surface and those instructions as a pair.

Step 1 — the merchant starts in your dashboard. You design this screen.

Step 2 — Your app shows a one-shot code

When they click your button, mint a pairing code and show it to them, along
with instructions telling them where to enter it in Ewity. Nothing from Ewity
is involved yet.

The code you generate must be:

• Single-use — valid for exactly one successful verification.
• Account-bound — tied to the merchant who was logged in when it was
  minted, so it can only ever link their account.
• Short-lived — a ~10-minute TTL is recommended.
• Generated only behind login — never on a public page.

Step 2 — your app shows the code and tells the merchant where to paste it.

Step 3 — The merchant opens Ecommerce → Platforms in Ewity

The merchant now switches to Ewity POS, opens the sidebar, goes to
Ecommerce → Platforms (heading: "Ecommerce Platforms"), finds your card,
and clicks Enable.

The moment they click Enable, Ewity calls GET {connect_url} and renders
your instructions inside the modal. So the text the merchant reads inside
Ewity is authored by you — this is your chance to restate the steps from Step
2 in the merchant's face at the exact moment they need them.

Step 3 — the merchant clicks Enable on your card in Ewity. This fires GET {connect_url}.

The GET endpoint is strongly recommended, not strictly required. If
Ewity gets any non-200 (or no response), it falls back to generic copy
— "Generate a connection code on Online Order MV and paste it here…". That fallback
only works if your dashboard has an obvious "Connect to Ewity" entry point,
so implement the endpoint and don't rely on the fallback. See
GET — Connect Instructions.

Step 4 — The "Connect to Online Order MV" modal

With the modal open, the merchant sees your instructions above an input
labeled Connection code (or your code_label override). They paste the
code from Step 2 and click Connect.

Step 4 — the merchant pastes the code and clicks Connect. This fires POST {connect_url}.

Step 5 — Behind the scenes: Ewity verifies the code

On Connect, Ewity POSTs the code to your Connect URL. You look it up,
confirm it exists, is unexpired, and is unconsumed, mark it consumed, and
return the merchant's stable id on your side as external_account_id (plus an
optional display_name).

The request Ewity sends:

POST {your_connect_url} HTTP/1.1
Authorization: Bearer {your_shared_platform_auth_token}
Content-Type: application/json
Accept: application/json

{ "connect_code": "XK4-PQR-9TZ" }

On success, return 200:

{
  "external_account_id": "merchant_42",
  "display_name": "Patty Noir"
}

On rejection, return a 4xx with an OAuth-style body:

{
  "error": "expired_code",
  "error_description": "This connection code has expired. Generate a new one and try again."
}

Step 5 — Ewity verifies the code against your Connect URL.

error_description is shown to the merchant verbatim in the modal.
Write it as user-facing copy — "This connection code has expired. Generate
a new one and try again." — not an internal error string. See
POST — Verify Connect Code for the full field list and
suggested error codes.

Step 6 — Linked

On a 200, Ewity links the merchant to your platform (or restores the link
if they'd connected before). The modal closes and the merchant lands on the
platform-details page.

Step 6 — the merchant is linked. Their platform-v1 activity now flows for that account.

The full exchange

sequenceDiagram
    actor M as Merchant
    participant P as Partner app
    participant POS as Ewity POS
    participant API as Ewity API
    participant CU as Partner connect URL

    M->>P: Click "Integrate with Ewity" (behind login)
    P->>P: Mint one-shot code (account-bound, ~10 min TTL)
    P-->>M: Show code + instructions
    M->>POS: Ecommerce → Platforms → Enable
    POS->>API: Open Connect modal
    API->>CU: GET connect_url (Bearer token)
    CU-->>API: 200 instructions + code_label
    API-->>M: Render instructions + code input
    M->>POS: Paste code, click Connect
    POS->>API: Submit connect_code
    API->>CU: POST connect_url (connect_code)
    alt code valid
        CU->>CU: Mark code consumed
        CU-->>API: 200 external_account_id + display_name
        API->>API: Link merchant to your platform
        API-->>M: Linked — platform details page
    else code invalid, expired, or already used
        CU-->>API: 4xx error + error_description
        API-->>M: Show error_description verbatim
    end

Checklist before you ship

Distilled from the verify reference — validate against
this before going live:

• Single-use codes. A successful verify marks the code consumed; a
  second verify of the same code returns 4xx (invalid_code /
  code_already_consumed).
• Account-bound codes. A code minted while merchant A was logged in
  never resolves to merchant B. This is the security property the whole
  flow depends on.
• Short TTL. Codes expire (~10 minutes recommended) and stop being
  valid once expired.
• Generated only behind auth. The "Integrate with Ewity" button lives
  behind your normal merchant login — never on a public page.
• Bearer token verified on both GET and POST. Check
  Authorization: Bearer against your shared platform token on every
  request; reject anything else with 401.
• Friendly error_description. It's shown to the merchant verbatim —
  write it as user-facing copy, not an internal error string.
• Stable external_account_id. Return an identifier that stays
  constant for the lifetime of the link — not a one-shot value.

Reference