Your first payment, end to end.

One API. Two isolated environments.#

Request an activated merchant account and a sandbox API key. In Dashboard → Settings → Webhook, select Sandbox, enter your HTTPS receiver URL, and securely store the one-time signing secret. You can configure, rotate, and disable your own webhook; sandbox and live defaults are separate. In Dashboard → API Keys → Key settings, each key can inherit its environment’s merchant default, use a custom receiver with its own signing secret, or disable delivery for that key. The key fixes the environment. Default changes do not replace custom key receivers. Configure delivery before creating payments.

export WEGOPAY_API_BASE_URL="https://api.wegopay.tech"
# Load WEGOPAY_SANDBOX_API_KEY from your secret manager.
# For retrieve/list examples, use the matching key:
export WEGOPAY_API_KEY="$WEGOPAY_SANDBOX_API_KEY"

Try a sandbox payment#

Create a $5.00 USD payment (amountCents: 500) with your wgp_test_… key, open the returned checkout URL, and choose Pay by card. Choose the scenario below and enter its synthetic card number in the secure card form. Use card holder TEST TEST, expiry 12/2030 and CVV 123 for either card.

For merchant token payments, submit these card details directly to PCI Vault from your backend. Send only the returned token and reference to Wegopay. See token submission and customer actions.

Card number: 4111 1111 1111 1111
Card holder: TEST TEST
Expiry: 12/2030
CVV: 123

After checkout, retrieve the payment and confirm status: paid, environment: sandbox, and the expected amount, currency, and reference. For 3DS, complete the challenge; merchant token integrations must open the returned action URL in the customer browser without collecting the card again. Challenge completion or a success redirect alone is not proof of payment. Verify signed webhook delivery separately. Request matching approved fixtures from Wegopay for declines or failed/canceled challenges.

Wallet availability depends on the provider page and the device, browser, and wallet setup. The merchant API has no operation to force a transaction status. Device-free wallet completion requires a provider-approved test procedure that Wegopay must confirm; a sandbox key alone does not bypass wallet availability checks. Sandbox results do not establish live wallet acceptance, issuer approvals, settlement, or production fraud and risk behavior.

Your card form. Payment-scoped capture.#

Your backend collects the card and sends it directly to PCI Vault. Wegopay receives only an opaque token and capture reference. Your customer may still need a browser to complete 3D Secure (3DS). The merchant API key, capture secret and token stay on your backend.

How merchants and payments are separated

Your API key identifies your merchant and selects sandbox or live. Wegopay checks that the payment belongs to both before allowing capture or payment submission. Each new custom payment has its own server-owned vault encryption key and random capture reference. Wegopay revokes capture access and checks the submitted token through an authenticated, metadata-only lookup within that payment's key. A matching reference alone does not prove ownership. Tokens from another merchant, payment or environment cannot be substituted. Amount and payment routing come from the stored payment.

You receive a capture-only secret. Wegopay keeps vault account credentials, encryption-key passphrases and payment credentials private. Access expires at most ten minutes after payment creation, or at checkout expiry if earlier; read the returned expiresAt. Access is also revoked when the token is bound. There is one card binding per payment, without saved-card reuse, recurring payments or permanent shared capture credentials.

Create, prepare, then capture at PCI Vault#

Create through POST /v1/payments using the normal order fields and a persisted Idempotency-Key, adding "checkoutMode": "custom". Custom mode returns 422 until configured for your merchant and environment. Save the returned data.id against the order before continuing.

// Run on your backend. Load the matching merchant key from your secret manager.
const response = await fetch(apiBase + '/v1/payments/' + paymentId + '/capture', {
  method: 'POST', // No request body.
  headers: { Authorization: 'Bearer ' + apiKey },
  redirect: 'error',
});
if (!response.ok) throw new Error('Capture preparation unavailable');
const prepared = (await response.json()).data;
// prepared.capture: { url, secret, reference, expiresAt }
// prepared.actionUrl: browser continuation URL; keep private until needed.
// Never print this response or return capture credentials to a browser.

Preparation performs no charge. Retry preparation for the same payment; completed preparation returns the existing access, rather than extending its lifetime. If provisioning has an uncertain result, access stays fenced and may require Wegopay support.

