ePayVista · API Reference

Everything the API does,
and exactly what it returns.

One page. Every endpoint, every field, every error code, the full payment lifecycle and the signed-webhook contract — each one checked against the running engine, not against a design document. Sandbox credentials are self-serve and take one request. You should never need to email anyone to finish an integration.

1 · Overview

ePayVista turns a USD order amount into a stablecoin payment. You POST an amount; the API returns a reference and a hosted checkout URL. The buyer sends stablecoin to a deposit address that belongs to that order alone. The engine watches the chain, confirms the deposit, pays out to your payout wallet, and POSTs you a signed webhook. You mark the order paid.

There is no card vault, no chargeback window and no settlement delay beyond block confirmations. A percentage fee is deducted from the settled order; the remainder is sent to your payout wallet.

Base URLs

Every path in this reference is relative to one of those two. POST /api/v1/payment means https://pay.epayvista.com/api/v1/payment on live and https://pay.epayvista.com/sandbox/api/v1/payment on sandbox. The request shapes, the auth header, the response fields, the error codes and the webhook signature scheme are identical in both. Only the base URL, the key and the chains change.

Live vs sandbox — the complete list of differences

Getting credentials

Live. Live keys are issued instantly from the merchant portal under Developer — there is no onboarding gate, no review queue and nothing to wait for. A live key is never emailed and is stored encrypted server-side.

Sandbox. One unauthenticated request, no account, no call:

curl -X POST https://pay.epayvista.com/sandbox/keys \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","storeUrl":"https://yourstore.com"}'

Full field list and response in §3 · POST /sandbox/keys.

2 · Authentication

One header, one value:

API-Key: <the key shown in the merchant portal under Developer>

The header name is matched case-insensitively (API-Key and api-key both work). There is no bearer scheme, no signature on requests, no timestamp, no nonce. The key is the whole credential, so it must never reach a browser, a mobile app, or a public repository.

Which endpoints need a key

Reference reads are scoped to the account that created them

Sending your API-Key on a reference read confines the read to your own account. A reference that is not yours answers 404 — never 403 — so an authenticated stranger cannot enumerate or inspect another merchant's orders, and cannot tell a reference outside their account from one that does not exist. A key never widens access here; it only narrows it.

Reads without a key stay possible because the hosted checkout page is client-rendered and fetches the reference from the buyer's browser with no credential — for a buyer, the reference UUID is the bearer. That response contains only what the buyer is already being shown: amount, deposit address, chain and state.

Verified against the sandbox: an anonymous read and a keyed read of the same reference both returned 200 with byte-identical bodies; a read with API-Key: epv_sbx_nope returned 401.

Key hygiene

• Server-side only. Anything the key can do, whoever holds it can do — including changing the payout wallet future settlements go to.
• Never in a browser. If your checkout needs live payment state, poll GET /api/status/:ref or GET /api/v1/payment/reference/:ref without a key. Both are designed for exactly that.
• Environment-separated. A sandbox key always starts epv_sbx_, so a sandbox key that has leaked into a live config is visible in a .env at a glance. Live keys have no single fixed shape — copy yours from the portal rather than pattern-matching it. A sandbox key on the live base URL returns 401 invalid_api_key, and vice versa — they are different databases.
• Rotation. There is no self-serve rotate endpoint. Email [email protected] and a new key is issued; the old one is deactivated at the same time.
• The callback secret is a separate credential and is not interchangeable with the API key. Changing your callback URL never changes the secret.

3 · Endpoints

Every example below was run against the sandbox. Keys, references, addresses and transaction hashes in the examples are placeholders — they are shaped like the real thing but are not real values. Substitute https://pay.epayvista.com for the base URL and your live key from the merchant portal to run the same calls on live.

Create a payment session. This is the only endpoint that mints a deposit address, and the only one you strictly need.

Request body

Amounts. Send 12.34 or "12.34" — both work. The engine formats to two decimal places and converts to atomic units using the token's decimals (6 for every currently enabled rail). Never send a value with more than 2 decimal places of meaning: the third and beyond are discarded, and the buyer is quoted the rounded figure. Every amount returned by the API is a 2-decimal-place string, never a float.

Request

