Skip to content
Docs

Get started

Quickstart

Create a sandbox payment, pay it with a test card, and verify the result from your server.

Before you start

  • Ask Wegopay to activate your account. Then create a sandbox key in Dashboard → API Keys.
  • Optionally, add a sandbox webhook endpoint in Dashboard → Settings → Webhook. Store its signing secret on your server. See webhooks.
Environment
export WEGOPAY_API_BASE_URL="https://api.wegopay.tech"
# Load the sandbox key from your secret manager; never commit it.
export WEGOPAY_API_KEY="wgp_test_…"

1. Create a payment

Call POST /v1/payments from your server. Generate an Idempotency-Key for the order and store it before sending, so a retry after a timeout cannot create a second payment.

POST/v1/payments
API reference →

Headers

  • Idempotency-Keyrequiredstring16–255 chars

    16 to 255 visible ASCII characters. Scope is authenticated merchant plus operation. Records are retained for twenty-four hours.

Request body application/json

  • amountCentsrequiredinteger500–100000000
  • currencyrequiredstring

    AlwaysUSD

  • referencerequiredstring1–255 chars
  • successUrlrequiredstring <uri>1–2048 chars

    Absolute URL parsed by a standards-compliant URL parser. Production permits HTTPS only. HTTP is accepted only when the hostname is exactly localhost, 127.0.0.1, or ::1 in development. Credentials and fragments are forbidden; hostnames are canonicalized before validation.

  • cancelUrlrequiredstring <uri>1–2048 chars

    Absolute URL parsed by a standards-compliant URL parser. Production permits HTTPS only. HTTP is accepted only when the hostname is exactly localhost, 127.0.0.1, or ::1 in development. Credentials and fragments are forbidden; hostnames are canonicalized before validation.

  • paymentMethodstring

    Optional checkout restriction. Opens only this method and prevents switching. Must be enabled by the effective API-key and merchant settings, otherwise creation returns 422 validation_failed for paymentMethod. Omit to offer all configured methods. Custom card capture supports card only.

    One ofcardwallet

  • checkoutModestring

    Defaults to hosted. Custom requires an enabled merchant capture integration. Prepare scoped access with POST capture, submit a token and captureReference, and open actionUrl in the customer browser when required.

    One ofhostedcustom

  • embeddingOriginstring1–255 chars

    Exact approved website to embed this checkout. Required for embedding when the effective allowlist exceeds 20 sites. Omission preserves legacy embedding for lists up to 20 and otherwise permits hosted checkout only.

  • localestring

    Wegopay checkout language. Omission on creation selects English. Provider-hosted content is controlled separately.

    One ofenespt

  • environmentstring

    Immutable provider account selection derived from the API key. Omit environment on creation or provide the same environment as the key; a mismatch is rejected. Test keys can only access sandbox payments and live keys can only access live payments.

    One ofsandboxlive

  • customerobject
    • emailstring <email>≤ 320 chars
    • namestring1–255 chars
    • documentNumberstring

      Payer document number for server-side wallet initiation.

    • phonestring

      Payer phone number for server-side wallet initiation.

  • metadataobject (free-form)≤ 100 keys

    Merchant-defined JSON object. The server measures canonical UTF-8 JSON, including keys and structural bytes, and rejects values over 16384 bytes. The limit is applied before persistence and is part of idempotency hashing.

Responses

Payment and checkout session created, or exact idempotent replay.

  • dataobject
    • idstring <uuid>
    • statusstring

      Alwayspending

    • checkoutUrlstring <uri>1–2048 chars

      Absolute URL parsed by a standards-compliant URL parser. Production permits HTTPS only. HTTP is accepted only when the hostname is exactly localhost, 127.0.0.1, or ::1 in development. Credentials and fragments are forbidden; hostnames are canonicalized before validation.

    • expiresAtstring <date-time>
    • environmentstringoptional

      Immutable provider account selection derived from the API key. Omit environment on creation or provide the same environment as the key; a mismatch is rejected. Test keys can only access sandbox payments and live keys can only access live payments.

      One ofsandboxlive

Request
curl -X POST "https://api.wegopay.tech/v1/payments" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY" \
  -H "Idempotency-Key: order-1042-create" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1500,
    "currency": "USD",
    "reference": "order-1042",
    "successUrl": "https://shop.example.com/orders/1042",
    "cancelUrl": "https://shop.example.com/cart",
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "metadata": {
      "orderId": "order-1042"
    }
  }'
