Skip to content
Docs

API reference

Card capture

Endpoints for merchant-owned card checkout. They require activation for your merchant and environment; hosted checkout does not use them.

Prepare card capture

POST/v1/payments/{id}/capture

Returns short-lived, write-only access to capture one card for this payment directly at the card vault. Preparation never charges. Payments without card capture enabled return 404.

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

Path parameters

  • idrequiredstring <uuid>

Responses

Merchant and environment scoped custom checkout state and capture coordinates.

  • dataobject
    • paymentIdstring <uuid>
    • amountCentsinteger500–100000000
    • currencystring

      AlwaysUSD

    • referencestring1–255 chars
    • statusstring

      One ofopenprocessingrequiresActionpaidfailed_retryableexpired

    • expiresAtstring <date-time>
    • attemptsLeftinteger0–5
    • 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

    • pciConfigobject
      • providerstring

        AlwayspciVault

      • captureUrlstring <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.

      • vaultIdstring1–31 chars

        Random payment-scoped capture reference; never your order reference. The server-owned dedicated vault key establishes payment isolation.

      • allowedOriginstring <uri>
      • iframeUrlstring <uri>optional1–2048 chars

        Present only with a hosted form configured for the merchant checkout origin. Direct capture credentials are returned by POST capture.

    • terminalReasonstringoptional

      Why a checkout closed. A provider failure is not a local link timeout.

      One ofcheckout_expiredattempts_exhaustedprovider_failed

    • actionUrlstring <uri>optional1–2048 chars

      Open in the customer browser only when payment requiresAction; existing checkout resumes the challenge without card collection.

    • captureobjectoptional
      • urlstring <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.

      • secretstring16–4096 chars

        Write-only capture secret. Keep on your backend; never log.

      • referencestring1–31 chars
      • expiresAtstring <date-time>

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

Request
curl -X POST "https://api.wegopay.tech/v1/payments/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55/capture" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY"
Response
{
  "data": {
    "paymentId": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "amountCents": 1500,
    "currency": "USD",
    "reference": "order-1042",
    "status": "open",
    "expiresAt": "2026-10-11T12:30:00Z",
    "attemptsLeft": 5,
    "environment": "sandbox",
    "capture": {
      "url": "https://capture.example/v1/capture/example",
      "secret": "<capture secret, keep server-side>",
      "reference": "cap_9fQx2LwM",
      "expiresAt": "2026-10-11T12:10:00Z"
    },
    "pciConfig": {
      "provider": "pciVault",
      "captureUrl": "https://capture.example/v1/capture/example",
      "vaultId": "cap_9fQx2LwM",
      "allowedOrigin": "https://shop.example.com"
    }
  }
}

Retrieve the card checkout

GET/v1/payments/{id}/checkout

Returns the card checkout of a capture payment: amount, status, attempts left, and the actionUrl to open in the customer’s browser when an action is required.

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

Path parameters

  • idrequiredstring <uuid>

Responses

Merchant and environment scoped custom checkout state and capture coordinates.

  • dataobject
    • paymentIdstring <uuid>
    • amountCentsinteger500–100000000
    • currencystring

      AlwaysUSD

    • referencestring1–255 chars
    • statusstring

      One ofopenprocessingrequiresActionpaidfailed_retryableexpired

    • expiresAtstring <date-time>
    • attemptsLeftinteger0–5
    • 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

    • pciConfigobject
      • providerstring

        AlwayspciVault

      • captureUrlstring <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.

      • vaultIdstring1–31 chars

        Random payment-scoped capture reference; never your order reference. The server-owned dedicated vault key establishes payment isolation.

      • allowedOriginstring <uri>
      • iframeUrlstring <uri>optional1–2048 chars

        Present only with a hosted form configured for the merchant checkout origin. Direct capture credentials are returned by POST capture.

    • terminalReasonstringoptional

      Why a checkout closed. A provider failure is not a local link timeout.

      One ofcheckout_expiredattempts_exhaustedprovider_failed

    • actionUrlstring <uri>optional1–2048 chars

      Open in the customer browser only when payment requiresAction; existing checkout resumes the challenge without card collection.

    • captureobjectoptional
      • urlstring <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.

      • secretstring16–4096 chars

        Write-only capture secret. Keep on your backend; never log.

      • referencestring1–31 chars
      • expiresAtstring <date-time>

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

