API reference

Payments

Create a payment with a hosted checkout session, then read its verified state. These are the only endpoints a standard hosted-checkout integration needs.

Create a payment

POST/v1/payments

Creates a pending payment and its hosted checkout session. The session allows five card attempts and lasts about 30 minutes. Repeating a request with the same Idempotency-Key and body returns the original response instead of creating another payment.

Auth Secret API key as Authorization: Bearer. Call from your server only.

Headers

Idempotency-Key*requiredstring16–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

amountCents*requiredinteger500–100000000
currency*requiredstring
AlwaysUSD
reference*requiredstring1–255 chars
successUrl*requiredstring <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.
cancelUrl*requiredstring <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

Malformed path, header, or strict JSON request.

Error codesinvalid_request

errorobject
- codestring
  Alwaysinvalid_request
- messagestring

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

Error codesunauthorized

HeadersWWW-Authenticate

errorobject
- codestring
  Alwaysunauthorized
- messagestring

Idempotency key conflict or matching request still fenced.

Error codesidempotency_key_reusedidempotency_in_progress

errorobject
- codestring
  One ofidempotency_key_reusedidempotency_in_progress
- messagestring

Semantically invalid payment creation field.

Error codesvalidation_failed

errorobject
- codestring
  Alwaysvalidation_failed
- messagestring
- fieldstringoptional

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

See errors and idempotency for how to handle each error code.

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"
  }
}

Retrieve a payment

GET/v1/payments/{id}

Retrieves a payment. This is the source of truth before you fulfill an order. Unknown IDs and payments of another merchant or environment return the same 404.

Auth Secret API key as Authorization: Bearer. Call from your server only.

Path parameters

id*requiredstring <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

Malformed path, header, or strict JSON request.

Error codesinvalid_request

errorobject
- codestring
  Alwaysinvalid_request
- messagestring

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

Error codesunauthorized

HeadersWWW-Authenticate

errorobject
- codestring
  Alwaysunauthorized
- messagestring

Unknown or unauthorized resource/token, without existence disclosure.

Error codesnot_found

errorobject
- codestring
  Alwaysnot_found
- 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

See errors and idempotency for how to handle each error code.

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
  }
}

List payments

GET/v1/payments

Lists the payments of your key’s merchant and environment, newest first. Date filters apply to createdAt as inclusive UTC dates. A page past the end returns an empty list.

Auth Secret API key as Authorization: Bearer. Call from your server only.

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

See errors and idempotency for how to handle each error code.

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
  }
}