Confirm payment

Confirm a pending payment. Used when the operation response carried external_confirmation.required: true.

Public confirmation always requires a receipt: set confirmation_type to receipt and upload the receipt file. nspay stores the file in object storage and validates the receipt. A confirmation without a receipt is not accepted on the public API.

Requests that omit the receipt file or use another confirmation type are rejected with 400.

The receipt confirmation returns after the file is accepted, attached to the operation, and submitted for validation. For self-matching routes a clean validation may complete the payment automatically; suspicious, wrong-amount, or unavailable validation keeps the operation pending until an operator confirms or rejects it.

Endpoint

POST /v1/confirm_payment

Multipart request (`receipt`)

Send multipart/form-data with a receipt file. The file is stored privately; dispatcher keeps the opaque storage reference in the upload record.

Content-Type: multipart/form-data; boundary=...
X-API-Key: nspay_live_…

Form field	Type	Required	Notes
`operation_id`	text	yes	The `operation_id` returned by the original payment.
`confirmation_type`	text	yes	Must be `receipt`. Any other value is rejected.
`actual_amount`	text	no	Decimal string with scale 2. Omit or send empty for the default (the expected amount).
`receipt`	file	yes	PDF, JPEG, PNG, GIF, or WebP. Maximum size: 10 MB.

Example

curl -X POST https://api.nspay.tech/v1/confirm_payment \
  -H "X-API-Key: nspay_live_…" \
  -F 'operation_id=f6c2e7d4-3e5b-4f1f-8a02-9d6c7e8a1b22' \
  -F 'confirmation_type=receipt' \
  -F 'actual_amount=1500.00' \
  -F 'receipt=@/path/to/receipt.pdf;type=application/pdf'

The receipt file is mandatory. If the file is missing, too large, or object storage cannot accept it, the request fails and the operation stays pending. If validation reports a clean match, nspay may complete the payment automatically. If validation fails, detects a different amount, or is unavailable after retries, the payment remains pending for manual review.

Receipt review flow

The payment is not considered completed just because the upload succeeded:

The gateway stores the file in object storage.
Dispatcher durably records the upload, changes the operation to pending_confirmation, and proxies it to the accepted provider.
Self-matching puts its provider payment on hold and validates through antifraud.
A clean validation confirms the payment automatically.
Failed, wrong-amount, or unavailable validation remains pending until an operator confirms or rejects it.
The final status is delivered through the normal webhook.

An operation accepts one durable receipt submission. Once accepted, the merchant is no longer asked to upload another receipt.

Response

200 OK with the operation object. The object may be completed immediately after a clean validation or may still be pending; any later final status is delivered through the normal webhook after operator review.

Errors

400 — bad form, missing operation_id, missing or non-receipt confirmation_type, missing receipt file, malformed actual_amount, or non-UUID operation_id.
401 — X-API-Key missing or invalid.
404 — no operation with that operation_id in this shop's scope.
412 — the operation is not in a state that accepts confirmation (already terminal, or no external confirmation expected).
413 — receipt file is larger than 10 MB.
415 — receipt media type is not PDF, JPEG, PNG, GIF, or WebP.
502 — receipt object storage is unavailable or rejected the upload.