// This request goes to PCI Vault, NOT the Wegopay API.
// Validate capture.url against the exact vault origin approved for your environment.
// Use the downloadable example for origin, path, expiry and response checks.
const response = await fetch(prepared.capture.url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PCIVault-Capture-Secret': prepared.capture.secret,
  },
  body: JSON.stringify({
    card_number: card.number,
    card_cvv: card.cvv,
    card_expiry_month: card.month, // Two-digit string: MM
    card_expiry_year: card.year,   // Two-digit string: YY, not YYYY
  }),
  redirect: 'error',
});
if (!response.ok) throw new Error('Card capture rejected');
const captured = await response.json();
if (captured.reference !== prepared.capture.reference) {
  throw new Error('Capture binding mismatch');
}
// Durably store only captured.token and captured.reference, encrypted,
// against this payment before submitting them. Do not store the raw card.

The supplied URL targets PCI Vault's POST /v1/capture/{unique_id}. Its capture reference is different from your order reference. Use the exact URL and secret returned by Wegopay; do not change references or add vault account credentials. Never send raw card fields to any Wegopay route, metadata or support message. See the PCI Vault capture API.

Submit the token. Resume the customer action.#

POST /v1/payments/{id}/pay
Authorization: Bearer <your merchant API key>
Content-Type: application/json

{
  "cardToken": "EXAMPLE_OPAQUE_CAPTURE_TOKEN",
  "captureReference": "EXAMPLE_SERVER_ISSUED_REFERENCE"
}

These placeholders are illustrative, never valid capture credentials. Submit the actual returned token and reference with the original payment ID. Wegopay validates their binding and executes payment using the existing durable attempt fence. Competing hosted and token submissions cannot charge this payment independently.

Sandbox cards: test both customer-action paths

Sandbox only: use a wgp_test_… key, card holder TEST TEST, expiry 12/2030 and CVV 123. Submit the raw test card only to PCI Vault from your backend, then submit its returned token and reference to Wegopay. Create a separate payment and capture for each scenario. Never use these cards with live credentials. See sandbox setup and verification.

A merchant backend cannot complete a 3DS challenge

When pay or status returns data.status: requiresAction, send the customer browser to prepared.actionUrl. You can also retrieve it through authenticated GET /v1/payments/{id}/checkout. The Wegopay action page resumes the current challenge and confirmation without asking for a card again, including reloads. Give only that action URL to the browser; keep API keys and capture access on the backend.

Prefer the supplied action page. An explicitly approved custom action integration may call POST /v1/payments/{id}/confirm with {} after the customer completes the action; further returned actions must be completed too. A challenge completion, confirm response or success redirect does not establish paid status.

Poll and receive signed webhooks

Poll GET /v1/payments/{id}/status from your backend for checkout progress, with backoff such as 2s, 5s, then 10s. Stop the active polling loop for a terminal checkout or required customer action, and respect 429. Retrieve GET /v1/payments/{id}for authoritative payment state. Signed webhooks use the existing exact-byte verification and durable event deduplication flow. Match ID, merchant order reference, environment, currency and amount, then fulfill exactly once only on verified paid. Checkout expiry alone is not definitive payment failure.

Keep the original payment through uncertainty#

Same-token recovery preserves the original payment operation after an uncertain result, even if capture access subsequently expires. Retain identifiers encrypted only for this payment's agreed recovery period. Disable card, token, secret, action URL and request/response body logging in your own backend, tracing, error reporting and proxies. Agree card/CVC lifecycle and PCI responsibilities during onboarding.

Download the backend example

The sanitized Node.js module validates vault destination, expiry and returned reference, separates capture from payment, requires durable encrypted token retention before combined capture/payment, and supports status polling and verified fulfillment. It sends no requests when imported. Supply your own order persistence, encrypted retention and browser redirect handling. Use the webhook verifier with environment-specific secrets and transactional event acceptance. The complete guide covers the same flow.

Acceptance and availability

Local fixtures cover ownership and environment isolation, expiry, concurrent submission, retries and uncertain outcomes. External sandbox checks on October 6, 2026 passed immediate payment success and a real browser 3DS challenge with authenticated paid verification and signed webhook delivery. Those checks predate the current repository refactor; repeat acceptance against the exact deployed candidate. Frictionless, failed/canceled actions and deployed callback networking still need acceptance. Production activation also requires account capacity, card/CVC deletion and retention evidence, merchant PCI onboarding, and operational cleanup and monitoring. Contact Wegopay for your environment's activation status.

Signed events. Reliable delivery.#

Webhooks tell your server when a payment changes. Delivery is at least once and events may arrive out of order. Use an event as a trigger to retrieve current payment state.