Response
{
  "data": {
    "environment": "sandbox",
    "id": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "status": "pending",
    "checkoutUrl": "https://wegopay.tech/c/wgp_chk_example",
    "expiresAt": "2026-10-11T12:30:00Z"
  }
}

Save data.id against your order. The amount must be at least 500 cents ($5.00).

2. Send the customer to checkout

Redirect the customer’s browser to data.checkoutUrl exactly as returned. Treat it like a secret: it opens this payment. The session lasts about 30 minutes; the exact deadline is expiresAt.

3. Pay with a test card

On the sandbox checkout, choose Pay by card and enter 4242 4242 4242 4242. Use expiry 12/2030, CVV 123 and card holder TEST TEST. More cards are listed under sandbox testing.

4. Verify the payment

When the customer returns to your successUrl, or a webhook arrives, read the payment from your server:

GET/v1/payments/{id}
API reference →

Path parameters

  • idrequiredstring <uuid>

Responses

Merchant-scoped payment.

  • dataobject
    • idstring <uuid>
    • referencestring
    • statusstring

      One ofpendingrequiresActionpaidfailedrefundedpartiallyRefundeddisputeddisputeWondisputeLost

    • methodstringcan be null

      One ofcardwalletpix

    • amountCentsinteger500–100000000
    • refundedCentsinteger0–100000000
    • netCentsinteger0–100000000
    • currencystring

      AlwaysUSD

    • customerobject
      • emailstring <email>can be null≤ 320 chars
      • namestringcan be null≤ 255 chars
    • metadataobject (free-form)≤ 100 keys

      Merchant-defined JSON object. The server measures canonical UTF-8 JSON, including keys and structural bytes, and rejects values over 16384 bytes. The limit is applied before persistence and is part of idempotency hashing.

    • checkoutUrlstring <uri>can be null1–2048 chars

      Absolute URL parsed by a standards-compliant URL parser. Production permits HTTPS only. HTTP is accepted only when the hostname is exactly localhost, 127.0.0.1, or ::1 in development. Credentials and fragments are forbidden; hostnames are canonicalized before validation.

    • expiresAtstring <date-time>
    • cardBinstringcan be null

      Issuer prefix from authenticated PCI Vault capture matched to the verified attempt. Null when unavailable.

    • cardIssuerobjectcan be null
      • bankstringcan be null≤ 128 chars
      • countryCodestringcan be null
      • countryNamestringcan be null≤ 128 chars
      • typestringcan be null≤ 128 chars
      • levelstringcan be null≤ 128 chars
      • categorystringcan be null≤ 128 chars
      • regulatedstringcan be null≤ 128 chars
    • cardBrandstringcan be null

      Card brand from verified provider status; also included in signed payment webhook data. Null when unavailable.

    • cardLast4stringcan be null

      Last four card digits from verified provider status as a string preserving leading zeros; also included in signed payment webhook data. Null when unavailable. This is not a BIN/IIN; BIN/issuer metadata is separately available in cardBin and cardIssuer when PCI Vault capture metadata is configured.

    • failureCodestringcan be null
    • failureMessagestringcan be null
    • createdAtstring <date-time>
    • paidAtstring <date-time>can be null
    • refundedAtstring <date-time>can be null
    • environmentstringoptional

      Immutable provider account selection derived from the API key. Omit environment on creation or provide the same environment as the key; a mismatch is rejected. Test keys can only access sandbox payments and live keys can only access live payments.

      One ofsandboxlive

Request
curl "https://api.wegopay.tech/v1/payments/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY"
Response
{
  "data": {
    "environment": "sandbox",
    "id": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "reference": "order-1042",
    "status": "paid",
    "method": "card",
    "amountCents": 1500,
    "refundedCents": 0,
    "netCents": 1500,
    "currency": "USD",
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "metadata": {
      "orderId": "order-1042"
    },
    "checkoutUrl": "https://wegopay.tech/c/wgp_chk_example",
    "expiresAt": "2026-10-11T12:30:00Z",
    "cardBrand": "visa",
    "cardBin": "424242",
    "cardIssuer": null,
    "cardLast4": "4242",
    "failureCode": null,
    "failureMessage": null,
    "createdAt": "2026-10-11T12:00:00Z",
    "paidAt": "2026-10-11T12:01:12Z",
    "refundedAt": null
  }
}

Fulfill only on a verified match

Check that status is paid and that the ID, reference, amountCents, currency and environment match your order. Then mark the order fulfilled, once.

Next