Verifying Payments#

Cartino Pay always verifies a payment with the external gateway server-to-server before it becomes paid — automatically when the payer's browser returns from the gateway. You normally do not need to do anything.

POST /api/v1/payments/{payment_id}/verify exists for the cases where the automatic path did not complete:

• the payer closed the browser after paying, so no callback reached Cartino Pay,
• the gateway was unreachable when the callback arrived (status=pending on your callback page),
• you want to reconcile old pending payments.

POST /api/v1/payments/PAY_01J9X4Z8K3M2N5P7Q9R1S3T5V7/verify
Authorization: Bearer cp_live_…

The response is the payment object with the resulting status.

Guarantees#

• Idempotent. A payment already paid is returned immediately without contacting the gateway. A gateway that reports "already verified" is treated as success, not an error. Calling verify twice can never double-charge or double-count.
• Serialised. Concurrent verifications of the same payment are queued behind a lock; the second caller sees the first caller's result.
• Safe on failure. If the gateway is unreachable the payment stays pending and you get 503 GATEWAY_UNAVAILABLE; retry later.
• Terminal statuses are stable. failed and cancelled payments are not re-verified; expired payments are — if the payer completed the payment at the last second, verification moves it to paid and a payment.paid webhook is sent.

Errors#

Reconciliation job (recommended)#

Run every few minutes:

for each order with cartino status in (pending, processing) and created > 5 minutes ago:
    POST /api/v1/payments/{payment_id}/verify
    update the order from data.status

This catches every missed webhook. It is cheap: verified payments short-circuit without a gateway call.