Node.js verifier · Companion tests ↗

Node.js 22.18+. No npm dependencies. Implement the database callback shown in this wiring example.

import { webhookHandler } from './webhook.mjs';
import { acceptEventDurably } from './your-database.mjs';

// Mount on your registered HTTPS endpoint,
// before any JSON body parser.
const handler = webhookHandler({
  secrets: [process.env.WEGOPAY_WEBHOOK_SECRET],
  expectedEnvironment: 'sandbox',
  acceptEvent: acceptEventDurably,
});

// Implement acceptEventDurably in your database:
// 1. Insert event.eventId under a UNIQUE constraint.
// 2. Queue processing in the SAME transaction.
// 3. Treat an already accepted duplicate as success.
// The handler returns 2xx only after acceptance.

Signature format & event types

Wegopay-Signature: t=<unix-seconds>,v1=<hex-digest>

Verify HMAC-SHA256 over timestamp + "." + rawBody using the full issued secret as UTF-8. Compare in constant time with a five-minute timestamp tolerance. Match Wegopay-Event-Id to the signed eventId.

The envelope includes version (1), eventId, type, createdAt, environment, and data. Event types: payment.paid, payment.failed, payment.refunded, payment.partially_refunded, payment.disputed, payment.dispute_won, payment.dispute_lost.

The complete data object is shown below. Use id andreference to resolve your order after signature verification. It includes status, amounts, currency, and nullable failure details; it excludes customer, metadata, checkout URLs, and provider identifiers. Nullable keys remain present asnull. Because an event is a snapshot and delivery can be out of order, retrieve the payment for its current state before fulfillment. The signed environment is on the envelope, outside data.

{
  "version": 1,
  "eventId": "01K4Q75T30GZN5VR8JZ6F0D1XM",
  "type": "payment.paid",
  "createdAt": "2026-09-09T12:01:00Z",
  "environment": "sandbox",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "reference": "order-0001",
    "status": "paid",
    "method": "card",
    "amountCents": 1500,
    "refundedCents": 0,
    "netCents": 1500,
    "currency": "USD",
    "cardBin": "411111",
    "cardIssuer": {
      "bank": "Example Bank",
      "countryCode": "US",
      "countryName": "United States",
      "type": "CREDIT",
      "level": "CLASSIC",
      "category": "PERSONAL",
      "regulated": null
    },
    "cardBrand": "visa",
    "cardLast4": "1111",
    "failureCode": null,
    "failureMessage": null,
    "failureIsFinal": true,
    "refunds": [],
    "dispute": null,
    "verifiedAt": "2026-09-09T12:01:00Z",
    "statusVersion": 2,
    "observationVersion": 1,
    "createdAt": "2026-09-09T12:00:00Z",
    "paidAt": "2026-09-09T12:01:00Z",
    "refundedAt": null
  }
}

Card details

Payment webhooks include data.cardBrand (for example, visa) and data.cardLast4 from verified provider status. The last four digits are a four-character string, so leading zeros are preserved (for example, "0042"). Both keys remain null when unavailable; card details are not guaranteed for every paid payment or wallet payment. The same fields are available from GET /v1/payments/{id}.

BIN/IIN is the first six or eight digits identifying the card issuer, separate from the last four digits. When PCI Vault capture metadata is configured, payment reads, transaction details, and webhooks include cardBin and cardIssuer with issuing bank, country, card type, level, personal/commercial category, and regulation classification where available. These values come from an authenticated capture callback bound to the payment attempt, and remain null when unavailable. Historical events may omit these fields. A later event with a higher observation version may supply metadata that arrived after payment verification. Full card numbers, expiry dates, and CVV/CVC are not included in payment reads or webhooks.

Refunds, disputes & verification

New events include failureIsFinal, the provider's finality flag or null when unavailable; it does not guarantee settlement or prevent later refunds or disputes. refunds contains individual amountCents entries when the provider supplies a complete list matching refundedCents. An empty array means a reported empty list; null means unavailable. dispute contains the card-network stage, sanitized reason, amount in cents, currency, and nullable creation time. Unknown network stages and reasons become other.

verifiedAt records when Wegopay authenticated this observation. Use observationVersion per payment to recognize older snapshots; gaps are normal. statusVersion increases when normalized status changes. A new dispute stage can produce another payment.disputed event with the same status and a higher observation version. Unchanged reads do not emit another event. These additive version-1 fields can be absent from older queued events; accept additional fields after verifying the raw-body signature.