Request
curl "https://api.wegopay.tech/v1/payments/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55/checkout" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY"
Response
{
  "data": {
    "paymentId": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "amountCents": 1500,
    "currency": "USD",
    "reference": "order-1042",
    "status": "open",
    "terminalReason": "checkout_expired",
    "expiresAt": "2026-10-11T12:00:00Z",
    "attemptsLeft": 5,
    "environment": "sandbox",
    "actionUrl": "https://wegopay.tech/c/wgp_chk_example",
    "capture": {
      "url": "https://shop.example.com",
      "secret": "string",
      "reference": "order-1042",
      "expiresAt": "2026-10-11T12:00:00Z"
    },
    "pciConfig": {
      "provider": "pciVault",
      "captureUrl": "https://shop.example.com",
      "vaultId": "string",
      "allowedOrigin": "https://shop.example.com",
      "iframeUrl": "https://shop.example.com"
    }
  }
}

Submit a card token

POST/v1/payments/{id}/pay

Submits the token and reference returned by the card vault. The response is the result of this attempt: paid, requiresAction or failed. A 409 or 503 can mean the attempt is still processing; poll the status before doing anything else.

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

Path parameters

  • idrequiredstring <uuid>

Request body application/json

  • cardTokenrequiredstring16–4096 chars
  • captureReferencerequiredstring1–31 chars

    Must equal the server-issued payment capture reference and the vault capture result reference.

Responses

Paid, repeated customer action, or definitive retryable failure.

  • dataone of

    Variant paid

    • statusstring

      Alwayspaid

    • paymentIdstring <uuid>

    Variant requiresAction

    • statusstring

      AlwaysrequiresAction

    • paymentIdstring <uuid>
    • clientSecretstring1–2048 chars
    • publishableKeystring1–255 chars

    Variant failed

    • statusstring

      Alwaysfailed

    • paymentIdstring <uuid>
    • failureCodestring1–128 chars
    • messagestring1–500 chars
    • attemptsLeftinteger0–5

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

Request
curl -X POST "https://api.wegopay.tech/v1/payments/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55/pay" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardToken": "EXAMPLE_CARD_TOKEN_FROM_CAPTURE",
    "captureReference": "cap_9fQx2LwM"
  }'
Response
{
  "data": {
    "status": "requiresAction",
    "paymentId": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55"
  }
}

Confirm a customer action

POST/v1/payments/{id}/confirm

Confirms the current customer action after the customer completes it. Only for approved custom action handling; the page at actionUrl already does this.

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

Path parameters

  • idrequiredstring <uuid>

Request body application/json

object

Responses

Paid, repeated customer action, or definitive retryable failure.

  • dataone of

    Variant paid

    • statusstring

      Alwayspaid

    • paymentIdstring <uuid>

    Variant requiresAction

    • statusstring

      AlwaysrequiresAction

    • paymentIdstring <uuid>
    • clientSecretstring1–2048 chars
    • publishableKeystring1–255 chars

    Variant failed

    • statusstring

      Alwaysfailed

    • paymentIdstring <uuid>
    • failureCodestring1–128 chars
    • messagestring1–500 chars
    • attemptsLeftinteger0–5

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

Request
curl -X POST "https://api.wegopay.tech/v1/payments/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55/confirm" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "status": "paid",
    "paymentId": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55"
  }
}

Retrieve checkout status

GET/v1/payments/{id}/status

Returns the checkout state, attempts left and any pending customer action. Poll it with backoff while a capture payment is processing.

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

Path parameters

  • idrequiredstring <uuid>

Responses

Exact durable checkout status.

  • dataobject
    • paymentIdstring <uuid>
    • statusstring

      One ofopenprocessingrequiresActionpaidfailed_retryableexpired

    • attemptsLeftinteger0–5
    • expiresAtstring <date-time>
    • actionone ofcan be null

      Present only while status is requiresAction; null for every other status.

      Variant threeDS

      • kindstring

        AlwaysthreeDS

      • clientSecretstring1–2048 chars

        Decrypted only for the current requiresAction fence so a checkout can resume after reload.

      • publishableKeystring1–255 chars

      Variant wallet

      • kindstring

        Alwayswallet

      • 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>
    • terminalReasonstringoptional

      Why a checkout closed. A provider failure is not a local link timeout.

      One ofcheckout_expiredattempts_exhaustedprovider_failed

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

Request
curl "https://api.wegopay.tech/v1/payments/7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55/status" \
  -H "Authorization: Bearer $WEGOPAY_API_KEY"
Response
{
  "data": {
    "paymentId": "7d5c2f1e-4b8a-4c3e-9f21-6a0b8e4d1c55",
    "status": "processing",
    "attemptsLeft": 4,
    "expiresAt": "2026-10-11T12:30:00Z",
    "action": null
  }
}