Skip to main content
Documentation

Veyra API

Server-driven payments API plus a browser embed. Your server creates a signed checkout session with your secret key; the customer pays inside a Veyra-hosted iframe; your server is notified via a signed webhook. Card data never touches your servers.

How it fits together

  1. Your server requests a checkout session at POST /api/v1/checkout_sessions using a secret key (Authorization: Bearer vg_sk_test_...).
  2. The response includes a session.id and an embed_url. Either redirect the customer to that URL or mount the Veyra iframe with the embed snippet.
  3. The customer types card data into a Veyra-hosted iframe — never into your page. The iframe handles 3DS challenges automatically when required.
  4. Your webhook endpoint receives payment.succeeded (or payment_failed) with a Veyragate-Signature HMAC header. Verify the signature, then update your order state.

Public references

Quickstart

Create a checkout session server-side and mount the iframe. Copy-paste examples in Node, Python, and curl.

Verifying webhook signatures

Verify Veyragate-Signature with HMAC-SHA256. Five-minute timestamp tolerance. Snippets in 7 languages.

Errors & idempotency

Error envelope shape, the three top-level error categories, and how Idempotency-Key replays behave.

Test cards

Test PANs and amount triggers for exercising success, decline, and 3DS challenge branches in test mode.

Conventions

  • Authorization: Bearer vg_sk_test_... on every request. Secret keys are server-side only and never appear in browser code.
  • All amounts are integers in the smallest currency unit (cents for USD).
  • POST endpoints accept an optional Idempotency-Key header. Replays with the same key and body return the original response.
  • Outbound webhooks carry a Veyragate-Signature header. The timestamp must be within 5 minutes of the receive time.
  • Test keys (vg_sk_test_...) never touch real funds. Live keys (vg_sk_live_...) are issued after underwriting approval.

Looking for the full endpoint reference?

The endpoint-by-endpoint reference, your API keys, and your webhook signing secret all live in the merchant dashboard. The public docs cover everything you need to evaluate the API before applying.

Apply for a merchant accountSign in (existing merchants)