Hosted Payment API · v3

Hosted Payment API Guidance & Protocol Cheatsheet

Base Path: /api/v3Method: POST OnlyAuth: Bearer Token

2FA required. Google or Apple Authenticator must be enrolled before any API key can be generated or rotated.

Authentication

header
Authorization: {apiKey}

Must be present on every POST request. Keys are environment-scoped; a missing or malformed header resolves to AUTHENTICATION_FAILED.

Hosted Flow Logic

4 steps
  1. 1Create order
  2. 2Obtain redirectUrl
  3. 3Guide customer
  4. 4Webhook + returnUrl

Supported Methods

native / on request
CardCryptoWallets

On request: Apple Pay, Google Pay, APMs, m-commerce.

Critical 5xx Warning

idempotency

A 5xx on creation means the order was possibly created.

Always poll get-status with the same merchantOrderId before any retry.

Hosted Form Creation & Auth Logic

request + response
POST/api/v3/order/payment-form/create
body · application/json
1{2  "merchantOrderId": "ORD-2026-88431",3  "invoice": {4    "amount": 149.9,5    "currency": "EUR",6    "description": "Plan Pro · annual"7  },8  "client": {9    "email": "ada@merchant.io",10    "taxpayer": "PT509442112"11  },12  "returnUrl": "https://merchant.io/checkout/return",13  "webhookUrl": "https://merchant.io/api/hooks/payments"14}
200 OK · data.auth.redirectUrl
1{2  "data": {3    "orderId": "e7c1f0a4-95d2-4e1b-9a77-2f0b8c31d004",4    "merchantOrderId": "ORD-2026-88431",5    "status": "processing",6    "auth": {7      "type": "redirect",8      "redirectUrl": "https://pay.yourdomain.com/f/e7c1f0a4"9    }10  },11  "error": null12}

Attention: the auth flow varies per method — e.g. a fallback to plain redirect. Systems must handle all data.auth variations dynamically rather than assuming one shape.

Status Checking & Transactions

poll · lifecycle
POST/api/v3/order/get-status
body · application/json
1{2  "merchantOrderId": "ORD-2026-88431"3}

awaiting_confirmation — Non-terminal. Keep polling; do not release goods.

200 OK · status: processing
1{2  "data": {3    "status": "processing",4    "subStatus": "awaiting_confirmation",5    "invoice": { "amount": 149.9, "currency": "EUR" },6    "transactions": [7      {8        "id": "tx_01HQ8",9        "authorized": { "amount": 149.9, "currency": "EUR" },10        "merchantWallet": { "amount": 0, "currency": "EUR" },11        "confirmations": 112      }13    ]14  },15  "error": null16}

Unified 200 OK Rules

never 4xx

Business errors are returned with HTTP 200. Branch on error !== null, never on the HTTP status code.

error envelope
1{2  "data": null,3  "error": {4    "code": "ORDER_ALREADY_EXISTS",5    "message": "merchantOrderId is already in use"6  }7}

Error Code Reference

9/9

ORDER_ALREADY_EXISTS — merchantOrderId collision — poll get-status instead.

Breaking Changes Policy

versioned · /api/v3
Proactive notice
Announced ahead of rollout to every integrating merchant.
Transparent docs
Reference is updated in the same release as the change.
Migration help
Engineering support during the overlap window.