# Veracity Pay – Kustom flavour (formerly Klarna Checkout)

Base URL `https://kustom.pay.veracity.se` in place of https://api.playground.kustom.co – Kustom's own paths follow (also at `https://pay.veracity.se/kustom`). Auth: HTTP Basic, username = merchant id (any), password = secret key.

```
KUSTOM_BASE_URL=https://kustom.pay.veracity.se
KUSTOM_USERNAME=acct_…
KUSTOM_PASSWORD=vp_sk_test_…
```

1. `POST /checkout/v3/orders` { purchase_country, purchase_currency, locale, order_amount, order_tax_amount, order_lines[] (unit_price, tax_rate, total_amount, total_tax_amount), merchant_urls { terms, checkout, confirmation, push } } → { order_id, status: "checkout_incomplete", html_snippet }. Render html_snippet on your checkout page.
2. After the purchase the customer goes to merchant_urls.confirmation ({checkout.order.id} replaced). `GET /checkout/v3/orders/{id}` → checkout_complete.
3. A POST without body arrives at merchant_urls.push; then `GET /ordermanagement/v1/orders/{id}` and `POST /ordermanagement/v1/orders/{id}/acknowledge`.
4. Captures `POST …/captures` { captured_amount }, refunds `POST …/refunds` { refunded_amount }, cancel `POST …/cancel`.

### Test outcomes

- Hosted checkout: each flavour follows that provider's order of steps; every verification (3-D Secure, Swish app, BankID) is a six-digit code e-mailed to the payer. A "Test mode" panel picks approve, decline (with a reason, including authentication_failed), pending, timeout or provider error. Invoice asks for a personnummer: use 19121212-1212.
- Magic cards: `4242424242424242` Visa – succeeds; `5555555555554444` Mastercard – succeeds; `4000000000000002` Declined: card declined; `4000000000009995` Declined: insufficient funds; `4000000000000069` Declined: expired card; `4100000000000019` Declined: suspected fraud; `4000000000003220` Requires 3-D Secure authentication; `4000000000000150` Pending, succeeds after 5 s; `4000000000000168` Pending, fails after 5 s; `4000000000000119` Provider error (500); `4000000000000184` Timeout – the session expires; `4000000000000341` Succeeds, but renewals fail.
- Magic amounts (total ends in these öre/cents, at least 1.00): `.01` Declined: card declined; `.02` Declined: insufficient funds; `.03` Declined: expired card; `.04` Declined: suspected fraud; `.05` Declined: credit check failed (invoice); `.06` Requires an extra authentication step; `.07` Pending, succeeds after 5 s; `.08` Pending, fails after 5 s; `.09` Timeout – the session expires.
- `metadata[veracity_test_outcome]` on a Checkout Session or PaymentIntent: `approve`, `decline_card_declined`, `decline_insufficient_funds`, `decline_expired_card`, `decline_fraudulent`, `decline_credit_rejected`, `challenge`, `pending_succeed`, `pending_fail`, `timeout`, `provider_error` (`metadata[veracity_test_delay]` seconds for pending/timeout).
- Without a browser: `POST /v1/test_helpers/checkout/sessions/{id}/complete` with `outcome` (MCP tool `complete_checkout`).
- Next renewal of a subscription: `POST /v1/test_helpers/subscriptions/{id}/next_charge_outcome` with `outcome` = approve | insufficient_funds | restricted_card | timeout (MCP tool `set_next_charge_outcome`).
- Time: `POST /v1/test_helpers/advance_clock` with `months` / `days` (MCP tool `advance_clock`); renewals are charged without a code and send invoice.paid or invoice.payment_failed.
## Going live and deviations from the original

Original documentation: [Kustom Checkout API](https://docs.kustom.co/contents/checkout/integrate-kco-in-your-ecommerce/create-order), [Kustom API URLs](https://docs.kustom.co/contents/api/api-basics/api-urls).

To go live, change only the host and the keys: Playground: `https://api.playground.kustom.co`; Production: `https://api.kustom.co`. Replace the username and password (HTTP Basic) with your Kustom credentials.

Deviations in Veracity Pay:
- Missing: updating an order (POST checkout/v3/orders/{id}) and the validation, address and shipping callbacks.
- No idempotency on captures and refunds, and refunds are not checked against captures.
- Push is sent once (retried on failure), not repeated until the order is acknowledged.
- Recurring payments (recurring_token) are not supported.