Getting started

Base URL

The production merchant API base URL is:

https://api.nspay.tech

All endpoints below are relative to that host.

Transport

Every endpoint accepts a JSON body and returns a JSON body. The single exception is POST /v1/confirm_payment, which 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 nspay 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, …) — the gateway normalises it deterministically (UUIDv5) before storing, so the same input always maps to the same internal id. It is the idempotency key: re-sending the same (shop, merchant_operation_id) pair returns the original operation rather than creating a new one. Different bodies with the same key are rejected with 412 Precondition Failed.
• client_id — your end-user identifier. Any non-empty string; used for audit and antifraud. Normalised the same way as merchant_operation_id.