Elements — endpoint reference

This is the raw HTTP reference for the token-gated endpoints behind Elements and the embeddable Secure Payments checkout. In almost all cases you should use the vezmo-elements.js (or vezmo.js) SDK, which calls these for you — this page is for teams integrating over raw HTTP or debugging.

How these endpoints authenticate

They are not API-key endpoints. Each is scoped by a client token (:token in the path) — the short-lived, single-session clientToken you got back from creating a session server-side with your API key (see Secure Payments → create a session). They are public (no Authorization header) but every call is:

• token-scoped — one session only; the amount, currency and customer are fixed server-side at session create and cannot be changed from here;
• origin-gated — requests must come from one of the merchant's Trusted Origins;
• rate-limited, and (for saved cards) gated by an email OTP and a session-email ownership check.

All responses share the standard envelope { "success": boolean, "message": string, "data": ... }. The fields below describe data.

Start the payment — POST /v1/secure-payments/:token/checkout

Creates (or idempotently returns) the PaymentIntent for the session and returns everything the browser needs to render the field. No request body.

Response (data)

• clientSecret — the PaymentIntent client secret (used by the SDK to mount + confirm).
• publishableKey — the publishable key to initialise the payment library with (matches live/sandbox mode).
• connectedAccountId — the account the charge runs on (the SDK passes it as the merchant account context).
• amount, currency — server-authoritative; fixed at session create.
• livemode — false for sandbox sessions.
• bankSupported — whether bank transfer (ACH) is offered for this session.
• canSaveCard — whether this session may save the card (the session was created with saveCard: true and a customer email).
• theme — the session's default checkout theme (light/dark/auto).
• title, merchantName, customerName, customerEmail, successUrl, cancelUrl, paymentId.

Finalize the payment — POST /v1/secure-payments/:token/confirm

Call this after the payment library confirms the PaymentIntent in the browser. It records the payer's IP and risk signals and finalizes the row. Settlement is authoritative via the webhook, so this never has to succeed for the money to be correct.

Request body

• paymentIntentId (required) — the id of the PaymentIntent that was just confirmed.

Response (data)

• The settled payment (white-label) on success, or a pending/processing shape for asynchronous methods (e.g. ACH), or requiresVerification: true for manual-ACH micro-deposits — then also paymentId, microdepositType (descriptor_code | amounts) and verifyUrl, the branded verify page (the same link the buyer is emailed). In vezmo-elements.js, confirm() resolves that case as status: 'requires_verification' with verification: { type, url }; your server can complete it later with POST /v1/merchant/payment/:id/verify-bank (details).

Saved cards (returning customers)

These power the saved-card flow. A card is only listed for a session whose customer email matches the saved card's network email, and only when a reusable copy exists at this merchant. Charging a saved card requires a fresh email OTP.

List saved cards — GET /v1/secure-payments/:token/saved-cards

Returns the cards reusable for this session. data is an array of:

• savedCardId — opaque id used by the OTP + pay calls below.
• brand, last4, expMonth, expYear — for display.
• maskedEmail — the (masked) email an OTP will be sent to.

An empty array means no reusable saved card — render your normal card field.

Send the OTP — POST /v1/secure-payments/:token/saved-cards/otp/request

Body: { "savedCardId": "..." }. Emails a 6-digit code to the saved email. Returns { "maskedEmail": "ad••@example.com" }.

Verify the OTP — POST /v1/secure-payments/:token/saved-cards/otp/verify

Body: { "savedCardId": "...", "code": "123456" }. Returns { "ok": true }. The code expires in 10 minutes and allows 5 attempts.

Charge the saved card — POST /v1/secure-payments/:token/saved-cards/pay

Body: { "savedCardId": "..." }. Requires a verified OTP within the last 10 minutes. Charges the saved card off-session and returns the settled payment (or a processing shape). Cards usually complete inline; if the issuer demands a fresh challenge the call returns a white-label error and you should fall back to a new card.

Errors

Errors use the same envelope with success: false and a white-label message (no processor names or ids). Common statuses: 401 (invalid/expired token), 403 (origin not allowed, or the saved card isn't for this session, or no verified OTP), 404 (not found), 429 (rate limited).

Webhooks

Payments made through these endpoints settle through the same pipeline as every other VezmoPay charge and emit the same events — payment.processing, payment.success, payment.failed, payment.refunded, the dispute.* events, and payment_method.saved when a customer saves a card. See Webhooks. Always treat the webhook as the source of truth for fulfilment.

For ACH / US bank payments (which settle over several days, not instantly), payment.processing fires as soon as the debit is initiated so you can record it as pending in real time, and payment.success is the later settlement signal to fulfil on. See Payments & the ACH lifecycle.