Sandbox docs

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.