Getting started

Base URL

The production merchant API base URL is:

https://api.alva.co.nl

All endpoints below are relative to that host.

Transport

JSON endpoints return a JSON body. Operation create/state endpoints accept a JSON body; GET /v1/balances has no request body. POST /v1/confirm_payment uses multipart/form-data: public confirmation always requires confirmation_type=receipt with the receipt file attached. Confirming without a receipt is not supported.

Always send Content-Type: application/json for JSON requests; for multipart, the standard Content-Type: multipart/form-data; boundary=... header is required.

Authentication

Every /v1 request must carry an X-API-Key header issued for your shop. See Authentication for the full set of rules — missing/invalid keys return 401, and the key fixes the merchant/shop the request is attributed to. Cross-shop operation lookups deliberately return 404 rather than disclosing existence.

Identifiers

The operation_id that InOut issues is a UUID string (lowercase, hyphenated):

3fa85f64-5717-4562-b3fc-2c963f66afa6

It is deterministic — derived from your (shop, merchant_operation_id) pair rather than randomly generated — so retrying the same create request always resolves to the same operation_id. Sending anything other than a strict, canonically-formatted UUID for operation_id returns a 400 Bad Request.

The fields you control as a merchant:

• merchant_operation_id — your own identifier for the operation. Any non-empty string works (UUID, hex, integer-as-string, …). It is the idempotency key: re-sending the same (shop, merchant_operation_id) pair returns the original operation rather than creating a new one. Changing the operation type, method, currency, amount or client with the same key returns 412 Precondition Failed; payouts also compare normalized recipient details. A retry does not update metadata such as client_ip.
• client_id — your end-user identifier. Any non-empty string; use the same value for the same client.