# API Reference — Payments v4.0
**Create and manage payments**
REST API for creating and managing GoPay payments: creating a payment, charging it with a payment instrument, following it through to a terminal outcome, and managing saved card tokens. The long-form integration guides are published alongside this reference.
## Servers
- `https://gw.sandbox.gopay.com/gp-gw/api/4.0` — Sandbox
- `https://gate.gopay.com/gp-gw/api/4.0` — Production
## Security schemes
- `basic` (http; basic) — Only used to obtain a JWT on `POST /oauth2/token`.
- The merchant's server uses `client_id:client_secret`
- The GoPay client SDK uses `payment_id:payment_secret`
See [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) for the scheme.
- `merchant_credentials` (oauth2) — Authorizes the merchant's server using `client_id:client_secret`.
The secret and the JWT must never leave the merchant's server.
- `payment_credentials` (oauth2) — Authorizes a client for payment-specific operations using `payment_id:payment_secret`.
These credentials and the JWT are used by the GoPay client SDK in the merchant's web or mobile app.
The client presents `payment_id:payment_secret` as HTTP Basic on `POST /oauth2/token` with `grant_type=payment_credentials` and requests `payment:read`, `payment:charge`, or both. The returned JWT is bound to the payment and valid for fifteen minutes. The exchange may be repeated to obtain a fresh JWT; `payment_secret` does not expire, and an operation that the payment's state no longer allows is rejected, mostly with `409`.
- `shareable_key` (http; basic) — `client_id:shareable_key` encoded in base64 in the Authorization header. `shareable_key` is configured in the GoPay client SDK.
Used to authenticate to endpoints holding public resources such as public keys and URLs, and values derived from the request itself.
See [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) for the scheme.
## Operations
### Authentication
Exchanging merchant and per-payment credentials for the access tokens that authorise every other call.
#### Authenticate
`POST /oauth2/token` · Operation ID: `post-oauth2-token`
Requires: `basic`
Exchanges credentials for an access token.
The merchant's server presents `client_id:client_secret` with the `client_credentials` grant; the GoPay client SDK presents `payment_id:payment_secret` with the `payment_credentials` grant to obtain a payment-scoped token. Credentials are sent as HTTP Basic and at least one scope must be requested. The returned `access_token` is a JWT valid for fifteen minutes and is presented as a Bearer token on the calls that authenticate with it; the `shareable_key` endpoints use HTTP Basic instead and involve no token exchange.
**Request body** (required)
`application/x-www-form-urlencoded`: [Client-Credentials-Request](#schema-Client-Credentials-Request) | [Payment-Credentials-Request](#schema-Payment-Credentials-Request)
Example — Client Credentials:
```json
{
"grant_type": "client_credentials",
"scope": "payment:write payment:read"
}
```
**Responses**
- `200` The access token — [Access-Token](#schema-Access-Token)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### Payments
Creating a payment, charging it with a payment instrument, and following it through to a terminal outcome.
#### Create a payment
`POST /eshops/{goid}/payments` · Operation ID: `post-eshops-goid-payments`
Requires: `merchant_credentials` (scopes: `payment:write`)
Creates a payment for the given eshop.
The response carries the payment `id`, the per-payment client credential `payment_secret`, and `gw_url` — the address of GoPay's hosted payment gateway, which offers the customer every payment method the eshop has enabled but cannot be embedded in the merchant's own checkout. The new payment is in the `CREATED` state and awaits a charge attempt; if none is made before the initial timeout expires, it transitions to `TIMEOUTED`.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
**Request body** (optional)
`application/json`: [Payment-Create-Request](#schema-Payment-Create-Request)
**Responses**
- `201` The new payment — [Payment-Details](#schema-Payment-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Payment Status
`GET /payments/{payment_id}` · Operation ID: `get-payments-payment_id`
Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)
Returns the current state of a payment.
Called after a webhook notification or a return-URL redirect to learn the outcome, since both carry only the payment `id`. The `state` field follows the payment lifecycle from `CREATED` to a terminal outcome.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `200` The payment — [Payment-Details](#schema-Payment-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Cancel a payment
`DELETE /payments/{payment_id}` · Operation ID: `delete-payments-payment_id`
Requires: `merchant_credentials` (scopes: `payment:write`)
Cancels a payment that has not been charged yet.
The payment transitions to `CANCELED` and remains readable; it is not deleted. Only a payment in the `CREATED` state can be canceled; any other state returns `409`. The operation is server-side only.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `204` Done; the response has no body
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Payment charge state
`GET /payments/{payment_id}/charge` · Operation ID: `get-payments-payment_id-charge`
Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)
Returns the current state of the payment's charge.
Polled while a charge is in flight, at a recommended cadence of one second, until the state reaches `SUCCEEDED`, `FAILED` or `ACTION_REQUIRED`. On `ACTION_REQUIRED` the response carries an `action` describing the step the customer must complete; once they have, polling resumes until the charge reaches `SUCCEEDED` or `FAILED`. When a charge fails, the reason is carried in `fail_reason`.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `200` Current state of the payment's charge — [Payment-Charge-Status-Response](#schema-Payment-Charge-Status-Response)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Charge a payment
`POST /payments/{payment_id}/charge` · Operation ID: `post-payments-payment_id-charge`
Requires: `merchant_credentials` (scopes: `payment:write`) or `payment_credentials` (scopes: `payment:charge`)
Attempts to settle a payment with a payment instrument.
Only card payments are charged through this endpoint — `payment_instrument` is always `PAYMENT_CARD`, and the card input type nested under it is one of `ENCRYPTED_CARD`, `CARD_TOKEN`, `APPLE_PAY` or `GOOGLE_PAY`. Other payment methods are reachable only through the hosted gateway. The charge is asynchronous; a state of `ACTION_REQUIRED` means the customer must complete an external step before the charge can terminate.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Request body** (optional)
`application/json`: [Payment-Charge-Input](#schema-Payment-Charge-Input)
**Responses**
- `201` The charge that was started — [Payment-Charge-Response](#schema-Payment-Charge-Response)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### QR Payment Info
`GET /payments/{payment_id}/qr-payment/info` · Operation ID: `get-payments-payment_id-qr-payment-info`
Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)
Returns the data needed to display a QR code for settling the payment by bank transfer.
The response carries the amount, the recipient bank account, and the generated image as a base64 string under the regional format applicable to the payment's currency and recipient country. Requesting a QR code extends the payment's initial timeout to four days and does not change the payment state.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
- `format` (string; query; optional; values: `png`, `svg`; default `"png"`) — Image format of the generated QR code
**Responses**
- `200` The QR payment data for the payment — [QR-Payment-Details](#schema-QR-Payment-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### Refunds
Returning funds from a paid payment to the customer, and reading back the refunds a payment carries.
#### List payment refunds
`GET /payments/{payment_id}/refunds` · Operation ID: `get-payments-payment_id-refunds`
Requires: `merchant_credentials` (scopes: `payment:read`) or `payment_credentials` (scopes: `payment:read`)
Returns every refund issued against the payment.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `200` The refunds of the payment — array of [Refund-Details](#schema-Refund-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Refund a payment
`POST /payments/{payment_id}/refunds` · Operation ID: `post-payments-payment_id-refunds`
Requires: `merchant_credentials` (scopes: `payment:write`)
Refunds a paid payment in full or in part. Set `amount` to the payment amount for a
full refund, or to a lower value for a partial refund. A payment can be refunded
repeatedly until the sum of its refunds reaches the original amount.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Request body** (required)
`application/json`: [Refund-Create-Request](#schema-Refund-Create-Request)
**Responses**
- `201` The new refund — [Refund-Details](#schema-Refund-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Refund details
`GET /refunds/{refund_id}` · Operation ID: `get-refunds-refund_id`
Requires: `merchant_credentials` (scopes: `payment:read`)
Returns the current state and amount of a single refund.
**Parameters**
- `refund_id` (string; path; required) — Identifier of the refund
**Responses**
- `200` The refund — [Refund-Details](#schema-Refund-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### Payment Links
Payment links that carry the data for a payment and create it only when the customer opens the link.
#### Create a payment link
`POST /eshops/{goid}/links` · Operation ID: `post-eshops-goid-links`
Requires: `merchant_credentials` (scopes: `payment:write`)
Creates a payment link for the given eshop. The link only stores the payment data — no payment exists until a customer opens the link.
The response carries `id`, used on the status and disable calls, and `url`, the address to share with the customer. The two are different identifiers: `url` ends in a random ten-character code that cannot be derived from `id`, nor `id` from the code.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
**Request body** (required)
`application/json`: [Link-Create-Request](#schema-Link-Create-Request)
**Responses**
- `201` The new payment link — [Link-Details](#schema-Link-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Link status
`GET /eshops/{goid}/links/{link_id}` · Operation ID: `get-eshops-goid-links-link_id`
Requires: `merchant_credentials` (scopes: `payment:read`)
Returns the current settings and state of a payment link, including the payment data it carries.
Expiry is evaluated on read: a link past its `expires_at` is reported as `active: false` with `stop_reason` `EXPIRED`, without anything being written first.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `link_id` (string; path; required; pattern `^[0-9]+$`) — Link ID returned when the link was created. A non-numeric or negative value is rejected with `400`
**Responses**
- `200` The payment link — [Link-Details](#schema-Link-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Disable a link
`DELETE /eshops/{goid}/links/{link_id}` · Operation ID: `delete-eshops-goid-links-link_id`
Requires: `merchant_credentials` (scopes: `payment:write`)
Deactivates a payment link so that it can no longer start a new payment. This is not a delete: the link can still be read back, and reports `stop_reason` `FROM_API`.
Disabling a link that is already inactive returns `409`. A one-shot link that has already been used is inactive too, so it cannot be disabled — it keeps redirecting to the payment it created. To stop that payment, cancel the payment itself.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `link_id` (string; path; required; pattern `^[0-9]+$`) — Link ID returned when the link was created. A non-numeric or negative value is rejected with `400`
**Responses**
- `204` Done; the response has no body
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### Recurrences
Recurring payments that hold a payment template and create payments from it, either on a schedule or when the merchant asks for the next one.
#### Create a recurrence
`POST /eshops/{goid}/recurrences` · Operation ID: `post-eshops-goid-recurrences`
Requires: `merchant_credentials` (scopes: `payment:write`)
Registers a recurrence for the eshop and returns it in state `NEW`. The recurrence only stores the payment template — no payment exists until the recurrence is started. `schedule` is required for an `AUTO` recurrence and must be omitted for an `ON_DEMAND` one.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
**Request body** (required)
`application/json`: [Recurrence-Create-Request](#schema-Recurrence-Create-Request)
**Responses**
- `201` The new recurrence — [Recurrence-Details](#schema-Recurrence-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Recurrence status
`GET /recurrences/{rec_id}` · Operation ID: `get-recurrences-rec_id`
Requires: `merchant_credentials` (scopes: `payment:read`)
Returns the current state of the recurrence and the payment it last created.
**Parameters**
- `rec_id` (string; path; required) — Unique ID of a previously created recurrence
**Responses**
- `200` The recurrence — [Recurrence-Details](#schema-Recurrence-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Stop a recurrence
`DELETE /recurrences/{rec_id}` · Operation ID: `delete-recurrences-rec_id`
Requires: `merchant_credentials` (scopes: `payment:write`)
Stops the recurrence permanently. It moves to state `STOPPED` with `stop_reason` `CANCELLED_VIA_API` and creates no further payments. Stopping cannot be undone.
**Parameters**
- `rec_id` (string; path; required) — Unique ID of a previously created recurrence
**Responses**
- `204` Done; the response has no body
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Start a recurrence
`POST /recurrences/{rec_id}/start` · Operation ID: `post-recurrences-rec_id-start`
Requires: `merchant_credentials` (scopes: `payment:write`)
Creates the first payment of the recurrence and moves it to state `REQUESTED`. The customer pays that payment at its `gw_url`; once it is paid the recurrence becomes `STARTED` and further payments can be requested. The optional body overrides fields of the stored payment template for this payment only.
**Parameters**
- `rec_id` (string; path; required) — Unique ID of a previously created recurrence
**Request body** (optional)
`application/json`: [Payment-Instance-Override](#schema-Payment-Instance-Override)
**Responses**
- `201` The new payment — [Payment-Details](#schema-Payment-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Create a next payment for a recurrence
`POST /recurrences/{rec_id}/next` · Operation ID: `post-recurrences-rec_id-next`
Requires: `merchant_credentials` (scopes: `payment:write`)
Creates a further payment from a recurrence that has already reached state `STARTED`. Returns `409` while the recurrence has not been started and its first payment paid. The optional body overrides fields of the stored payment template for this payment only.
**Parameters**
- `rec_id` (string; path; required) — Unique ID of a previously created recurrence
**Request body** (optional)
`application/json`: [Payment-Instance-Override](#schema-Payment-Instance-Override)
**Responses**
- `201` The new payment — [Payment-Details](#schema-Payment-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### Cards
Saved card tokens that stand in for a customer's card on later charges.
#### Create card token
`POST /cards/tokens` · Operation ID: `post-cards-tokens`
Requires: `merchant_credentials` (scopes: `card:write`)
Exchanges an encrypted card payload for a permanent card token.
The JWE produced by the GoPay client SDK is submitted in `payload` and exchanged for a `Permanent Card Token Details` object. Its `token` is what a later charge carries as `card_token` in the `CARD_TOKEN` input; its `card_id` addresses the saved card in the read and delete operations. The JWE is single-use. Tokenisation is disabled by default and must be enabled for the merchant; the operation is server-side only.
**Request body** (optional)
`application/json`: [Token-Create-Request](#schema-Token-Create-Request)
**Responses**
- `201` The new saved card token — [Permanent-Card-Token-Details](#schema-Permanent-Card-Token-Details)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Card details
`GET /cards/tokens/{card_id}` · Operation ID: `get-cards-tokens-card_id`
Requires: `merchant_credentials` (scopes: `card:read`)
Returns the current details of a saved card.
Called after the `cards.updated` event to read fields the issuer has updated in place — a reissued PAN or a new expiration date — while the `card_id` stays the same. The API does not list saved cards; the merchant persists the association between `card_id` and customer. Server-side only.
**Parameters**
- `card_id` (string; path; required) — ID of the saved payment card
**Responses**
- `200` The saved card — [Permanent-Card-Token-Details](#schema-Permanent-Card-Token-Details)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Delete a card
`DELETE /cards/tokens/{card_id}` · Operation ID: `delete-cards-tokens-card_id`
Requires: `merchant_credentials` (scopes: `card:write`)
Permanently deletes a saved card.
A deleted token is not recoverable; saving the same card again requires a new tokenisation. Server-side only.
**Parameters**
- `card_id` (string; path; required) — ID of the saved payment card
**Responses**
- `204` Done; the response has no body
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### Events
The eshop's event log and the public keys that verify the signature of a webhook.
#### List events
`GET /eshops/{goid}/events` · Operation ID: `get-eshops-goid-events`
Requires: `merchant_credentials` (scopes: `event:read`)
Returns one page of the eshop's events, newest first.
Each page carries the URL of the next one in `next_page_url`, with the filters of the
request and the position to continue from already in it. The field is absent once the
last matching event has been returned.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `max_items` (integer; query; optional; default `20`; minimum 1; maximum 100) — Maximum number of events in one page
- `prev_item` (string; query; optional) — The `id` of the last event of the previous page. The page starts at the event after it.
GoPay writes the value into `next_page_url` and the caller follows that URL rather than
assembling the parameter. A value that has aged out of the 30-day window is rejected.
- `type` (string; query; optional) — The event types to include, comma-separated in a single parameter, up to 20 items. An item
is either an exact type (`payments.paid`) or a whole namespace (`payments.*`). An unknown
type is rejected. Omitted, every type matches.
- `occurred_after` (string (date-time); query; optional) — Include events that occurred at or after this instant. Must be earlier than `occurred_before` when both are given
- `occurred_before` (string (date-time); query; optional) — Include events that occurred before this instant
- `related_type` (string; query; optional; values: `payments`, `links`, `refunds`, `recurrences`, `cards`) — The kind of entity `related_id` refers to. Required together with `related_id`
- `related_id` (string; query; optional) — Include only events that carry this identifier, whichever position it appears in within
`data`. Required together with `related_type`.
**Responses**
- `200` One page of the eshop's events, newest first — [Event-List](#schema-Event-List)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Event details
`GET /eshops/{goid}/events/{event_id}` · Operation ID: `get-eshops-goid-events-event_id`
Requires: `merchant_credentials` (scopes: `event:read`)
Returns a single event of the eshop by its `id`.
**Parameters**
- `goid` (string; path; required) — Unique identifier of a registered merchant website
- `event_id` (string; path; required) — Identifier of the event
**Responses**
- `200` The event — [Event](#schema-Event)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Fetch webhook signing keys
`GET /webhooks/public-keys` · Operation ID: `get-webhooks-public-keys`
Requires: `shareable_key` or `merchant_credentials` (scopes: `shared:read`)
Returns the public keys that verify the signature of a webhook.
The keys are structured as a JWK Set described by
[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517). Several keys may be published at
once while a key is being rotated.
**Responses**
- `200` The webhook signing keys currently in use — [JWK-Set](#schema-JWK-Set)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
### SDK Services
Operations the GoPay client SDKs call from the customer's browser or app while collecting card or wallet data for a charge. The merchant's code does not normally call them. When the merchant's server performs the charge, it needs the browser data, which the GoPay client SDK also collects for it. The operations are documented for fully custom integrations; a custom card-data integration additionally requires a PCI DSS SAQ.
#### Google Pay Payment Info
`GET /payments/{payment_id}/google-pay/info` · Operation ID: `get-payments-payment_id-info-google-pay`
Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)
Returns the Google Pay payment request configuration for the payment.
Intended for the GoPay client SDK; the merchant's code does not normally call it. The same endpoint serves both the web and the in-app case — the configured environment is carried in `environment`.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `200` Google Pay payment request configuration consumed by the Google Pay button — object
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Apple Pay Payment Info
`GET /payments/{payment_id}/apple-pay/info` · Operation ID: `get-payments-payment_id-info-apple-pay`
Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)
Returns the Apple Pay payment request configuration for the payment on the web.
Intended for the GoPay client SDK; the merchant's code does not normally call it.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `200` Apple Pay payment request object consumed by the Apple Pay button — object
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Apple Pay Payment Info For Apps
`GET /payments/{payment_id}/apple-pay/app-info` · Operation ID: `get-payments-payment_id-apple-pay-app-info`
Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)
Returns the Apple Pay payment request configuration for the payment in a native application. It carries `paymentSummaryItems` where the web variant carries a single `total`.
Intended for the GoPay client SDK; the merchant's code does not normally call it.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
**Responses**
- `200` Apple Pay payment request object for a native application — object
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Validate Merchant
`POST /payments/{payment_id}/apple-pay/validate` · Operation ID: `post-payments-payment_id-apple-pay-validate`
Requires: `payment_credentials` (scopes: `payment:read`) or `merchant_credentials` (scopes: `payment:read`)
Completes the Apple Pay merchant validation handshake for the payment session.
The `validationUrl` issued by Apple is forwarded to GoPay, which returns the merchant session that the Apple Pay sheet expects. Intended for the GoPay client SDK; the merchant's code does not normally call it.
**Parameters**
- `payment_id` (string; path; required) — Identifier of the payment, `Payment Details.id`
- `Origin` (string; header; required) — The origin of the page where the Apple Pay button is displayed. The browser adds it automatically
**Request body** (required)
`application/json`: [Validate-Merchant-Request](#schema-Validate-Merchant-Request)
**Responses**
- `200` The merchant session for the Apple Pay sheet — [Validate-Merchant-Response](#schema-Validate-Merchant-Response)
- `400` Bad Request — [Error-Response-Body](#schema-Error-Response-Body)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `404` Not Found — [Error-Response-Body](#schema-Error-Response-Body)
- `409` Conflict — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Fetch public key
`GET /cards/public-key` · Operation ID: `get-encryption-public-key`
Requires: `shareable_key` or `merchant_credentials` (scopes: `shared:read`)
Returns the public encryption key to be used for encrypting card data.
It is structured as a JWK described by [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).
Intended for the GoPay client SDK; the merchant's code does not normally call it.
**Responses**
- `200` The public encryption key — [JWK](#schema-JWK)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Card Form URL
`GET /cards/card-form-url` · Operation ID: `get-card-form-url`
Requires: `shareable_key` or `merchant_credentials` (scopes: `shared:read`)
Returns the URL of the hosted card input form.
Intended for the GoPay browser SDK, which embeds the form; the merchant's code does not normally call it.
**Responses**
- `200` The URL of the hosted card form — [Card-Form-URL](#schema-Card-Form-URL)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
#### Fetch browser data
`GET /cards/browser-data` · Operation ID: `get-browser-data`
Requires: `shareable_key`
Returns the `Browser Data` fields that the customer's browser cannot determine on its own — the source IP address, the `User-Agent` header, and the `Accept` headers — derived from the request that fetched them.
The GoPay client SDK calls it from the customer's browser or device immediately before a charge. A call made from the merchant's server returns the server's own values, which the card issuer rejects during 3-D Secure authentication.
**Responses**
- `200` The browser data derived from the request — [Browser-Data-Detected](#schema-Browser-Data-Detected)
- `401` Unauthorized — [Error-Response-Body](#schema-Error-Response-Body)
- `403` Forbidden — [Error-Response-Body](#schema-Error-Response-Body)
- `500` Internal Server Error — [Error-Response-Body](#schema-Error-Response-Body)
## Schemas
### Client-Credentials-Request
**Client Credentials Request**
Requests a merchant access token with the `client_credentials` grant
Type: `object`
- `grant_type` (string = `"client_credentials"`; required; example `"client_credentials"`) — Always `client_credentials` for this flow
- `scope` (string; required; example `"payment:write payment:read"`) — List of required token scopes, separated with a space.
- `payment:read` reads payments and the resources built on them, such as charges, refunds, recurrences and payment links
- `payment:write` creates, charges, cancels and modifies payments and those same resources
- `card:read` reads saved card tokens
- `card:write` saves and deletes card tokens
- `event:read` reads the eshop's events
- `shared:read` reads public resources such as public keys
### Payment-Credentials-Request
**Payment Credentials Request**
Requests a payment-scoped access token with the `payment_credentials` grant
Type: `object`
- `grant_type` (string = `"payment_credentials"`; required; example `"payment_credentials"`) — Always `payment_credentials` for this flow
- `scope` (string; required; example `"payment:charge payment:read"`) — List of required token scopes, separated with a space.
- `payment:read` reads the payment
- `payment:charge` charges the payment
### Access-Token
**Access Token**
The access token and its meta information.
Type: `object`
- `token_type` (string = `"bearer"`; optional; default `"bearer"`; example `"bearer"`) — Always `bearer`
- `access_token` ([JWT](#schema-JWT); optional) — The access token, presented as a Bearer token
- `scope` (string; optional; example `"payment:write payment:read"`) — Space-separated list of token scopes.
- `expires_in` (integer; optional; minimum 0; example `900`) — The expiration of the access JWT in seconds
### JWT
The JWT string as described by [RFC 7519: JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
The JWT claims contain:
- `sub` -> the Client ID for which the token was issued
- `scope` -> the scopes of the token
- `iat` -> timestamp of token issuing
- `exp` -> timestamp of token expiration
- `domain` -> `merchant` for tokens issued to the merchant's server with the `client_credentials` grant, `payment` for payment-scoped tokens issued with the `payment_credentials` grant to the GoPay client SDK
Type: `string`
### Payment-Create-Request
**Payment Create Request**
Representation of a request for a new payment
Type: `object`
- `amount` (integer; required; minimum 0; example `100`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `order_number` (string; required; max length 128; example `"2025010199"`) — Order identification for the online shop, alphanumeric characters
- `order_description` (string; optional; example `"Test order"`) — Order description, alphanumeric characters
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); optional; max items 4) — Additional parameters for the payment
- `customer` ([Customer](#schema-Customer); required) — Information about the customer
- `callback` ([Payment-Callback](#schema-Payment-Callback); required) — URLs for the return redirect and the notifications
Example:
```json
{
"amount": 100,
"currency": "CZK",
"order_number": "2025010199",
"order_description": "Test order",
"additional_params": [
{
"name": "Custom param",
"value": "Custom value"
}
],
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+420123456789",
"city": "Testington",
"street": "Example st. 10",
"postal_code": "10000",
"country_code": "CZE",
"customer_id": "customer420"
},
"callback": {
"notification_url": "https://example.com/notify",
"return_url": "https://example.com/return"
}
}
```
### Currency
Supported payment currencies in ISO 4217 format
Type: `string`
Values: `CZK`, `EUR`, `PLN`, `USD`, `GBP`, `HUF`, `RON`
### Additional-Param
**Additional Parameter**
Additional payment parameters
Type: `object`
- `name` (string; required; example `"Custom param"`) — Parameter name
- `value` (string; required; example `"Custom value"`) — Parameter value
Example:
```json
{
"name": "Custom param",
"value": "Custom value"
}
```
### Payment-Details
**Payment Details**
Representation of an existing payment
Type: `object`
- `id` (string; required; example `"300000001"`) — Identifier of the payment
- `order_number` (string; required; example `"2025010199"`) — Order number given when the payment was created
- `state` ([Payment-State](#schema-Payment-State); required) — Payment state
- `amount` (integer; required; example `100`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `customer` ([Customer](#schema-Customer); required) — Customer data
- `gw_url` (string (uri); required; example `"https://gate.gopay.com/gw/123456789"`) — Address of GoPay's hosted payment gateway for this payment, used by the Redirect
integration. It offers the customer every payment method the eshop has enabled,
and GoPay drives the payment while the customer is on it. It is a destination the
customer is sent to and cannot be embedded in the merchant's own checkout.
`GET /payments/{payment_id}` reports the outcome of a payment paid there in the
same way as for any other payment.
- `charge` ([Payment-Charge-Status-Response](#schema-Payment-Charge-Status-Response); optional) — The payment's charge, once a charge has been attempted
- `payment_secret` (string; required; example `"ps_4d2f9a51b7e30c68a1c5e9f03b7d2e46"`) — Payment secret that the merchant's server passes to the GoPay client SDK, so that the SDK can act on this payment. **Do not embed in URLs, log or store!**
### Customer
Customer details associated with the payment. The email address is required as it is used for authentication and notification purposes.
Type: `object`
- `email` (string (email); required; max length 128; example `"john.doe@example.com"`) — Customer email
- `first_name` (string; optional; max length 256; example `"John"`) — Customer first name
- `last_name` (string; optional; max length 256; example `"Doe"`) — Customer last name
- `phone_number` (string; optional; max length 128; example `"+420123456789"`) — Customer phone number (home or mobile)
- `city` (string; optional; max length 128; example `"Testington"`) — Customer address city
- `street` (string; optional; max length 128; example `"Example st. 10"`) — Customer address street
- `postal_code` (string; optional; max length 128; example `"10000"`) — Customer address ZIP (postal code)
- `country_code` (string; optional; max length 128; example `"CZE"`) — Customer country code according to [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
- `customer_id` (string; optional; max length 128; example `"customer420"`) — Unique customer ID (used to customise the checkout experience)
Example:
```json
{
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+420123456789",
"city": "Testington",
"street": "Example st. 10",
"postal_code": "10000",
"country_code": "CZE",
"customer_id": "customer420"
}
```
### Payment-Callback
**Payment Callback**
Object holding URLs for callback purposes related to a payment
Type: `object`
- `notification_url` (string; required; example `"https://example.com/notify"`) — URL that receives a notification whenever the state of the payment changes
- `return_url` (string; required; example `"https://example.com/return"`) — URL the customer's browser is sent to at the end of the hosted gateway flow, and after the 3-D Secure step in a checkout integration. It must not carry a fragment (`#…`)
Example:
```json
{
"notification_url": "https://example.com/notify",
"return_url": "https://example.com/return"
}
```
### Payment-State
**Payment State**
The lifecycle state of a payment.
- `CREATED` - The payment exists and is awaiting a charge attempt
- `PAID` - The payment was charged successfully
- `CANCELED` - The customer abandoned the payment, the charge was rejected at authorisation, or the merchant canceled the payment before it was charged
- `PAYMENT_METHOD_CHOSEN` - A charge attempt is in flight and its outcome is not known yet
- `TIMEOUTED` - The payment did not reach a terminal outcome within its timeout
- `AUTHORIZED` - The payment has been authorised but not yet captured; only relevant for the pre-authorisation flow
- `REFUNDED` - The payment has been fully refunded
- `PARTIALLY_REFUNDED` - The payment has been partially refunded
Type: `string`
Values: `CREATED`, `PAID`, `CANCELED`, `PAYMENT_METHOD_CHOSEN`, `TIMEOUTED`, `AUTHORIZED`, `REFUNDED`, `PARTIALLY_REFUNDED`
### Charge-State
**Charge State**
The lifecycle state of a payment charge.
- `REQUESTED` - The charge has been initiated
- `PROCESSING` - The charge is being processed by the payment provider
- `ACTION_REQUIRED` - The customer must complete a step, such as 3-D Secure authentication, before the charge can continue
- `SUCCEEDED` - The charge completed successfully
- `FAILED` - The charge failed
Type: `string`
Values: `REQUESTED`, `PROCESSING`, `ACTION_REQUIRED`, `SUCCEEDED`, `FAILED`
### Payment-Charge-Data
**Payment Charge Data**
The payment instrument used for the charge. The `payment_instrument` field selects the case, taking values from the [Payment Instrument](#schema-Payment-Instrument) enum.
Type: `oneOf`
One of: [Payment-Card-Charge-Data](#schema-Payment-Card-Charge-Data)
Discriminator: `payment_instrument` (`PAYMENT_CARD` → [Payment-Card-Charge-Data](#schema-Payment-Card-Charge-Data))
### Payment-Charge-Input
**Payment Charge Input**
Model holding all data necessary to perform a payment charge
Type: `object`
- `payment_instrument` ([Payment-Charge-Data](#schema-Payment-Charge-Data); required) — Payment instrument data specifying how the payment should be charged
### Payment-Instrument
**Payment Instrument**
The values of the field that selects the case of [Payment Charge Data](#schema-Payment-Charge-Data)
Type: `string`
Values: `PAYMENT_CARD`
### Payment-Card-Charge-Data
**Payment Card Charge Data**
The `PAYMENT_CARD` variant of the [Payment Charge Data](#schema-Payment-Charge-Data) union. Holds the card input, the browser data and the 3-D Secure preference.
Type: `object`
- `payment_instrument` (string = `"PAYMENT_CARD"`; required) — Always `PAYMENT_CARD`
- `input` ([Payment-Card-Input](#schema-Payment-Card-Input); required) — One of the possible inputs for a card payment
- `browser_data` ([Browser-Data](#schema-Browser-Data); required)
- `challenge_preference` ([Payment-Card-Challenge-Preference](#schema-Payment-Card-Challenge-Preference); optional)
### Payment-Card-Input
**Payment Card Input**
The card the payment is charged with. The `input_type` field selects the case, taking values from the [Payment Card Input Type](#schema-Payment-Card-Input-Type) enum.
Type: `oneOf`
One of: [Card-Token-Input](#schema-Card-Token-Input), [Google-Pay-Input](#schema-Google-Pay-Input), [Apple-Pay-Input](#schema-Apple-Pay-Input), [Encrypted-Card-Input](#schema-Encrypted-Card-Input)
Discriminator: `input_type` (`CARD_TOKEN` → [Card-Token-Input](#schema-Card-Token-Input), `GOOGLE_PAY` → [Google-Pay-Input](#schema-Google-Pay-Input), `APPLE_PAY` → [Apple-Pay-Input](#schema-Apple-Pay-Input), `ENCRYPTED_CARD` → [Encrypted-Card-Input](#schema-Encrypted-Card-Input))
### Payment-Card-Input-Type
**Payment Card Input Type**
The values of the field that selects the case of [Payment Card Input](#schema-Payment-Card-Input)
Type: `string`
Values: `CARD_TOKEN`, `APPLE_PAY`, `GOOGLE_PAY`, `ENCRYPTED_CARD`
### Card-Token-Input
**Card Token Input**
The `CARD_TOKEN` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries a saved card token
Type: `object`
- `input_type` (string = `"CARD_TOKEN"`; required) — Always `CARD_TOKEN`
- `card_token` (string; required; example `"J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjG..."`) — Permanent card token acquired using the [Create Card Token](#operation-post-cards-tokens) API call
### Payment-Card-Challenge-Preference
**Payment Card Challenge Preference**
The merchant's preference for the 3-D Secure authentication of a card payment.
- `AUTO` - let GoPay decide
- `CHALLENGE_PREFERRED` - ask for a 3-D Secure challenge for stronger authentication; it may still be skipped, for example for Apple Pay
- `NO_CHALLENGE_PREFERRED` - ask to skip the challenge; the card issuer can still require one
Type: `string`
Values: `CHALLENGE_PREFERRED`, `NO_CHALLENGE_PREFERRED`, `AUTO`
### Google-Pay-Input
**Google Pay Input**
The `GOOGLE_PAY` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries the payment data returned by Google Pay.
See [Payment Data Cryptography](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography) in Google Pay documentation for details.
Type: `object`
- `input_type` (string = `"GOOGLE_PAY"`; optional; example `"GOOGLE_PAY"`) — Always `GOOGLE_PAY`
- `protocolVersion` (string; optional; example `"ECv2"`) — Version of the Google Pay API protocol used to encrypt the payment data
- `signature` (string; optional; example `"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q=="`) — Digital signature of the payment data
- `intermediateSigningKey` (object; optional) — Intermediate signing key from Google used to verify the signature
- `signedKey` (string; optional; example `"{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw==\"}"`) — JSON-encoded string containing the key value and expiration
- `signatures` (array of string; optional) — Signatures of the intermediate signing key
- `signedMessage` (string; optional; example `"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U=\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs=\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"`) — JSON-encoded string containing the encrypted payment data
### Apple-Pay-Input
**Apple Pay Input**
The `APPLE_PAY` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries the payment token returned by Apple Pay.
See [Payment token format reference](https://developer.apple.com/documentation/passkit/payment-token-format-reference) in the Apple Pay documentation for details.
Type: `object`
- `input_type` (string = `"APPLE_PAY"`; required; example `"APPLE_PAY"`) — Always `APPLE_PAY`
- `data` (string; required; example `"V7OcjttPJnUJaQH7x7OjbIeZSINuc..."`) — Encrypted payment data from the Apple Pay token
- `signature` (string; required; example `"MIAGCSqGSIb3DQEHAqCAM..."`) — Signature of the payment and header data, signed by Apple
- `version` (string; required; example `"EC_v1"`) — Version of the Apple Pay payment token format
- `header` (object; required) — Header containing additional data for decrypting and verifying the payment token
- `applicationData` (string; optional; example `"94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4"`) — Hash of the `applicationData` carried on the Apple Pay payment request. Apple includes it only for sessions created with that value, so the field is optional; forward it unchanged when the Apple Pay session returns it
- `ephemeralPublicKey` (string; required; example `"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw=="`) — Ephemeral public key used for deriving the shared secret
- `publicKeyHash` (string; required; example `"L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo="`) — SHA-256 hash of the merchant's public key certificate
- `transactionId` (string; required; example `"4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5"`) — Unique transaction identifier generated by Apple Pay
Example:
```json
{
"input_type": "APPLE_PAY",
"data": "V7OcjttPJnUJaQH7x7OjbIeZSINuc...",
"signature": "MIAGCSqGSIb3DQEHAqCAM...",
"version": "EC_v1",
"header": {
"applicationData": "94ee059335e587e5f6b717fb172c5c3841659d892a84b7c6c47d0d13c58f7ea4",
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwpd0HT6uOdE2pZTBZXsJF7IK7EvJQDq4LnQS5B5g8fiD9sEZNt4P9DhWRO44kEbbyiQ1FVgPcSsvJ2Z5I+qPTw==",
"publicKeyHash": "L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=",
"transactionId": "4f4fac7a179ae30ce4c839e85efa4a34811a5ea2af88280c847a6a8ba2c0e8c5"
}
}
```
### Bank-Swift
**Bank Swift**
SWIFT/BIC code identifying a supported bank. Use `OTHERS` for banks not explicitly listed.
- `GIBACZPX` - Česká spořitelna (Czech Republic)
- `KOMBCZPP` - Komerční banka (Czech Republic)
- `SUBASKBX` - VÚB banka (Slovakia)
- `GIBASKBX` - Slovenská sporiteľňa (Slovakia)
- `OTHERS` - Any other supported bank
Type: `string`
Values: `GIBACZPX`, `KOMBCZPP`, `SUBASKBX`, `GIBASKBX`, `OTHERS`
### Browser-Data
**Browser Data**
Customer browser data collected for 3-D Secure authentication purposes. This data is forwarded to the card issuer during the authentication flow.
Type: `object`
- `language` (string; required; example `"cs-CZ"`) — Language or locale of the customer environment
- `timezone` (integer; required; example `-60`) — Timezone offset of the customer environment in minutes (e.g. -60 for CET)
- `screen_width` (integer; required; example `434`) — Width of the customer's screen in pixels
- `screen_height` (integer; required; example `965`) — Height of the customer's screen in pixels
- `color_depth` (integer; required; example `24`) — Color depth of the customer's screen in bits
- `user_agent` (string; required; example `"Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36"`) — User-Agent string of the customer's browser, as returned by the browser data endpoint. Take it from the same source as `ip` — a pair that disagrees fails 3-D Secure authentication
- `accept_header` (string; required; example `"{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}"`) — JSON-encoded Accept headers from the customer's browser, as returned by the browser data endpoint. Take it from the same source as `ip`
- `javascript_enabled` (boolean; required; example `true`) — Whether JavaScript is enabled in the customer's browser
- `ip` (string; required; max length 45; example `"192.0.2.42"`) — IP address of the customer's browser, as returned by the browser data endpoint. A merchant's server charging on the customer's behalf must forward the value collected in the browser, never its own address
### Browser-Data-Detected
**Browser Data Detected**
The `Browser Data` fields the customer's browser cannot determine on its own, derived from the request that fetched them.
Merge them into `Browser Data` when charging the payment.
Type: `object`
- `ip` (string; required; max length 45; example `"192.0.2.42"`) — IP address the request originated from
- `user_agent` (string; required; example `"Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Mobile Safari/537.36"`) — User-Agent header sent with the request
- `accept_header` (string; required; example `"{\"accept-language\":\"cs;q=0.5\",\"accept-encoding\":\"gzip, deflate, br, zstd\",\"accept\":\"application/json, text/plain, */*\"}"`) — JSON-encoded Accept headers sent with the request
### Payment-Charge-Response
**Payment Charge Response**
The charge started by `POST /payments/{payment_id}/charge`: its state, the instrument used, and any step the customer must complete.
Type: `object`
- `id` (string; required; example `"9123456789"`) — Unique identifier of the charge
- `state` ([Charge-State](#schema-Charge-State); required) — Current state of the charge
- `payment_instrument` ([Payment-Instrument-Data](#schema-Payment-Instrument-Data); required) — Details of the payment instrument used for this charge
- `action` ([Payment-Charge-Action](#schema-Payment-Charge-Action); optional) — The step the customer must complete, such as 3-D Secure authentication. Present when `state` is `ACTION_REQUIRED`
### Payment-Charge-Status-Response
**Payment Charge Status Response**
The current state of the payment's charge, the instrument used, any step the customer must complete and, for a failed charge, the reason.
Type: `object`
- `id` (string; required; example `"9123456789"`) — Unique identifier of the charge
- `state` ([Charge-State](#schema-Charge-State); required) — Current state of the charge
- `payment_instrument` ([Payment-Instrument-Data](#schema-Payment-Instrument-Data); optional) — Details of the payment instrument used for this charge
- `action` ([Payment-Charge-Action](#schema-Payment-Charge-Action); optional) — The step the customer must complete, such as 3-D Secure authentication. Present when `state` is `ACTION_REQUIRED`
- `fail_reason` (string; optional; example `"Issuer declined the authorisation"`) — Reason for the charge's failure. Only present when state is `FAILED`
### Payment-Instrument-Data
**Payment Instrument Data**
The payment instrument a charge used. The `payment_instrument` field selects the case, taking values from the [Payment Instrument](#schema-Payment-Instrument) enum.
Type: `oneOf`
One of: [Payment-Card-Instrument-Out](#schema-Payment-Card-Instrument-Out)
Discriminator: `payment_instrument` (`PAYMENT_CARD` → [Payment-Card-Instrument-Out](#schema-Payment-Card-Instrument-Out))
Example:
```json
{
"payment_instrument": "PAYMENT_CARD",
"details": {
"input_type": "CARD_TOKEN",
"masked_pan": "406821******1234",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"fingerprint": "73c8d0a48d91def89761..."
}
}
```
### Payment-Card-Instrument-Out
**Payment Card Instrument Out**
The `PAYMENT_CARD` variant of the Payment Instrument Data union. Contains the card-specific details of the instrument used in a charge.
Type: `object`
- `payment_instrument` ([Payment-Instrument](#schema-Payment-Instrument); required) — Always `PAYMENT_CARD`
- `details` ([Payment-Card-Charge-Details](#schema-Payment-Card-Charge-Details); optional) — Card-specific details of the payment instrument
Example:
```json
{
"payment_instrument": "PAYMENT_CARD",
"details": {
"input_type": "CARD_TOKEN",
"masked_pan": "406821******1234",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"fingerprint": "73c8d0a48d91def89761..."
}
}
```
### Payment-Card-Charge-Details
**Payment Card Charge Details**
Output details of a card payment instrument as returned in a charge response. Contains masked card data identifying the card used.
Type: `object`
- `input_type` ([Payment-Card-Input-Type](#schema-Payment-Card-Input-Type); required) — The type of card input that was used for the charge
- `masked_pan` (string; optional; example `"406821******1234"`) — Masked primary account number with only the first six and last four digits visible
- `expiration_month` (string; optional; pattern `^(?:0[0-9]|1[0-2])$`; example `"01"`) — Card expiration month (01–12)
- `expiration_year` (string; optional; pattern `^[0-9]{2}$`; example `"30"`) — Card expiration year (two-digit format)
- `scheme` ([Card-scheme](#schema-Card-scheme); optional) — Card network scheme
- `fingerprint` (string; optional; example `"73c8d0a48d91def89761..."`) — A unique hash identifying the physical card
Example:
```json
{
"input_type": "CARD_TOKEN",
"masked_pan": "406821******1234",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"fingerprint": "73c8d0a48d91def89761..."
}
```
### Card-scheme
**Card Scheme**
The card network scheme (VISA or MASTERCARD)
Type: `string`
Values: `VISA`, `MASTERCARD`
### Payment-Charge-Action
**Payment Charge Action**
A step the customer must complete before the charge can continue, such as 3-D Secure authentication on the card issuer's page. The `action_type` field selects the case.
Type: `oneOf`
One of: [Emv-3DS-Action](#schema-Emv-3DS-Action)
Discriminator: `action_type` (`EMV3DS` → [Emv-3DS-Action](#schema-Emv-3DS-Action))
Example:
```json
{
"action_type": "EMV3DS",
"state": "CREATED",
"redirect_url": "https://gate.gopay.com/redirect"
}
```
### Payment-Charge-Action-Type
**Payment Charge Action Type**
The values of the field that selects the case of Payment Charge Action.
- `EMV3DS` - EMV 3-D Secure authentication for card payments
Type: `string`
Values: `EMV3DS`
### Emv-3DS-Action
**Emv 3DS Action**
The `EMV3DS` variant of the Payment Charge Action union. Represents an EMV 3-D Secure authentication action for card payments.
Type: `object`
- `action_type` ([Payment-Charge-Action-Type](#schema-Payment-Charge-Action-Type); required) — Always `EMV3DS`
- `state` ([Emv-3DS-State](#schema-Emv-3DS-State); required) — Current state of the 3-D Secure authentication
- `redirect_url` (string (uri); optional; example `"https://gate.gopay.com/redirect"`) — URL the customer's browser is sent to for the 3-D Secure step. Present while the charge is in `ACTION_REQUIRED`
Example:
```json
{
"action_type": "EMV3DS",
"state": "CREATED",
"redirect_url": "https://gate.gopay.com/redirect"
}
```
### Emv-3DS-State
**Emv 3DS State**
The lifecycle state of an EMV 3-D Secure authentication.
- `CREATED` - The 3-D Secure authentication has been initiated
- `CHALLENGE_REQUIRED` - The customer must complete a 3-D Secure challenge, such as a one-time code or a confirmation in the banking app
- `AUTHENTICATED_CHALLENGE` - The customer was authenticated through a challenge
- `AUTHENTICATED_FRICTIONLESS` - The customer was authenticated without a challenge (frictionless flow)
- `NOT_AUTHENTICATED` - The 3-D Secure authentication was not completed
- `FAILED` - The 3-D Secure authentication failed
Type: `string`
Values: `CREATED`, `CHALLENGE_REQUIRED`, `AUTHENTICATED_CHALLENGE`, `AUTHENTICATED_FRICTIONLESS`, `NOT_AUTHENTICATED`, `FAILED`
### QR-Payment-Details
**QR Payment Details**
Details of a QR code payment including the payment amount, recipient bank account information, and the generated QR codes in various formats.
Type: `object`
- `amount` (integer; required; example `10000`) — Payment amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `recipient` ([Bank-Transfer-Recipient](#schema-Bank-Transfer-Recipient); required) — Information about the recipient
- `qr_code` ([QR-Code-List](#schema-QR-Code-List); required) — Generated QR code images in various regional formats
### Bank-Transfer-Recipient
**Bank Transfer Recipient**
Information about the recipient of a bank transfer payment, including their name, bank account details, and address.
Type: `object`
- `name` (string; optional; example `"GoPay Czech"`) — Name of the payment recipient
- `bank_account` ([Recipient-Bank-Account](#schema-Recipient-Bank-Account); optional) — Bank account details of the recipient in both local and international formats
- `address` ([Recipient-Address](#schema-Recipient-Address); optional) — Physical address of the recipient
### Recipient-Bank-Account
**Recipient Bank Account**
Recipient bank account details provided in both local (country-specific) and international (IBAN/SWIFT) formats.
Type: `object`
- `local` ([Bank-Account-Local-Details](#schema-Bank-Account-Local-Details); optional) — Bank account details in the local (country-specific) format
- `international` ([Bank-Account-International-Details](#schema-Bank-Account-International-Details); optional) — Bank account details in the international IBAN/BIC format
### Bank-Account-Local-Details
**Bank Account Local Details**
Bank account details in the local Czech/Slovak format, including the account number prefix, bank code, and variable symbol for payment identification.
Type: `object`
- `prefix` (string; required; example `"000000"`) — Account number prefix (may be all zeros)
- `account_number` (string; required; example `"9878039"`) — The local bank account number
- `bank_code` (string; required; example `"2010"`) — Numeric bank code identifying the bank
- `variable_symbol` (string; required; example `"3123456789"`) — Variable symbol used to match the payment to an order
### Bank-Account-International-Details
**Bank Account International Details**
Bank account details in the international IBAN/BIC format, used for cross-border and SEPA payments.
Type: `object`
- `bic` ([Bank-Swift](#schema-Bank-Swift); optional) — BIC (Bank Identifier Code) / SWIFT code of the bank
- `iban` (string; optional; example `"CZ5120100000000009878039"`) — International Bank Account Number
- `reference` (string; optional; example `"3123456789"`) — Payment reference number used to match the payment to an order
### Recipient-Address
**Recipient Address**
Physical address of the payment recipient.
Type: `object`
- `street` (string; optional; example `"Senovazne nam. 1736"`) — Street address including the building number
- `city` (string; optional; example `"Ceske Budejovice"`) — City name
- `zip_code` (string; optional; example `"37001"`) — ZIP or postal code
- `country` (string; optional; example `"Czech Republic"`) — Country name
### QR-Code-List
**QR Code List**
A collection of QR code images in various regional formats, each encoded as a base64 string. The available formats depend on the payment currency and recipient country.
Type: `object`
- `spayd` (string; optional; example `"iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAklEQVR4AewaftIAAAglSURBVO3BUa4cuZYEwXCi9r9lH30WDh6RBJVXrekOM/wlVfU/rVTV1kpVba1U1dZKVW2tVNXWSlVtrVTV1kpVba1U1dYnh4D8DdRMQE6omYBMat4CZFIzATmhZgLyk9ScADKpmYD8DdQ8WamqrZWq2lqpqq2Vqtr65Deo+WlA3gJkUnMLyBM1t9RMQCY1E5BvaiYgJ4CcUHNDzU8DcmOlqrZWqmprpaq2Vqpq65OXAbml5i1qJiATkEnNBOQtQN4EZFLzFjUngExqbgC5peYtK1W1tVJVWytVtbVSVVuf/AuomYC8Sc0TILfUTEAmNSeAfFNzQs0EZFLzX7BSVVsrVbW1UlVbK1W19cm/AJBJzQRkUnMCyKTmCZATQCY1E5BJzaTmG5A3AZnU/NusVNXWSlVtrVTV1kpVbX3yMjV/mpoTak4AOQHkiZoJyJuATGp+kpoJyKTmhpq/wUpVba1U1dZKVW2tVNXWJ78ByN8AyKRmAjKpOaFmAvJNzQRkUjMBuaVmAvJNzQTkbwDkb7VSVVsrVbW1UlVb+Ev+hYBMam4BmdR8AzKpuQXklppvQCY1E5ATav4LVqpqa6WqtlaqamulqrY+OQRkUnMCyN8AyKRmAjKpuQFkUjMBmdRMQG6omYBMak4AuaXmCZBJzQTklponK1W1tVJVWytVtbVSVVufHFIzAZnUTGpOAJnUPAHyJjUTkCdqTgCZ1NxSMwH5puafoGYC8hY1P2mlqrZWqmprpaq2Vqpq65NDQCY1Pw3IEzX/BDU31NxSc0LNW4BMak4AmdR8AzKpOQFkUvOWlaraWqmqrZWq2lqpqi38Jf8AIJOaJ0AmNSeAnFBzAsgTNROQSc0tIDfU3ALyk9RMQCY1E5ATap6sVNXWSlVtrVTV1kpVbX3yG4BMat4E5AaQE2omIDfUTEAmNSeATGpOqLkB5E1qngCZgExqTqiZgNxYqaqtlaraWqmqrZWq2vrkEJBbQG6p+QbkTUAmNROQtwCZ1ExqTqiZgHxTMwGZ1ExAJjUngExqfhKQSc2NlaraWqmqrZWq2lqpqi38JZeAnFBzC8g3NROQSc0E5ISaCcik5gaQSc0tIDfUTED+NDUngJxQMwGZ1DxZqaqtlaraWqmqLfwlB4BMaiYgJ9S8BcgJNROQE2reAuSEmgnIpOYJkFtqJiBvUXMLyKTmLStVtbVSVVsrVbW1UlVb+EsuAZnUnAByQ80EZFIzAZnUnADyk9RMQG6puQFkUnMCyKTmCZATav60laraWqmqrZWq2lqpqq1P/gAgt9R8AzKpOaHmlpobQCY1E5BJzQRkUnMDyKTmlpoJyBM1t4BMaiYgk5onK1W1tVJVWytVtbVSVVuf/AY1E5BJzQTkBJC3ALmlZgLyRM1PA3JDzQkgk5oTap4AOaFmUvOTVqpqa6WqtlaqamulqrY++Q1Abql5C5CfBmRS8xY1J9S8BcikZlIzAZnUnADyFiCTmresVNXWSlVtrVTV1kpVbeEvOQBkUjMBOaFmAvJEzQkgk5oTQP4Gak4AeaLmBJATaiYgb1EzAZnUnAAyqXmyUlVbK1W1tVJVWytVtfXJy9RMQG6peQLkFpBJzQkg39TcAjIB+UlAJjVvUjMBeQLkBJBJzaTmxkpVba1U1dZKVW2tVNUW/pIXAZnUnADyRM0JIJOanwTkTWomIJOaCcifpmYCMqn5SUBOqHmyUlVbK1W1tVJVW58cAvImICfUPAEyqTkBZFLzFjUTkEnNBGRSMwF5i5oJyKRmAjKpmYC8Rc2kZgJyY6WqtlaqamulqrZWqmoLf8klIH+amgnICTUngExqngB5k5oTQCY1bwFyQs0E5ImaCcgtNROQSc2TlaraWqmqrZWq2lqpqq1PDgE5oWYCMqmZgExqvgGZ1LxJzQkg39RMQE6omYCcUPOT1ExA3gLkhJoJyATkLStVtbVSVVsrVbW1UlVbn/zlgHxTMwF5k5oTam6oeROQJ2omIJOaW0AmNROQb2pOAJnUTEDeslJVWytVtbVSVVsrVbX1yW9QMwGZ1ExAJjVPgExqfhqQSc03IJOaCcgJNROQE2qeqJmATGpOqJmA3AByAsgJNTdWqmprpaq2Vqpqa6WqtvCXHAAyqTkBZFIzAXmLmgnICTUTkCdqJiCTmjcBeYuaW0B+kppbQCY1T1aqamulqrZWqmprpaq2Pjmk5paaE2puAJmAnFAzATmh5icBmdRMap4AOQFkUnNLzQ0gJ4BMat6yUlVbK1W1tVJVWytVtfXJISB/AzW31ExA3gLknwDkiZoJyKTmBJBbQL6peROQt6xU1dZKVW2tVNXWJ79BzU8DckPNLTU31JwAcgvIpGYC8kTNBGRSM6mZgJxQ8xY1E5C3rFTV1kpVba1U1dZKVW198jIgt9T8aWreAmRSM6k5AWRSMwG5AWRScwLICSB/mpq3rFTV1kpVba1U1dZKVW198h8CZFLzFjUTkEnNBGRSc0vNNyCTmgnIpGZSMwG5oWYCcgLIpGYCMql5slJVWytVtbVSVVsrVbX1yb+AmgnICSCTmhNAbgA5AeQnAZnUTEDepOYbkEnNCTUTkLesVNXWSlVtrVTV1kpVbX3yMjX/n6i5peYJkBNqJiC3gHxTcwLIpOZNQP40NTdWqmprpaq2Vqpqa6Wqtj75DUD+BkBuAZnUnADyRM0EZAIyqZmAvAXIpOYEkBNq3gLkFpBJzZOVqtpaqaqtlaraWqmqLfwlVfU/rVTV1kpVba1U1dZKVW2tVNXWSlVtrVTV1kpVbf0fJGLzp4ep9m8AAAAASUVORK5CYII="`) — QR code in the SPAYD (Short Payment Descriptor) format, commonly used in the Czech Republic. Encoded as a base64 image in the requested format.
- `paybysquare` (string; optional; example `"{QR code in base64}"`) — QR code in the Pay by Square format, commonly used in Slovakia. Encoded as a base64 image in the requested format.
- `sepa` (string; optional; example `"{QR code in base64}"`) — QR code in the SEPA (Single Euro Payments Area) format for EUR payments. Encoded as a base64 image in the requested format.
- `mnb_qr` (string; optional; example `"{QR code in base64}"`) — QR code in the MNB (Magyar Nemzeti Bank) format, commonly used in Hungary. Encoded as a base64 image in the requested format.
### Token-Create-Request
**Token Create Request**
Request body for creating a card token. Contains the encrypted card data.
Type: `object`
- `payload` ([JWE](#schema-JWE); required) — The encrypted card data payload in JWE compact serialization format
### Permanent-Card-Token-Details
**Permanent Card Token Details**
Details of a saved card token. The token is reused on later charges until it is deleted; issuer updates such as a new expiration date are applied to it in place.
Type: `object`
- `card_id` (string; required; example `"8007127320"`) — Unique identifier of the stored card token
- `masked_pan` (string; required; example `"406821******1234"`) — Masked primary account number with only the first six and last four digits visible
- `masked_virtual_pan` (string; required; example `"489537******6287"`) — Masked virtual PAN (network token) associated with the card
- `expiration_month` (string; required; pattern `^(?:0[0-9]|1[0-2])$`; example `"01"`) — Card expiration month (01–12)
- `expiration_year` (string; required; pattern `^[0-9]{2}$`; example `"30"`) — Card expiration year (two-digit format)
- `scheme` ([Card-scheme](#schema-Card-scheme); required) — Card network scheme
- `corporate` (boolean; required; default `false`; example `false`) — Whether the card is a corporate (business) card
- `fingerprint` (string; required; example `"73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b"`) — A unique hash identifying the physical card, stable across repeated tokenisations of the same card
- `token` (string; required; example `"J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv9DtCT3HLSlWHRYAbVTBLbouV77YtVSgavhi4uRZTwDy218Gog4MbZJ+umL/BkfFlNQ80PCdOjwYr8DtqZr71LHwkvg91ywirZp0="`) — The permanent card token value to be used in charge requests
- `card_art_url` (string (uri); required; example `"https://card.art/pic.png"`) — URL of the card art image provided by the issuing bank
- `brand` (string; optional; example `"GOLD"`) — Card brand or tier (e.g. GOLD, PLATINUM, STANDARD)
- `service_type` ([Card-Service-Type](#schema-Card-Service-Type); optional) — Whether the card is a debit or credit card
- `status` ([Card-Token-Status](#schema-Card-Token-Status); optional) — Current status of the stored card token
Example:
```json
{
"card_id": "8007127320",
"masked_pan": "406821******1234",
"masked_virtual_pan": "489537******6287",
"expiration_month": "01",
"expiration_year": "30",
"scheme": "VISA",
"corporate": false,
"fingerprint": "73c8d0a48d91def897612b54e630997745e1faad43045e732189cfe4acf4961b",
"token": "J7HjFNwzyBOHS+jwIMMktubTwoIRy6qB/4opvjGcKtjv9DtCT3HLSlWHRYAbVTBLbouV77YtVSgavhi4uRZTwDy218Gog4MbZJ+umL/BkfFlNQ80PCdOjwYr8DtqZr71LHwkvg91ywirZp0=",
"card_art_url": "https://card.art/pic.png",
"brand": "GOLD",
"service_type": "DEBIT"
}
```
### Card-Service-Type
**Card Service Type**
Indicates whether the card is a debit or credit card.
- `DEBIT` - Funds are drawn directly from the cardholder's bank account
- `CREDIT` - Funds are drawn from the cardholder's credit line
Type: `string`
Values: `DEBIT`, `CREDIT`
### Card-Token-Status
**Card Token Status**
Current status of a permanent card token.
- `ACTIVE` - The token is valid and can be used for payments
- `SUSPENDED` - The token is temporarily suspended and cannot be used
- `DELETED` - The token has been permanently deleted
Type: `string`
Values: `ACTIVE`, `SUSPENDED`, `DELETED`
### JWK
The structure of the public encryption key. It is formatted according to RFC 7517: JSON Web Key (JWK)
Type: `object`
- `kty` (string = `"RSA"`; required; example `"RSA"`) — Key type. Always `RSA` for the encryption keys used by GoPay.
- `use` (string = `"enc"`; required; example `"enc"`) — Key usage. Always `enc` (encryption).
- `kid` (string; required; example `"key_20250406"`) — Key ID
- `alg` (string; required; default `"RSA-OAEP-256"`; example `"RSA-OAEP-256"`) — Algorithm to be used for encryption with the key.
- `n` (string; required; example `"oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw"`) — The `RSA` public key modulus part.
- `e` (string; required; default `"AQAB"`; example `"AQAB"`) — The `RSA` public key exponent part.
Example:
```json
{
"kty": "RSA",
"kid": "key_20250406",
"use": "enc",
"alg": "RSA-OAEP-256",
"n": "oR79tj1xAaqr1TfmkGS03EfEZjU_5DMomKJXGK8cnmtGivG5XnFodcbztzSOrlrKmhoxrKRR0LiRRjYJIgTP3dGK9KOv7JRH4adnDClckQkxupwoz1dcm6cLDzjuVS1a4et8lQlwYKm5r52fG9VShckwNZgvmK0uYcE7717wLkX3JM2vA_F_-2oRCjG3l2E4cjhQzzstTFPkW35ZjuKut4If8LOnKH0h9tdblUOSB_VtZBNY6PCXeUTDfbCb85-eGrwWXEajq4uegPDbV2oSnTLxOXR8ctWURZ8XjS1PgsoDD4go9BQchv-9Q2m0NbS5s71WVJ9LOW7Xt-Napsoftw",
"e": "AQAB"
}
```
### JWE
The structure containing the encrypted payload. It is described by [RFC 7516: JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516)
It is produced by the GoPay client SDK.
Type: `string`
### Card-Form-URL
**Card Form URL**
The URL of the hosted card input form, which the GoPay browser SDK embeds in the merchant's page.
Type: `object`
- `card_form_url` (string; optional; example `"https://secure.gopay.com/gp-card-comm/q/form"`) — URL of the hosted card input form
### Error-Response-Body
**Error Response Body**
Standard error response body returned for all API error responses. Contains the HTTP status code, error type, a human-readable message, and additional diagnostic details.
Type: `object`
- `code` (integer; required; example `400`) — HTTP status code
- `error` (string; required; example `"BAD_REQUEST"`) — Error type
- `message` (string; required; example `"Invalid request parameter"`) — Error message
- `detail` (string; required; example ``"The field `payment_instrument` is required"``) — Detailed error description
- `path` (string; required; example `"/payments/123/charge"`) — Request path
- `timestamp` (string (date-time); required; example `"2025-12-10T10:30:00Z"`) — Error timestamp
### Encrypted-Card-Input
**Encrypted Card Input**
The `ENCRYPTED_CARD` variant of the [Payment Card Input](#schema-Payment-Card-Input) union. Carries a card the customer entered, encrypted by the GoPay client SDK. Single-use and valid for ten minutes.
Type: `object`
- `input_type` (string = `"ENCRYPTED_CARD"`; required; example `"ENCRYPTED_CARD"`) — Always `ENCRYPTED_CARD`
- `payload` ([JWE](#schema-JWE); required) — The encrypted card
### Refund-Create-Request
**Refund Create Request**
The amount to refund from a paid payment
Type: `object`
- `amount` (integer; required; minimum 1; example `100`) — Amount to be refunded in cents. For a full amount, set it equal to the payment amount
### Refund-Details
**Refund Details**
A refund issued against a payment
Type: `object`
- `id` (string; required; example `"3050123456"`) — Refund ID
- `state` ([Refund-State](#schema-Refund-State); required) — Refund state
- `amount` (integer; required; example `100`) — Refunded amount in cents
- `currency` ([Currency](#schema-Currency); required) — Refund currency
- `created_at` (string (date-time); required; example `"2025-12-10T10:30:00Z"`) — When the refund was requested
- `updated_at` (string | null (date-time); optional; example `"2025-12-10T10:35:00Z"`) — When the refund state last changed. Null until the state changes for the first time
### Refund-State
**Refund State**
Refund lifecycle state:
- `REQUESTED` - The refund was accepted and is being processed
- `SUCCESS` - The refund was settled
- `FAILED` - The refund could not be processed
Type: `string`
Values: `REQUESTED`, `SUCCESS`, `FAILED`
### Recurrence-Schedule
**Recurrence Schedule**
How often an `AUTO` recurrence creates a payment
Type: `object`
- `period` (string; required; values: `DAY`, `WEEK`, `MONTH`; example `"MONTH"`) — Unit the cycle is counted in
- `cycle` (integer; required; minimum 1; example `1`) — Number of periods between two payments
Example:
```json
{
"period": "MONTH",
"cycle": 1
}
```
### Recurrence-Create-Request
**Recurrence Create Request**
One of the two recurrence kinds. The `type` field selects the case, taking values from the [Recurrence Type](#schema-Recurrence-Type) enum. An `AUTO` recurrence carries a `schedule`; an `ON_DEMAND` one must not, because the merchant asks for each further payment itself.
Type: `oneOf`
One of: [Recurrence-Create-Auto](#schema-Recurrence-Create-Auto), [Recurrence-Create-On-Demand](#schema-Recurrence-Create-On-Demand)
Discriminator: `type` (`AUTO` → [Recurrence-Create-Auto](#schema-Recurrence-Create-Auto), `ON_DEMAND` → [Recurrence-Create-On-Demand](#schema-Recurrence-Create-On-Demand))
### Recurrence-Create-Auto
**Recurrence Create Auto**
The `AUTO` variant of the [Recurrence Create Request](#schema-Recurrence-Create-Request) union. GoPay creates the payments itself on the schedule, so `schedule` is required here.
Type: `object`
- `type` (string = `"AUTO"`; required; example `"AUTO"`) — Always `AUTO`
- `schedule` ([Recurrence-Schedule](#schema-Recurrence-Schedule); required) — How often the recurrence creates a payment
- `recurrence_date_to` (string (date); required; example `"2027-09-04"`) — Last day on which the recurrence may create a payment, as yyyy-MM-dd
- `payment` ([Payment-Create-Request](#schema-Payment-Create-Request); required) — Payment template every payment of this recurrence is created from
Example:
```json
{
"type": "AUTO",
"schedule": {
"period": "MONTH",
"cycle": 1
},
"recurrence_date_to": "2027-09-04",
"payment": {
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"order_description": "Monthly subscription",
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe"
},
"callback": {
"notification_url": "https://example.com/notify",
"return_url": "https://example.com/return"
}
}
}
```
### Recurrence-Create-On-Demand
**Recurrence Create On Demand**
The `ON_DEMAND` variant of the [Recurrence Create Request](#schema-Recurrence-Create-Request) union. There is no schedule — the merchant asks for each further payment with the next operation — so `schedule` must not be sent.
Type: `object`
- `type` (string = `"ON_DEMAND"`; required; example `"ON_DEMAND"`) — Always `ON_DEMAND`
- `recurrence_date_to` (string (date); required; example `"2027-09-04"`) — Last day on which the recurrence may create a payment, as yyyy-MM-dd
- `payment` ([Payment-Create-Request](#schema-Payment-Create-Request); required) — Payment template every payment of this recurrence is created from
Example:
```json
{
"type": "ON_DEMAND",
"recurrence_date_to": "2027-09-04",
"payment": {
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"order_description": "Monthly subscription",
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe"
},
"callback": {
"notification_url": "https://example.com/notify",
"return_url": "https://example.com/return"
}
}
}
```
### Recurrence-Details
**Recurrence Details**
State of a recurrence and the payment it last created
Type: `object`
- `id` (string; required; example `"8008013370"`) — Unique ID of the recurrence
- `type` ([Recurrence-Type](#schema-Recurrence-Type); required) — Whether payments are created on a schedule or only on request
- `state` ([Recurrence-State](#schema-Recurrence-State); required) — Current state of the recurrence
- `schedule` ([Recurrence-Schedule](#schema-Recurrence-Schedule); optional) — Present only for an `AUTO` recurrence
- `recurrence_date_to` (string (date); required; example `"2027-09-04"`) — Last day on which the recurrence may create a payment, as yyyy-MM-dd
- `stop_reason` ([Recurrence-Stop-Reason](#schema-Recurrence-Stop-Reason); optional) — Why the recurrence stopped — present only in state `STOPPED`
- `payment` ([Recurrence-Payment](#schema-Recurrence-Payment); required) — Payment the recurrence carries — the stored template until one is created
Example:
```json
{
"id": "8008013370",
"type": "ON_DEMAND",
"state": "NEW",
"recurrence_date_to": "2027-09-04",
"payment": {
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"customer": {
"email": "john.doe@example.com"
}
}
}
```
### Recurrence-Payment
**Recurrence Payment**
The payment the recurrence carries. Before the recurrence is started this is the stored template only; once a payment exists, `id`, `state`, `gw_url` and `payment_secret` are filled in as well.
Type: `object`
- `id` (string; optional; example `"7310142951"`) — Payment ID. Absent until the recurrence has created a payment
- `state` ([Payment-State](#schema-Payment-State); optional) — State of the created payment. Absent until the recurrence has created one
- `amount` (integer; required; minimum 0; example `1500`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency
- `order_number` (string; required; max length 128; example `"2025010199"`) — Order identification for the online shop, alphanumeric characters
- `customer` ([Customer](#schema-Customer); required) — Information about the customer
- `gw_url` (string; optional; example `"https://gate.gopay.com/gw/123456789"`) — Address of GoPay's hosted payment gateway, where the customer pays the created payment. It cannot be embedded in the merchant's own checkout — see `Payment Details.gw_url`. Absent until the recurrence has created one
- `payment_secret` (string; optional; example `"ps_6aa48c5fadd5ca9ccbc2a30bb13d7e8e"`) — Secret the merchant's server passes to the GoPay client SDK, so that the SDK can act on the payment. Absent until the recurrence has created a payment. **Do not embed in URLs, log or store!**
Example:
```json
{
"amount": 1500,
"currency": "CZK",
"order_number": "2025010199",
"customer": {
"email": "john.doe@example.com"
}
}
```
### Recurrence-Type
**Recurrence Type**
`AUTO` creates payments on the schedule, `ON_DEMAND` only when the merchant asks for the next payment.
Type: `string`
Values: `AUTO`, `ON_DEMAND`
### Recurrence-State
**Recurrence State**
`NEW` after creation, `REQUESTED` once the first payment was created and is waiting to be paid, `STARTED` once it was paid and further payments can be requested, `STOPPED` when the recurrence ended.
Type: `string`
Values: `NEW`, `REQUESTED`, `STARTED`, `STOPPED`
### Recurrence-Stop-Reason
**Recurrence Stop Reason**
Why a recurrence in state `STOPPED` ended.
- `RECURRENCE_EXPIRED` - `recurrence_date_to` passed
- `CARD_EXPIRED` - The authorised card expired
- `CANCELLED_VIA_API` - Stopped with `DELETE /recurrences/{rec_id}`
- `CANCELLED_VIA_BACKOFFICE` - Stopped by a GoPay operator on the merchant's behalf
- `CANCELLED_BY_GOPAY` - Stopped by GoPay
- `UNKNOWN` - The reason is not available
Type: `string`
Values: `RECURRENCE_EXPIRED`, `CARD_EXPIRED`, `CANCELLED_VIA_API`, `CANCELLED_VIA_BACKOFFICE`, `CANCELLED_BY_GOPAY`, `UNKNOWN`
### Customer-Override
**Customer Override**
Customer fields to replace for a single payment. Unlike `Customer` no field is required — the recurrence's stored customer supplies whatever is omitted, merged field by field. Unknown fields are rejected.
Type: `object`
- `email` (string (email); optional; max length 128; example `"john.doe@example.com"`) — Customer email
- `first_name` (string; optional; max length 256; example `"John"`) — Customer first name
- `last_name` (string; optional; max length 256; example `"Doe"`) — Customer last name
- `phone_number` (string; optional; max length 128; example `"+420123456789"`) — Customer phone number (home or mobile)
- `city` (string; optional; max length 128; example `"Testington"`) — Customer address city
- `street` (string; optional; max length 128; example `"Example st. 10"`) — Customer address street
- `postal_code` (string; optional; max length 128; example `"10000"`) — Customer address ZIP (postal code)
- `country_code` (string; optional; max length 128; example `"CZE"`) — Customer country code according to [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
- `customer_id` (string; optional; max length 128; example `"customer420"`) — Unique customer ID (used to customise the checkout experience)
Example:
```json
{
"first_name": "John",
"last_name": "Doe"
}
```
### Payment-Instance-Override
**Payment Instance Override**
Fields that replace the recurrence's stored payment template for a single payment. Omitted fields keep the stored value; `customer` is merged field by field rather than replaced. Unknown fields are rejected.
Type: `object`
- `amount` (integer; optional; minimum 0; example `9900`) — Total amount in cents
- `order_number` (string; optional; max length 128; example `"2025010199"`) — Order identification for the online shop, alphanumeric characters
- `order_description` (string; optional; example `"Test order"`) — Order description, alphanumeric characters
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); optional; max items 4) — Additional parameters for the payment
- `customer` ([Customer-Override](#schema-Customer-Override); optional) — Customer fields to replace; omitted ones keep the stored value
- `callback` ([Payment-Callback](#schema-Payment-Callback); optional) — URLs for the return redirect and the notifications
Example:
```json
{
"amount": 9900,
"order_number": "2025010199",
"order_description": "Test order",
"customer": {
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe"
},
"callback": {
"notification_url": "https://example.com/notify",
"return_url": "https://example.com/return"
}
}
```
### Link-Create-Request
**Link Create Request**
The payment data a new payment link carries, its lifetime, and whether it may be used more than once
Type: `object`
- `payment` ([Payment-From-Link-Request](#schema-Payment-From-Link-Request); required) — Payment data used for every payment this link creates
- `expires_in` (integer; optional; minimum 1; example `3600`) — Link lifetime in seconds, counted from creation. Omit it for a link that never expires. The upper bound is a hundred years
- `reusable` (boolean; optional; default `true`; example `true`) — Whether the link may start more than one payment. A one-shot link is consumed by the first visit; see `Link Stop Reason`
### Link-Details
**Link Details**
A payment link, its state, and the payment data it carries
Type: `object`
- `id` (string; required; example `"3405871122"`) — Link ID, used on the status and disable calls. Not the code that appears in `url`
- `url` (string; required; example `"https://gate.gopay.com/gp-gw/l/Xk8mQ2pR7t"`) — Address to share with the customer. Opening it creates a payment and redirects the customer to the payment gateway. It ends in a random ten-character code unrelated to `id`
- `active` (boolean; required; example `true`) — Whether the link can still start a payment. Reported as false once the link expires, even before that is recorded
- `reusable` (boolean; required; example `true`) — Whether the link may start more than one payment
- `expires_at` (string (date-time); optional; example `"2026-08-18T14:35:12Z"`) — When the link stops being usable, computed at creation from `expires_in`. Absent for a link that never expires
- `stop_reason` ([Link-Stop-Reason](#schema-Link-Stop-Reason); optional) — Why the link is no longer active. Absent while the link is active
- `payment` ([Payment-From-Link-Request](#schema-Payment-From-Link-Request); optional) — Payment data the link carries
### Link-Stop-Reason
**Link Stop Reason**
Why a payment link is no longer active:
- `FROM_API` - The merchant disabled the link
- `USED` - A one-shot link was opened and created its payment
- `EXPIRED` - The link passed its `expires_at`
Type: `string`
Values: `FROM_API`, `USED`, `EXPIRED`
### Payment-From-Link-Request
**Payment From Link Request**
Representation of a payment created from a payment link. The same data is used for every payment the link creates, so a reusable link gives all of them the same `order_number` and the same `notification_url`.
Type: `object`
- `amount` (integer; required; minimum 0; example `15000`) — Total amount in cents
- `currency` ([Currency](#schema-Currency); required) — Payment currency. It must be a currency the eshop has an enabled payment channel for, otherwise the link is rejected with `400`
- `order_number` (string; required; max length 128; example `"2026-00042"`) — Order identification for the online shop, alphanumeric characters
- `order_description` (string; optional; max length 256; example `"Invoice 2026-00042"`) — Order description, alphanumeric characters
- `additional_params` (array of [Additional-Param](#schema-Additional-Param); optional; max items 4) — Additional parameters for the payment. Each `name` must not contain `=`, and `name` and `value` together may not exceed 511 characters
- `customer` ([Customer](#schema-Customer); required) — Information about the customer. The email address is required
- `callback` ([Payment-Callback](#schema-Payment-Callback); required) — URLs for the return redirect and the notifications. Both must be http or https and at most 512 characters long
Example:
```json
{
"amount": 15000,
"currency": "CZK",
"order_number": "2026-00042",
"order_description": "Invoice 2026-00042",
"additional_params": [
{
"name": "invoice",
"value": "INV-2026-001"
}
],
"customer": {
"email": "payer@example.com",
"first_name": "Jan",
"last_name": "Novák",
"phone_number": "+420123456789",
"city": "Praha",
"street": "Testovací 42",
"postal_code": "11000",
"country_code": "CZE",
"customer_id": "cust-001"
},
"callback": {
"notification_url": "https://eshop.example.com/gopay/notify",
"return_url": "https://eshop.example.com/gopay/return"
}
}
```
### Validate-Merchant-Request
**Validate Merchant Request**
The Apple Pay merchant validation request
Type: `object`
- `validationUrl` (string (uri); required; example `"https://apple-pay-gateway.apple.com/paymentservices/paymentSession"`) — The validation URL Apple Pay issued for the session
### Validate-Merchant-Response
**Validate Merchant Response**
The merchant session object Apple Pay expects, passed to the Apple Pay sheet unchanged
Type: `object`
### Event
One of the events GoPay records. The `type` field selects the case, taking values from the [Event Type](#schema-Event-Type) enum. A `type` the merchant's code does not recognise is ignored rather than treated as an error, so that a new type does not break a working integration.
Type: `oneOf`
One of: [Payment-Paid-Event](#schema-Payment-Paid-Event), [Payment-Canceled-Event](#schema-Payment-Canceled-Event), [Payment-Timeouted-Event](#schema-Payment-Timeouted-Event), [Link-Payment-Created-Event](#schema-Link-Payment-Created-Event), [Link-Disabled-Event](#schema-Link-Disabled-Event), [Refund-Succeeded-Event](#schema-Refund-Succeeded-Event), [Refund-Failed-Event](#schema-Refund-Failed-Event), [Recurrence-Started-Event](#schema-Recurrence-Started-Event), [Recurrence-Payment-Created-Event](#schema-Recurrence-Payment-Created-Event), [Recurrence-Stopped-Event](#schema-Recurrence-Stopped-Event), [Card-Updated-Event](#schema-Card-Updated-Event), [Card-Deleted-Event](#schema-Card-Deleted-Event)
Discriminator: `type` (`payments.paid` → [Payment-Paid-Event](#schema-Payment-Paid-Event), `payments.canceled` → [Payment-Canceled-Event](#schema-Payment-Canceled-Event), `payments.timeouted` → [Payment-Timeouted-Event](#schema-Payment-Timeouted-Event), `links.payment_created` → [Link-Payment-Created-Event](#schema-Link-Payment-Created-Event), `links.disabled` → [Link-Disabled-Event](#schema-Link-Disabled-Event), `refunds.succeeded` → [Refund-Succeeded-Event](#schema-Refund-Succeeded-Event), `refunds.failed` → [Refund-Failed-Event](#schema-Refund-Failed-Event), `recurrences.started` → [Recurrence-Started-Event](#schema-Recurrence-Started-Event), `recurrences.payment_created` → [Recurrence-Payment-Created-Event](#schema-Recurrence-Payment-Created-Event), `recurrences.stopped` → [Recurrence-Stopped-Event](#schema-Recurrence-Stopped-Event), `cards.updated` → [Card-Updated-Event](#schema-Card-Updated-Event), `cards.deleted` → [Card-Deleted-Event](#schema-Card-Deleted-Event))
Example:
```json
{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"type": "payments.paid",
"occurred_at": "2026-07-08T12:04:39.123Z",
"data": {
"payment_id": "300000001",
"charge_id": "9123456789"
}
}
```
### Event-Type
**Event Type**
The values of the field that selects the case of [Event](#schema-Event)
Type: `string`
Values: `payments.paid`, `payments.canceled`, `payments.timeouted`, `links.payment_created`, `links.disabled`, `refunds.succeeded`, `refunds.failed`, `recurrences.started`, `recurrences.payment_created`, `recurrences.stopped`, `cards.updated`, `cards.deleted`
### Payment-Paid-Event
**Payment Paid Event**
The `payments.paid` variant of the [Event](#schema-Event) union. The payment reached `PAID`.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `payments.paid`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Payment-Paid-Data](#schema-Payment-Paid-Data); required) — Identifiers of the entities the event concerns
### Payment-Canceled-Event
**Payment Canceled Event**
The `payments.canceled` variant of the [Event](#schema-Event) union. The payment reached `CANCELED`: the customer abandoned it, the charge was rejected at authorisation, or the merchant canceled it before it was charged.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `payments.canceled`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Payment-Event-Data](#schema-Payment-Event-Data); required) — Identifiers of the entities the event concerns
### Payment-Timeouted-Event
**Payment Timeouted Event**
The `payments.timeouted` variant of the [Event](#schema-Event) union. The payment did not reach a terminal outcome within its timeout.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `payments.timeouted`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Payment-Event-Data](#schema-Payment-Event-Data); required) — Identifiers of the entities the event concerns
### Link-Payment-Created-Event
**Link Payment Created Event**
The `links.payment_created` variant of the [Event](#schema-Event) union. A customer opened a payment link and a payment was created from it.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `links.payment_created`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Link-Payment-Created-Data](#schema-Link-Payment-Created-Data); required) — Identifiers of the entities the event concerns
### Link-Disabled-Event
**Link Disabled Event**
The `links.disabled` variant of the [Event](#schema-Event) union. The merchant deactivated a payment link.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `links.disabled`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Link-Event-Data](#schema-Link-Event-Data); required) — Identifiers of the entities the event concerns
### Refund-Succeeded-Event
**Refund Succeeded Event**
The `refunds.succeeded` variant of the [Event](#schema-Event) union. A refund settled.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `refunds.succeeded`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Refund-Event-Data](#schema-Refund-Event-Data); required) — Identifiers of the entities the event concerns
### Refund-Failed-Event
**Refund Failed Event**
The `refunds.failed` variant of the [Event](#schema-Event) union. A refund could not be settled.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `refunds.failed`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Refund-Event-Data](#schema-Refund-Event-Data); required) — Identifiers of the entities the event concerns
### Recurrence-Started-Event
**Recurrence Started Event**
The `recurrences.started` variant of the [Event](#schema-Event) union. A recurrence was activated by the payment named in `data`.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `recurrences.started`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Recurrence-Payment-Data](#schema-Recurrence-Payment-Data); required) — Identifiers of the entities the event concerns
### Recurrence-Payment-Created-Event
**Recurrence Payment Created Event**
The `recurrences.payment_created` variant of the [Event](#schema-Event) union. A scheduled payment was created from a recurrence.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `recurrences.payment_created`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Recurrence-Payment-Data](#schema-Recurrence-Payment-Data); required) — Identifiers of the entities the event concerns
### Recurrence-Stopped-Event
**Recurrence Stopped Event**
The `recurrences.stopped` variant of the [Event](#schema-Event) union. A recurrence was stopped.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `recurrences.stopped`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Recurrence-Event-Data](#schema-Recurrence-Event-Data); required) — Identifiers of the entities the event concerns
### Card-Updated-Event
**Card Updated Event**
The `cards.updated` variant of the [Event](#schema-Event) union. A saved card token changed in place, for instance after the issuer reissued the card.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `cards.updated`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Card-Event-Data](#schema-Card-Event-Data); required) — Identifiers of the entities the event concerns
### Card-Deleted-Event
**Card Deleted Event**
The `cards.deleted` variant of the [Event](#schema-Event) union. A saved card token was deleted.
Type: `object`
- `id` (string; required; example `"01ARZ3NDEKTSV4RRFFQ69G5FAV"`) — Unique identifier of the event. It is the value the merchant's server deduplicates on
- `type` ([Event-Type](#schema-Event-Type); required) — Always `cards.deleted`
- `occurred_at` (string (date-time); required; example `"2026-07-08T12:04:39.123Z"`) — When the fact happened, in UTC. May carry fractional seconds
- `data` ([Card-Event-Data](#schema-Card-Event-Data); required) — Identifiers of the entities the event concerns
### Payment-Paid-Data
**Payment Paid Data**
Identifies the payment and, if a charge paid it, the charge.
Type: `object`
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
- `charge_id` (string; optional; example `"9123456789"`) — Identifier of the charge that paid the payment. Absent when no charge paid it, for instance on the hosted gateway at `gw_url`
### Payment-Event-Data
**Payment Event Data**
Identifies the payment the event concerns.
Type: `object`
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
### Link-Payment-Created-Data
**Link Payment Created Data**
Identifies the payment link and the payment created from it.
Type: `object`
- `link_id` (string; required; example `"346346346"`) — Identifier of the payment link
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
### Link-Event-Data
**Link Event Data**
Identifies the payment link the event concerns.
Type: `object`
- `link_id` (string; required; example `"346346346"`) — Identifier of the payment link
### Refund-Event-Data
**Refund Event Data**
Identifies the refund and the payment it belongs to.
Type: `object`
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
- `refund_id` (string; required; example `"3050123456"`) — Identifier of the refund
### Recurrence-Payment-Data
**Recurrence Payment Data**
Identifies the recurrence and the payment the event concerns. For `recurrences.started` the payment is the one that started the recurrence; for `recurrences.payment_created` it is the newly created payment.
Type: `object`
- `recurrence_id` (string; required; example `"5521002"`) — Identifier of the recurrence
- `payment_id` (string; required; example `"300000001"`) — Identifier of the payment
### Recurrence-Event-Data
**Recurrence Event Data**
Identifies the recurrence the event concerns.
Type: `object`
- `recurrence_id` (string; required; example `"5521002"`) — Identifier of the recurrence
### Card-Event-Data
**Card Event Data**
Identifies the saved card token the event concerns. Card tokens belong to the merchant and are shared across the merchant's eshops.
Type: `object`
- `card_id` (string; required; example `"8007127320"`) — Identifier of the saved card token
### Event-List
**Event List**
One page of events of an eshop, newest first
Type: `object`
- `items` (array of [Event](#schema-Event); required) — The events in this page
- `next_page_url` (string (uri); optional; example `"https://gate.gopay.com/gp-gw/api/4.0/eshops/8123456789/events?type=refunds.*&max_items=20&prev_item=01H8ZQ7X9K4Q0M2V6T8B3C5D7E"`) — The full address of the next page, carrying the filters of the request and the `id` of
the last event of this page as the position to continue from. Absent when no further
matching event exists.
### JWK-Set
**JWK Set**
A set of public keys holding the webhook signing keys currently in use. It is formatted according to RFC 7517: JSON Web Key Set (JWK Set)
Type: `object`
- `keys` (array of [Signing-JWK](#schema-Signing-JWK); required) — The webhook signing keys currently in use
### Signing-JWK
**Signing JWK**
The structure of a public webhook signing key. It is formatted according to RFC 7517: JSON Web Key (JWK)
Type: `object`
- `kty` (string = `"RSA"`; required; example `"RSA"`) — Key type. Always `RSA` for the signing keys used by GoPay.
- `use` (string = `"sig"`; required; example `"sig"`) — Key usage. Always `sig` (signature).
- `kid` (string; required; example `"sign-2026-02"`) — Key ID. Matches the `kid` of the protected header of the `X-GoPay-Signature` the key verifies
- `alg` (string = `"RS256"`; required; example `"RS256"`) — Algorithm the signature was produced with. Always `RS256`.
- `n` (string; required; example `"4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ"`) — The `RSA` public key modulus part.
- `e` (string; required; default `"AQAB"`; example `"AQAB"`) — The `RSA` public key exponent part.
Example:
```json
{
"kty": "RSA",
"use": "sig",
"kid": "sign-2026-02",
"alg": "RS256",
"n": "4JHqz4QwbiVuVzLhjJwwgK_EC86qVTPhQIpmiQCoGNzLBQlsBdt13Y10AlzRSMMF65LyF5Y8doKR-gJlCR9J5P9YPr1IgU0wVyqJ349yL7O_lMWy5TfWdGz7KOrq9tyHVtjH0i5ztAIQHPvQ02LayjdNgUA4Z8RxFsSz03nCU-dJLJOg63BS23VfxEs4J_kmbITSACIxiIAerc-wUwIQkjlHyHQQtac7kcCQfSqDB3F2YqxFkWOC66drt2zcMutjxcK-ZcnjdBiQnTI_9izbJB9mX4CoErMWre7GNt_krHoi6OP6DoOvjEsABAS2Dyf13xLuNVH-QHpCUaYqR70OTQ",
"e": "AQAB"
}
```