Ewity calls this when the merchant submits the modal with their pairing code. You verify the code is valid, mark it consumed, and return the merchant's account id on your side. Ewity then links that merchant to your platform — from this point on, their platform-v1 calls are routed to your platform.
Request
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" }| Field | Type | Required | Notes |
|---|---|---|---|
connect_code | string | yes | The one-shot code your dashboard generated. 6–64 chars. |
Response — 200
{
"external_account_id": "merchant_42",
"display_name": "Patty Noir"
}| Field | Type | Required | Notes |
|---|---|---|---|
external_account_id | string | yes | Your stable identifier for the merchant's account on your side. We store it against the merchant's connection so future support requests can be cross-referenced. Must be stable for the lifetime of the link — don't return a one-shot value. |
display_name | string | no | Optional human-readable label for the linked account, surfaced in our admin UI. |
Response — 4xx (rejection)
Reject the code with a 400 (or 401/410/403 as appropriate) and an OAuth-style body:
{
"error": "invalid_code",
"error_description": "This connection code has expired."
}| Field | Type | Notes |
|---|---|---|
error | string | A short machine-readable code. Suggested values: invalid_code, expired_code, code_already_consumed, unauthorized. |
error_description | string | Human-readable detail. We surface this verbatim to the merchant in the modal, so make it user-friendly. |
Code semantics — what we expect from your side
- Single-use. A successful verify must mark the code consumed; a second verify of the same code must return
400 invalid_code(or similar). - Bound to a single merchant account on your side. A code minted while merchant A was logged in must never resolve to merchant B — this is what gives the flow its security property.
- Short TTL. Recommended ~10 minutes. Codes minted but not used should expire and stop being valid.
- Generated only after authentication. The "Generate Connection Code" button in your dashboard must be behind your normal merchant login.
If you violate any of these the worst case is a merchant accidentally connecting the wrong account — which they can recover from by disconnecting and re-pairing, but is the security property we depend on.
Idempotency on our side
If the merchant has already linked your platform, a successful verify will update the stored external_account_id rather than creating a duplicate connection. If they had previously disconnected, the connection is restored. So a merchant can re-pair after disconnecting without you needing to do anything special.