Accept payments

Payment status

The payment status is the source of truth for your order. Read it from your server, keep it separate from checkout state and request errors, and fulfill only on a verified paid payment.

Payment statuses

Read data.status from GET /v1/payments/{id}. Webhooks carry the same value. Values are case-sensitive.

Status	Meaning	What to do
`pending`	No final outcome yet.	Keep the order pending and keep reconciling.
`requiresAction`	The customer must complete a step, such as 3D Secure.	Keep the order unfulfilled.
`paid`	Payment verified.	Match the payment to the order, then fulfill once.
`failed`	A final failure is recorded.	Do not fulfill. See `failureCode`.
`refunded`	Fully refunded.	Apply your refund workflow.
`partiallyRefunded`	Partly refunded.	Use `refundedCents`.
`disputed`	The customer disputed the payment.	Apply your dispute workflow.
`disputeWon`	Dispute resolved in your favour.	Close the dispute.
`disputeLost`	Dispute resolved against you.	Close the dispute.

There is no expired, canceled or declined status

A closed browser, the cancel redirect, a 3D Secure error, a timeout or an HTTP error does not make a payment failed. Show these orders as pending and reconcile them.

When to fulfill

Read the payment from your server with the key for its environment.
Require status === "paid", and check the payment ID, reference, amountCents, currency and environment against your order.
Mark the order fulfilled in one atomic update, so a duplicate webhook or retry cannot fulfill it twice.

Read and list payments

GET/v1/payments

API reference →

Query parameters

statusstring
One ofpendingrequiresActionpaidfailedrefundedpartiallyRefundeddisputeddisputeWondisputeLost
fromstring <date>
Inclusive UTC createdAt date. Must not be after to.
tostring <date>
Inclusive UTC createdAt date. Must not be before from.
pageinteger≥ 1
Default1
perPageinteger1–100
Default20

Responses

Merchant-scoped payment page.

dataarray of object
- 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
metaobject
- pageinteger≥ 1
- perPageinteger1–100
- totalinteger≥ 0

Invalid date, pagination, status, or from/to relation.

Error codesinvalid_query

errorobject
- codestring
  Alwaysinvalid_query
- messagestring

Missing, malformed, unknown, revoked, or disabled-merchant API key.

Error codesunauthorized

HeadersWWW-Authenticate

errorobject
- codestring
  Alwaysunauthorized
- messagestring

Rate limit exceeded without starting payment work.

Error codesrate_limited

HeadersRetry-After

errorobject
- codestring
  Alwaysrate_limited
- messagestring

Required persistence, encryption, hosted-fields, or payment processing dependency unavailable.

Error codesservice_unavailable

errorobject
- codestring
  Alwaysservice_unavailable
- messagestring

Request

curl "https://api.wegopay.tech/v1/payments?status=paid&page=1&perPage=20" \
  -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
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 1
  }
}

Lists are newest first and accept status, inclusive UTC from and to dates (YYYY-MM-DD), page and perPage (1–100). An unknown payment, or one belonging to another merchant or environment, returns 404.

Polling and reconciliation

Webhooks are the main signal, but do not rely on them alone. Reconcile pending orders on a schedule.

While a customer is waiting, poll the payment every 10 seconds, then back off to 30–60 seconds with jitter.
Limit polling across all payments and honour Retry-After on 429.
Stop interactive polling when the payment resolves or the customer leaves; keep reconciling in the background.
A read returns stored state; it does not trigger a new check with the payment network.

Checkout expiry

expiresAt is the checkout deadline, about 30 minutes after creation. Expiry stops further use of the checkout but does not change the payment to failed. There is no expiry webhook and no guaranteed time for pending to resolve, so keep reconciling after the customer leaves.

Checkout state

With merchant card capture, GET /v1/payments/{id}/status returns the checkout state. It describes the checkout session, not the payment.

Checkout status	Meaning
`open`	Ready for a payment attempt.
`processing`	An attempt or its verification is in progress. Poll the same payment.
`requiresAction`	Complete the customer action before anything else.
`paid`	Checkout saw a verified success. Still verify the payment against the order.
`failed_retryable`	An attempt failed and another may be allowed. The payment can still be pending.
`expired`	Checkout is closed. See `terminalReason`.

Terminal reasons

terminalReason	Meaning
`checkout_expired`	The deadline passed.
`attempts_exhausted`	No attempts remain.
`provider_failed`	A verified payment-network failure closed checkout.

In every case, read the payment for its outcome. Pay and confirm calls can return failed with attemptsLeft: that is one attempt, not the payment’s final status. See failure codes.