curl -X POST https://pay.epayvista.com/sandbox/api/v1/payment \
  -H "API-Key: $EPV_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerID":     "doc_order_1",
    "customerEmail":  "[email protected]",
    "amountInUSD":    12.34,
    "returnUrl":      "https://example.com/thanks",
    "cancelUrl":      "https://example.com/cart",
    "orderSummary":   "Order doc_order_1 x1",
    "blockchainCode": "base",
    "currencyCode":   "TUSDC"
  }'

200 — captured response

{
  "url": "https://pay.epayvista.com/sandbox/pay/11111111-2222-4333-8444-555555555555",
  "reference_id": "11111111-2222-4333-8444-555555555555"
}

That is the entire success body. reference_id is a UUID v4 — store it on your order, it is what every later read and the webhook are keyed on. url is the hosted checkout page; send the buyer there. The deposit address is not in this response; read it from GET /api/v1/payment/reference/:ref if you are building your own payment UI.

Errors

Captured error responses

# no key
HTTP 401  {"error":"api_key_required","message":"Send your API key in the API-Key header.
           You can find it in the merchant portal under Developer."}

# {"amountInUSD":"abc"}
HTTP 400  {"error":"invalid_amount","message":"The amount must be a number greater than zero,
           written in dollars — for example 12.50."}

# {"amountInUSD":0.04}
HTTP 400  {"error":"amount_too_small","message":"That amount is too small for us to settle.
           Raise the order amount and try again."}

# {"amountInUSD":10,"blockchainCode":"polygon","currencyCode":"TUSDC"}
HTTP 400  {"error":"unsupported_rail","chain":"polygon","currency":"TUSDC",
           "message":"We do not support that network and coin together.
           Call GET /api/rails to see the combinations you can use."}

# malformed JSON
HTTP 400  {"error":"bad_json","message":"We could not read that request body — it is not valid
           JSON. Check the payload and the Content-Type header.","reference":"1a2b3c4d"}

# 70 kB body
HTTP 413  {"error":"payload_too_large","message":"That request body is too large.
           Keep it under 64 kB.","reference":"5e6f7a8b"}

The full session read. This is what you poll, and what the hosted checkout reads from the buyer's browser. Auth behaviour is described in §2.

Before answering, an OPEN session gets one short, read-only on-chain balance check, so a deposit that has landed but has not yet been through the settlement tick is often reported as paid a few seconds early. That check never mutates anything and fails open.

curl https://pay.epayvista.com/sandbox/api/v1/payment/reference/$REF

200 — captured, session OPEN

{
  "linkExpired": false,
  "paymentState": "OPEN",
  "amountInUSD": "12.34",
  "confirmationRequired": 1,
  "confirmationCurrent": 0,
  "filledAmount": null,
  "explorerTransaction": null,
  "successURL": "https://example.com/thanks",
  "cancelURL": "https://example.com/cart",
  "invoiceID": "11111111-2222-4333-8444-555555555555",
  "referenceID": "11111111-2222-4333-8444-555555555555",
  "address": "0x1111111111111111111111111111111111111111",
  "blockchainCode": "BASE",
  "currencyCode": "TUSDC",
  "chainId": 84532,
  "url": "https://pay.epayvista.com/sandbox/pay/11111111-2222-4333-8444-555555555555"
}

200 — captured, same session after settlement

{
  "linkExpired": false,
  "paymentState": "FILLED",
  "amountInUSD": "3.50",
  "confirmationRequired": 1,
  "confirmationCurrent": 1,
  "filledAmount": "3.50",
  "explorerTransaction": "https://sepolia.basescan.org/tx/0xb2519bb6...537701",
  ...
}

Response fields

Errors

The minimal poll. Three fields, no on-chain call, no passthrough. This is the right endpoint for a status widget or a background job that only needs paid / not paid.

curl https://pay.epayvista.com/sandbox/api/status/$REF

# => HTTP 200, captured while open
{ "status": "OPEN", "paid": false, "reference_id": "11111111-…" }

# => HTTP 200, captured after settlement
{ "status": "PAID", "paid": true, "reference_id": "99999999-…" }

# => HTTP 404, unknown reference
{ "error": "not_found", "message": "We could not find that. If you sent an API key, note that
  a payment can only be read by the account that created it." }

Poll this, do not hammer it. The settlement loop ticks every 15 seconds, so polling faster than that tells you nothing new. Webhooks are the primary signal; polling is the fallback.

What the hosted checkout page calls

The hosted checkout page calls a few additional read-only endpoints on the customer's behalf — the payment-method list, the per-network deposit-address rows, the branding header and a currency helper. They are not part of the merchant integration surface, they are not documented here, and they may change without notice. Everything you need to take a payment and confirm it is on this page: create the session, read it back, and receive the webhook.

Every (chain, currency) pair this environment will actually accept, with its minimum. This is the source of truth for blockchainCode and currencyCode — build your network picker from it rather than hard-coding a list, and use it as a health probe.

The list is filtered live: a rail that is temporarily unavailable is absent, not listed-and-broken. So an empty or short list is meaningful information, not an error.

curl https://pay.epayvista.com/api/rails

# => HTTP 200 — LIVE, captured
{"rails":[
 {"chain":"base",    "chainId":8453,"chainName":"Base",    "currency":"USDC", "minOrderUsd":5, "decimals":6},
 {"chain":"polygon", "chainId":137, "chainName":"Polygon", "currency":"USDC", "minOrderUsd":5, "decimals":6},
 {"chain":"polygon", "chainId":137, "chainName":"Polygon", "currency":"USDT", "minOrderUsd":5, "decimals":6},
 {"chain":"ethereum","chainId":1,   "chainName":"Ethereum","currency":"USDC", "minOrderUsd":20,"decimals":6},
 {"chain":"ethereum","chainId":1,   "chainName":"Ethereum","currency":"PYUSD","minOrderUsd":20,"decimals":6}
]}

# => HTTP 200 — SANDBOX, captured
{"rails":[
 {"chain":"base",    "chainId":84532,   "chainName":"Base Sepolia",    "currency":"USDC", "minOrderUsd":0,"decimals":6},
 {"chain":"polygon", "chainId":80002,   "chainName":"Polygon Amoy",    "currency":"USDC", "minOrderUsd":0,"decimals":6},
 {"chain":"ethereum","chainId":11155111,"chainName":"Ethereum Sepolia","currency":"USDC", "minOrderUsd":0,"decimals":6},
 {"chain":"base",    "chainId":84532,   "chainName":"Base Sepolia",    "currency":"TUSDC","minOrderUsd":0,"decimals":6},
 {"chain":"ethereum","chainId":11155111,"chainName":"Ethereum Sepolia","currency":"TUSDC","minOrderUsd":0,"decimals":6}
]}

No error responses: this endpoint takes no input.

Set or re-assert where paid-webhooks are delivered. Your signing secret is not changed by this call — it changes where we deliver, never the key the receiver verifies with.

curl -X POST https://pay.epayvista.com/sandbox/api/v1/merchant/callback \
  -H "API-Key: $EPV_KEY" -H 'Content-Type: application/json' \
  -d '{"callback_url":"https://example.com/hooks/epv"}'

# => HTTP 200 (captured, first time)
{ "ok": true, "callback_url": "https://example.com/hooks/epv", "changed": true }

# => HTTP 200 (captured, same URL again — idempotent)
{ "ok": true, "callback_url": "https://example.com/hooks/epv", "changed": false }

Callback URL validation rules

This is a server-side POST target, so it is gated hard. All of the following are rejected with 400 invalid_callback_url — each verified:

All of these return the same code and the same message, so you cannot tell which rule you hit from the response — check the URL against the list above.

Calling this endpoint also resumes deliveries that were paused because your callback had stopped answering: anything undelivered is re-queued and sent on the next settlement tick. See §5.

Change your display name, your payout wallet, or your paid-notice email preference. All three fields are optional; omitted fields are left untouched. At least one must be present.

curl -X POST https://pay.epayvista.com/sandbox/api/v1/merchant/profile \
  -H "API-Key: $EPV_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Acme Widgets","notifyPaid":false}'

# => HTTP 200 (captured)
{ "id": 1234, "name": "Acme Widgets",
  "payout_address": "0x9041da1e1515d427B38858C83162778DD923CbdC",  // a fresh sandbox address unless you sent one
  "active": true, "notify_paid": 0 }

Payout-address safety

curl -X POST https://pay.epayvista.com/sandbox/api/v1/merchant/profile \
  -H "API-Key: $EPV_KEY" -H 'Content-Type: application/json' \
  -d '{"payoutAddress":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}'

# => HTTP 400 (captured)
{ "error": "invalid_payout_address",
  "reason": "token_contract",
  "message": "That is the address of a token contract, not a wallet. Money sent there cannot be recovered. Enter the wallet address where you want to be paid." }

The same check runs on every surface that can set your payout wallet, so an address refused here is refused in the merchant portal and in the WooCommerce plugin too.

Set the logo shown on the hosted checkout header. Pass an empty string to clear it.

curl -X POST https://pay.epayvista.com/sandbox/api/v1/merchant/logo \
  -H "API-Key: $EPV_KEY" -H 'Content-Type: application/json' \
  -d '{"logo_url":"https://cdn.example.com/logo.png"}'

# => HTTP 200 (captured)
{ "ok": true, "logo_url": "https://cdn.example.com/logo.png" }

# => HTTP 200 (captured, cleared with "")
{ "ok": true, "logo_url": "" }

Note that http:// is refused here even though it is accepted for the callback URL. The logo is loaded in the buyer's browser, so it must be https.

Chrome extension and AI-agent (MCP) links

The Chrome extension and the AI-agent (MCP) endpoint create links the same way; use them or the API, not both.

Self-serve sandbox credentials. No account, no email confirmation, no call. This endpoint exists only under /sandbox; there is no live equivalent.

curl -X POST https://pay.epayvista.com/sandbox/keys \
  -H 'Content-Type: application/json' \
  -d '{
    "email":    "[email protected]",
    "storeUrl": "https://yourstore.com",
    "name":     "Acme Widgets"
  }'

200 — captured (secrets elided)

{
  "sandbox": true,
  "network": "base-sepolia",
  "chain_id": 84532,
  "base_url": "https://pay.epayvista.com/sandbox",
  "auth_header": "API-Key",
  "merchant_id": 1234,
  "api_key": "epv_sbx_…",              // 56 chars: prefix + 48 hex
  "callback_secret": "…",             // 64 hex chars — shown ONCE
  "callback_url": "https://sandbox-callbacks.epayvista.com/discard",
  "payout_address": "0x9041da1e1515d427B38858C83162778DD923CbdC",
  "docs": "https://pay.epayvista.com/sandbox",
  "notice": "Test funds only (Base Sepolia). This key cannot process live payments."
}

The callback_secret is shown once and is not recoverable. Save it before you close the terminal; if you lose it, issue a new sandbox key.

A GET on the same URL returns this documentation page, not JSON.

Mints tUSDC — "ePayVista Test USD", our own testnet ERC-20 — to any address you name, and returns the transaction hash. Its mint() is unrestricted, so the dispenser cannot run dry and you never have to hunt a public faucet to finish a test.

This route refuses to mount at all on a mainnet engine. There is no live equivalent and there cannot be one.

curl -X POST https://pay.epayvista.com/sandbox/api/v1/faucet \
  -H 'Content-Type: application/json' \
  -d '{"address":"0xYourTestWallet","chain":"base","amount":250}'

200 — captured

{
  "ok": true,
  "sandbox": true,
  "chain": "base",
  "chain_id": 84532,
  "chain_name": "Base Sepolia",
  "token": "tUSDC",
  "token_contract": "0x3764Fac8d919a905EA0Dae18d65fCe5D40e21000",
  "decimals": 6,
  "to": "0x2222222222222222222222222222222222222222",
  "amount": "3.5",
  "amount_units": "3500000",
  "tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "confirmed",
  "explorer_url": "https://sepolia.basescan.org/tx/0xaaaaaaaa…aaaaaa",
  "notice": "Test tokens with no value. Sandbox only."
}

status is confirmed once mined, or pending if it is still in the mempool after 60 seconds — the hash is valid either way.

Every faucet response — success and failure alike — carries an ok boolean alongside error/message. That extra field is unique to this endpoint.

A GET on the same URL returns a machine-readable summary of the limits and supported chains, which is handy in a smoke test:

curl https://pay.epayvista.com/sandbox/api/v1/faucet

# => HTTP 200 (captured)
{ "ok": true, "endpoint": "POST /sandbox/api/v1/faucet",
  "body": { "address": "0x... (required)", "chain": ["base","ethereum"],
            "amount": "optional, default 100, max 10000" },
  "token": "tUSDC (ePayVista Test USD, 6 decimals)",
  "limits": { "per_ip_per_hour": 10, "global_per_hour": 200, "max_amount": 10000 },
  "chains": ["base","ethereum"] }

Hosted checkout URLs and their query parameters

Two URLs render a checkout. Both take the reference; both accept exactly one query parameter that changes what the buyer sees.

reference_id

On /payments this must match a canonical UUID v4 exactly. Anything else returns 404 with a branded "we could not find this payment" page — verified. The same page is returned by /pay/:ref for an unknown reference.

show

A comma-separated list that filters the payment-method tiles. Case-insensitive.

Omit show entirely and every tile renders — that is the all-in-one checkout and it is the right default. Send show with only card values and the crypto sections are hidden; send only crypto values and the card tile is hidden. Sending show=coinbase alone matches neither group and hides both, which is almost certainly not what you want — pass it alongside a value the page recognises, or leave show off. The card tile additionally requires a USDC order of at least $2 on Base or Polygon; below that it never renders, whatever show says.

On this sandbox /payments?reference_id=…&show=wallet answers 302 to /sandbox/pay/<ref>?show=wallet — captured. On live it renders the multi-rail shell directly. Either way, use the url the create call returned rather than constructing one; it is already correct for the environment.

4 · Payment lifecycle

There are two vocabularies for one lifecycle, and they never converge:

Internal statuses

These are the values the engine stores. GET /api/status/:ref surfaces them verbatim when the order is not yet paid, so you may observe them.

Transitions and timings

  create
    │
    ▼
  OPEN ──── no deposit, 4 h ────────▶ EXPIRED ──── 7 d ────▶ dead link
    │                                      │              (linkExpired: true)
    │  deposit ≥ threshold                 │  late deposit re-opens it
    │  + chain confirmations               │
    ▼                                      ▼
  PAID ──── paid out to your wallet ────────▶ deliver webhook
    │                                              │
    │                             2xx ─────────────┴──────▶ CLOSED   (terminal)
    │                             non-2xx / 3xx / timeout
    │                                              │
    └──────────────────────────────────────▶ NOTIFIED ──▶ … ──▶ WEBHOOK_FAILED
                                                              (hourly retry, 7 days)

linkExpired and dead links

linkExpired: true means the session is unpaid and no longer payable on any rail. When it is true the hosted checkout will not render a deposit address for it, and any attempt to open a new rail on that order is refused. Show your customer an "expired — start checkout again" state and issue a fresh session. Never invite a payment to a dead link's address.

Underpayment

The threshold that counts as paid is the quoted amount minus a tolerance, and the tolerance is the larger of a flat $0.05 and 5% of the order.

Your integration should therefore treat a session that stays OPEN after a plausible payment window as "possibly underpaid", not as "unpaid". There is no partial-payment webhook and no partial-payment field in the read API.

Overpayment

An overpayment settles the order normally — the threshold is a floor, not a range — and the full received amount is swept to your payout wallet. A receipt of 1.5× the quote or more is flagged internally as a probable double payment and looked at by a person, because that is usually a customer who paid twice and is owed a refund. Nothing is deducted or withheld automatically; the refund decision is yours.

explorerTransaction

Built from the settling chain's own explorer and the deposit transaction hash, so the read API and the webhook's explorer_url can never disagree about a transaction. Live: basescan.org, polygonscan.com, etherscan.io. Sandbox: sepolia.basescan.org, amoy.polygonscan.com, sepolia.etherscan.io. It is null until settlement, and stays null for a balance-proof settlement.

Verified end to end

The following was run against the sandbox while writing this page. Times are from the captured log.

# 1. create a $3.50 TUSDC session on Base Sepolia
POST /sandbox/api/v1/payment  →  { "reference_id": "99999999-…",
                                   "url": "…/sandbox/pay/99999999-…" }
GET  …/payment/reference/…    →  address 0x2222222222222222222222222222222222222222

# 2. mint exactly 3.5 tUSDC to that address
POST /sandbox/api/v1/faucet   →  tx 0xaaaaaaaa…aaaaaa  status "confirmed"

# 3. t + ~15 s — first poll after the mint
GET  /sandbox/api/status/…    →  { "status":"PAID", "paid":true }
GET  …/payment/reference/…    →  paymentState "FILLED", confirmationCurrent 1,
                                 filledAmount "3.50",
                                 explorerTransaction "https://sepolia.basescan.org/tx/0xb2519bb6…"

# 4. t + ~45 s — signed webhook delivered, accepted on the first attempt
POST https://example.com/hooks/epv
     → { "reference_id":"99999999-…", "status":"CLOSED", "amount_in_usd":"3.50",
         "blockchain_code":"BASE", "confirmations":2, … }   listener answered 200

Detection, confirmation, payout and webhook delivery completed inside a minute on Base Sepolia, on the first delivery attempt.

5 · Webhooks

One webhook exists: the order was paid. There is no webhook for creation, expiry, underpayment, refund, or any other event. If you need those, poll /api/status/:ref.

Registration

Your callback URL and signing secret are issued together with your API key. Change the URL — and only the URL — with POST /api/v1/merchant/callback. The secret is never changed by that call and there is no self-serve way to rotate it; email [email protected].

Validation rules for the URL are listed in full under that endpoint: http(s) only, a real public domain that resolves, no private or loopback hosts, 300 characters maximum.

Delivery

POST <your callback_url>
Content-Type: application/json
X-EPV-Signature: <64 lowercase hex characters>

{ …the body below… }

We expect a 2xx. Anything else is a failure, and that explicitly includes redirects: a 3xx is never followed and never counts as a delivery. (A 307 or 308 preserves method and body, so following one would deliver a signed POST wherever the response pointed — the URL validation would be worthless.) Answer 200 quickly and do your work afterwards; the delivery timeout is 8 seconds.

Body schema

Exactly seven fields, in this order. Nothing is ever added or omitted.

A real captured webhook

Delivered to a listener during the end-to-end run in §4. This is the verbatim body and the verbatim header:

X-EPV-Signature: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
Content-Type: application/json
content-length: 331

{"reference_id":"99999999-8888-4777-8666-555555555555","status":"CLOSED","txid":
"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","amount_in_usd":
"3.50","blockchain_code":"BASE","confirmations":2,"explorer_url":
"https://sepolia.basescan.org/tx/0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}

(Line breaks added here for the page — the real body is a single line with no whitespace.)

Signature

X-EPV-Signature = hex( HMAC_SHA256( raw request body bytes, callback_secret ) )

Node / Express

Verified against the captured webhook above: returned true. With "3.50" altered to "9.99" in the body, it returned false.

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/hooks/epayvista',
  express.raw({ type: 'application/json' }),        // keep the RAW bytes
  (req, res) => {
    const expected = crypto
      .createHmac('sha256', process.env.EPV_CALLBACK_SECRET)
      .update(req.body)                             // req.body is a Buffer here
      .digest('hex');
    const got = String(req.get('X-EPV-Signature') || '');

    const a = Buffer.from(got), b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }

    const event = JSON.parse(req.body.toString('utf8'));
    // mark the order paid, idempotently — see below
    res.sendStatus(200);
  });

Python / Flask

Verified against the same captured webhook: returned True; tampered body False.

import hashlib, hmac, os, json
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ['EPV_CALLBACK_SECRET'].encode()

@app.post('/hooks/epayvista')
def epayvista_hook():
    raw = request.get_data()                        # the RAW bytes, unparsed
    got = request.headers.get('X-EPV-Signature', '')
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(got, expected):
        abort(401)

    event = json.loads(raw)
    # mark the order paid, idempotently
    return '', 200

PHP

Verified against the same captured webhook on PHP 8.2: hash_equals returned true.

<?php
$raw = file_get_contents('php://input');            // the RAW bytes, unparsed
$got = $_SERVER['HTTP_X_EPV_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, getenv('EPV_CALLBACK_SECRET'));

if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
// mark the order paid, idempotently
http_response_code(200);

In WordPress, read the raw body the same way — $request->get_body() inside a REST route, never $request->get_json_params() re-encoded.

Idempotency

Assume every webhook will arrive more than once. Retries are normal, and a delivery your server processed but answered slowly is retried anyway. Make the handler idempotent:

• Key on reference_id. It is stable across every retry of one order.
• Check the order's current state before acting. If it is already paid, answer 200 and do nothing else.
• Do the state change in one transaction, or behind a unique constraint on reference_id.
• Answer 200 even for a duplicate — a non-2xx makes us retry a webhook you have already handled.
• Do not use txid as the key: it is "" or an internal sentinel for a balance-proof settlement.

Retry schedule

If your callback stops answering

WordPress routes. If your callback URL is a WordPress route (it contains /wp-json/ or ?rest_route=) and it returns 404, we treat that as the plugin having been switched off rather than as a broken site: deliveries for your account are paused instead of burning retries. They resume automatically when the route answers again, and immediately when you call POST /api/v1/merchant/callback — which is why "reactivate the plugin, then save its settings" clears a backlog of missing orders in one step.

Every other callback simply retries on the schedule above: up to 30 attempts, then once an hour for 7 days.

Nothing is lost either way. The money was paid out before the first delivery attempt; only the notification is delayed.

The practical consequence: "the money arrived but my store still shows the order unpaid" is, almost every time, a deactivated plugin. See the FAQ.

6 · Errors

Every JSON error from every endpoint has the same two keys:

{
  "error":   "amount_below_minimum",   // stable machine code — BRANCH ON THIS
  "message": "The minimum order is $20.00 on this network. Raise the amount
              or choose another network."   // plain English — SHOW THIS, never branch on it
}

error is a contract and never changes. Codes are only ever added, never renamed or repurposed, so branching on them is safe across releases. message is for humans — your logs, your admin screen, your support ticket. The wording is revised whenever it can be made clearer, so a client that matches on message text will break.

Some errors carry extra context keys alongside the two — minimum_usd, chain, currency, gas_usd, min_amount_usd, scope, max. They are additive; ignore any you do not recognise.

5xx responses

{
  "error": "server_error",
  "message": "Something went wrong on our side while handling this request. No money
              has moved. Try again in a moment — if it keeps happening, email
              [email protected] with the time and the reference.
              Quote reference 9c0d1e2f if you contact us.",
  "reference": "9c0d1e2f"
}

The extra reference is an 8-character id for that one failure. Quote it and we can find the exact failure. Every 5xx is recorded on our side automatically, so you do not have to report it for us to know — but the reference is what makes it findable. A 4xx is not recorded that way: a wrong key or an under-minimum amount is a client error that already explains itself. bad_json (400) and payload_too_large (413) also carry a reference.

Two shapes that are not this

• The unknown-reference answer. An unknown reference on /payment/reference/:ref returns 401 {"error":{"code":"UNAUTHORIZED","message":"Unauthorised access!"}} — a nested object, not two strings. Guard your parser: check typeof body.error === 'string' before using it as a code.
• Unmatched routes. A method or path the engine does not serve returns an HTML 404 from the framework, not JSON. Verified: DELETE /api/rails → 404, Cannot DELETE /api/rails as HTML. Do not assume every response is parseable JSON; branch on the status code and the content type first.

Complete error-code table

Every code the engine can return, its HTTP status, and the exact message text.

Authentication and account

The payment request

Merchant profile and settings

Transport and our side

Codes with no plain-English message

These are returned as a bare {"error": "..."} — no message key. Verified; handle a missing message gracefully everywhere.

How to handle errors, in one rule

if (res.status >= 500) {
  // our fault. Retry with backoff. No money has moved.
  // Log body.reference — it is how we find your exact failure.
} else if (res.status === 429) {
  // back off and retry.
} else if (res.status >= 400) {
  // PERMANENT client error. Do NOT retry the identical request.
  // Branch on body.error. Show body.message to a human.
}

The one trap: 401 api_key_required is permanent, not transient. A missing header will never fix itself, so a retry-with-backoff loop on it runs forever and never surfaces the misconfiguration.

7 · Rails & limits

A rail is one (chain, currency) pair. It is the unit everything else is parameterised by: the deposit address, the confirmation depth, the minimum, the explorer and the payout are all per-rail. Read the live list from GET /api/rails rather than hard-coding these tables — a rail that is temporarily unavailable disappears from that endpoint, and this page cannot.

Live rails

Captured from GET https://pay.epayvista.com/api/rails. Every enabled rail is a 1:1-USD stablecoin with 6 decimals, so a USD amount converts to token units with no price feed and no rounding surprise.

Sandbox rails

The USDC rails are Circle's official testnet deployments, kept exactly as they are so what you test against matches the real contract.

tUSDC — the dispensable test token

tUSDC uses 6 decimals deliberately, exactly like USDC, so every amount calculation your integration performs is the same code path it will run on a live rail. Its mint() is unrestricted and the faucet dispenses from it, so it cannot run dry. It is a valueless test token and exists nowhere but the sandbox.

There is no tUSDC on Polygon Amoy, and there will not be while the caveat below holds.

Minimums — why they exist and where they bite

The merchant pays the network fee. Settling an order costs gas on the chain it settles on, and that cost comes out of the merchant's side of the order — which is exactly why Ethereum's floor is $20 and Base's and Polygon's are $5. On top of the static floor, live orders also pass a gas-economics check at creation: an order that current network fees would make uneconomic is refused with gas_uneconomic_for_amount rather than settled at a loss. The practical consequence is that the effective Ethereum minimum can rise above $20 during a fee spike. Read min_amount_usd from the error body and surface it to your customer.

Rate limits

The core payment API is not rate limited. POST /api/v1/payment, the reference reads, /api/status, /api/rails and the merchant self-serve endpoints carry no quota. Be reasonable — polling faster than the 15-second settlement tick gains you nothing — but you will not be throttled for normal integration traffic.

8 · Going live

The request shapes, the auth header, the response fields, the error codes and the signature scheme are identical between sandbox and live. In principle the only things that change are the base URL and the key.

Getting the live key takes one visit to the portal. Sign in, open Developer, and your live key and callback secret are there immediately — there is no onboarding gate, no review queue, no call and nobody to email. In practice, check these before you switch:

FAQ

Where does my money actually go?

To the payout wallet on your account, minus the fee, sent from the order's own deposit address once the deposit confirms. Set it with POST /api/v1/merchant/profile and read the value back from the response. You hold the keys to that wallet; ePayVista never custodies your funds beyond the moments between confirmation and payout.

I changed my payout wallet. What happens to orders already open?

They settle to the old address. Every session snapshots its destination at creation and settlement reads that snapshot, so a wallet change applies only to sessions created afterwards. This is deliberate — it is what stops a stolen key redirecting a checkout that is already in flight. If you need an in-flight order redirected, email us.

How do I change my callback URL?

POST /api/v1/merchant/callback with your API key. The URL must be a public http(s) host that resolves; loopback and private ranges are refused. Your signing secret does not change. As a side effect, the call clears any parked-webhook state and re-queues undelivered webhooks.

How do I rotate my API key or callback secret?

There is no self-serve rotation for either. Email [email protected] and a new credential is issued with the old one deactivated at the same time. Plan a short window where both may be in play and make sure your webhook handler can accept a signature from either secret across the switch.

The money arrived but my store still shows the order unpaid.

Almost always a deactivated plugin. Your funds were swept and paid out before the first delivery attempt — that part completed. What failed is the notification: your callback answered 404 twice in a row, so the engine parked your webhooks rather than burning retries against a route that no longer exists.

The fix, in order:

1. Reactivate the ePayVista plugin on your store.
2. Open its settings and save them — that calls /merchant/callback, which clears the parked state and re-queues every parked webhook for the next tick.
3. If you are not on a plugin, call /merchant/callback yourself with the correct URL. Same effect.

If nothing arrives within a few minutes after that, check that the URL is publicly reachable and answers 2xx to a POST, then email us with the reference_id. Confirm with GET /api/status/:ref: if it says paid: true, the money is with you and only the notification is outstanding.

Can I use a sandbox key on live, or the other way round?

No. They are separate databases. A sandbox key on the live base URL, or a live key on the sandbox base URL, returns 401 invalid_api_key. Every sandbox key is prefixed epv_sbx_ precisely so that mistake is visible in a config file at a glance; live keys are not prefix-guaranteed, so keep the two in clearly named variables.

Am I going to get rate limited?

Not on the core payment API — it carries no quota. The only limits that apply to you are on the two sandbox-only endpoints: sandbox key issuance and the tUSDC faucet. See §7. If you are polling, one request per session per 15 seconds is the most that can tell you anything new.

Where do I get testnet gas and testnet USDC?

For tUSDC, nowhere — use our faucet, and if you mint straight to the deposit address you do not need gas at all. For the Circle USDC rails and for the native gas you need to send your own transfer:

Testnet gas is the developer's responsibility — our faucet mints tUSDC and nothing else. Public gas faucets rate-limit, sometimes ask for a mainnet balance, and are sometimes simply down, which is the whole reason tUSDC exists: mint the exact order amount straight to the deposit address and you need no gas at all.

Is there a webhook for anything other than "paid"?

No. Creation, expiry, underpayment and refunds have no webhook. Poll /api/status/:ref for those, and read §4 for what an order that stays OPEN might mean.

Can I take a payment without using the hosted checkout?

Yes. Create the session, read address, amountInUSD, currencyCode and chainId from /payment/reference/:ref, and render those yourself. Poll /api/status/:ref from the browser without a key. Everything the hosted page does, those two endpoints expose.

9 · Changelog