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. InOut accepts the file for validation. 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 moves the operation to manual_check for review.

Endpoint

POST /v1/confirm_payment

Multipart request (`receipt`)

Send multipart/form-data with a receipt file. JSON-only confirmation is not supported because the file is required.

Content-Type: multipart/form-data; boundary=...
X-API-Key: 01234567-89ab-4cde-8f01-23456789abcd

Form field	Type	Required	Notes
`operation_id`	text	conditional	The server-issued ID returned by `/v1/payment`.
`merchant_operation_id`	text	conditional	The idempotency key you supplied to `/v1/payment`. Use this when the create response was lost, or when you simply prefer to key off your own order id.
`confirmation_type`	text	yes	Must be `receipt`. Any other value is rejected.
`receipt`	file	yes	PDF, JPEG, PNG, GIF, or WebP. Maximum size: 10 MB.

Provide exactly one identifier: operation_id or merchant_operation_id. Both identify the same payment within your API key's shop.

Example

curl -X POST https://api.alva.co.nl/v1/confirm_payment \
  -H "X-API-Key: 01234567-89ab-4cde-8f01-23456789abcd" \
  -F 'operation_id=f6c2e7d4-3e5b-4f1f-8a02-9d6c7e8a1b22' \
  -F 'confirmation_type=receipt' \
  -F 'receipt=@/path/to/receipt.pdf;type=application/pdf'

Receipt review flow

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

The upload is accepted and the payment enters pending_confirmation.
A clean validation may complete the payment automatically. A suspicious, wrong-amount, or unverifiable receipt moves it to manual_check.
Later status updates arrive through the configured webhooks.

Repeated and late uploads

Retry the same file after an ambiguous response; an already accepted submission is reused. A concurrent finalization can return 409; retry with backoff. Do not replace the file while the payment is pending_confirmation.

A different file can be submitted from manual_check once the previous receipt has been acknowledged by the provider. If that review has changed or is not ready for replacement, the request returns 412; read the state before retrying.

A terminal status alone does not forbid a late receipt upload: eligible payments can accept additional evidence for review. Acceptance of the file does not by itself mean the payment has completed or its financial outcome has changed.

Response

200 OK with the operation object. For an in-flight payment, the object may show pending_confirmation, manual_check, or a final status if processing has already finished. A late receipt can leave the operation terminal. Use the returned status and subsequent webhooks; 200 alone does not mean a successful payment.

Errors

400 — bad form, no identifier (or both), missing or non-receipt confirmation_type, missing receipt file, or non-UUID operation_id; also an operation that is not eligible for receipt submission, such as a payout.
401 — X-API-Key missing or invalid.
404 — no operation with that operation_id in this shop's scope.
409 — another receipt revision is being finalized; retry the same file with backoff.
412 — the previous receipt review changed or is not ready for replacement.
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.