Processor names and identifiers, processing costs, platform balances and FX, credentials, action secrets, raw evidence, and raw provider responses are excluded. See PaymentWebhookEvent in OpenAPI for the typed event schema. These additional details are webhook fields; payment GET retains its existing schema.

Delivery retries & secret rotation

Six attempts: immediate, then 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours after each previous failure. Non-2xx responses and timeouts retry. Redirects are not followed; webhook Retry-After is ignored.

Retries have fresh signatures. Queued deliveries retain their original signing-secret snapshot, even after rotation or disabling a configuration. Keep draining old secrets until Wegopay confirms they can be removed. Use separate sandbox and live handlers and secrets.

Retry requests, not payments.#

Match statuses and failure reasons#

Keep payment status, checkout availability, failure reason, and request errors as separate fields. Values are case-sensitive. Use the full payment status list to map your order's payment outcome from GET /v1/payments/{id}. There is no expired, canceled, or declined payment status. A browser cancellation, 3DS error, timeout, or HTTP error does not establish payment failure; keep unresolved payments pending and reconcile.

Checkout states

Merchant-owned checkout reads these states from GET /v1/payments/{id}/status. Checkout configuration reads use the same states. They describe checkout separately from the payment outcome.

Checkout terminal reasons

Failure codes

Payment GET and signed payment webhook snapshots expose nullable failureCode and failureMessage. Failed pay/confirm attempts expose failureCode and message. Match codes, not message text; messages can differ between surfaces. A retryable attempt's reason need not appear in the pending payment's failure fields. The current recognized business declines and technical fallbacks are:

failureCode is an open string, not a closed enum. Authenticated provider status verification can retain other sanitized codes, including error, failed, cancelled, or canceled when no separate code is supplied. Unknown decoded HTTP 2xx decline codes fall back tocard_declined; unknown HTTP 422 codes remain unresolved. Status verification may preserve a different code. Support an unknown-code category, retain the code for support, and derive the outcome from payment status. A failure reason alone does not authorize a new charge.

Example: insufficient_funds with checkout failed_retryable and payment pending maps to Pending payment with last attempt reason Insufficient funds. Checkout expired with reason checkout_expired and payment pending maps to Checkout expired / payment unresolved. Only payment GET with status: failed maps the payment itself to Failed.

The complete request error list follows below. Request errors describe an API operation and do not replace payment status. Sandbox simulation states and events belong to separate test resources; never fulfill real orders from them.

How approval rate is calculated#

The dashboard measures successful live payments against selected bank/provider rejections. Each payment counts once, regardless of the number of attempts.

A rejection counts when the payment is definitively failed with an eligible code. A pending payment also counts when its latest attempt failed with an eligible code and its checkout is expired or past its deadline, provided it is not processing. This reporting classification does not change the payment's pending status. An earlier rejection is not counted if the latest attempt is excluded or unresolved.

A successful retry counts as approved. Reporting windows use payment creation time and UTC calendar boundaries; sandbox payments are excluded. With no qualifying payments, the dashboard displays an em dash. For example, 100 approvals, 10 eligible rejections and 20 card-detail or account-condition failures give 100 / (100 + 10) = 90.9%.

This measures bank/provider approval, rather than completion of all created payments or platform reliability. Excluded outcomes remain in transaction history with their actual statuses and reasons. See the status and failure-code reference for integration handling.

Handle errors predictably#

Branch on error.code, not message text. Error bodies contain error.code and error.message; validation errors may also identify error.field. On payment creation, an out-of-range amount returns422 validation_failed with error.field: amountCents; unknown properties use error.field: body. Malformed JSON remains400 invalid_request.

For transport failures, preserve the original key and body. Stop and investigate persistent errors. Never log authorization headers, checkout URLs, signing secrets, or payment payloads.

Prove the flow in sandbox#

Complete a joint deployed sandbox test with Wegopay using provider-approved test methods. Agree the acceptance evidence and an operational contact before live access.

• ✓Verified paid state, signed event accepted, and exactly one fulfillment
• ✓Required actions, declines, cancellation, and expiry without premature fulfillment
• ✓Concurrent creation, duplicate events, and out-of-order delivery
• ✓Tampered signatures, environment isolation, key revocation, and secret rotation
• ✓Receiver recovery and reconciliation after provider timeouts