Idempotency
Send Idempotency-Key on create operations so a retry cannot invent a second payment. Keys are scoped to your merchant (and API client).
Same key, same request
Replaying the same key with the same body returns the original resource. For POST /v1/payments that replay still uses HTTP 201 with the original vpay_ object — it does not create a second payment.
Same key, different request
A materially different body with the same key returns 409 idempotency_key_reuse. That usually means two operations accidentally share a key.
409
{
"error": {
"type": "idempotency_error",
"code": "idempotency_key_reuse",
"message": "Idempotency key was already used with a different request body.",
"request_id": "vreq_01EXAMPLE"
}
}Practice
- Derive the key from the business operation, not the HTTP attempt.
- Persist the key before the first request so crashes can retry safely.
- Use a new key for a genuinely new payment or beneficiary.