GoPay next-gen

Api URLs are built from three parts:

Environment root
API version
Resource endpoint

Environment root is the base URL of the environment to be used - sandbox or production.

Sandbox root: https://gw.sandbox.gopay.com
Production root: https://api.gopay.com

API version is in the format /api/x.y where x is the major version and y is the minor version. For example /api/4.0

Resource endpoint is what resource or operation you are actually targetting and can be found in this documentation. For example the authentication endpoint is /oauth2/token

The final URL is concatenation of these three parts: {environment_root}{api_version}{resource_endpoint} So to authenticate on the sandbox with API version 4.0, you would POST to

https://gw.sandbox.gopay.com/api/4.0/oauth2/token

POST /oauth2/token

Request headers

Content-Type

string required

Example:

application/x-www-form-urlencoded

Accept

string required

Example:

application/json

Authorization

string optional

Only applies to the client_credentials grant type.

Example:

Basic <username:password in base64>

Request body

application/x-www-form-urlencoded

Object

grant_type

Grant type

OAUTH2 Grant type. Use client_credentials if you don’t have a refresh token yet

scope

string

Only applies to the client_credentials grant type. List of values from Scope separated by spaces.

Example:

payment:create payment:read

refresh_token

string

Only applies to the refresh_token grant type. Refresh token value.

client_id

string

Only applies to the refresh_token grant type. Client ID for which the original token was issued.

Responses

200 OK

Headers

Content-Type

string required

application/json

Body

Object

access_token

JWT

The access token itself

Example:

ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogImtleS0yMDI1LTA0Igp9.ewogICJzdWIiOiAiY2xpZW50X2lkXzEyMyIsCiAgInNjb3BlIjogInBheW1lbnRzOnJlYWQgcGF5bWVudHM6d3JpdGUiLAogICJpYXQiOiAxNzEyNjQwMDAwLAogICJleHAiOiAxNzEyNjQzNjAwCn0.bWlrZWhlcmVfaXMtbXktc3VwZXJzZWNyZXQtbGlrZQ

token_type

string required

Example:

bearer

refresh_token

string required

scope

Scope

Scopes of the issued token. Only present when token is refreshed.

Example:

payment:create

New token

Refresh token

POST /api/4.0/oauth2/token HTTP/1.1 

Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

grant_type=client_credentials
&scope=payment:create payment:read

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogImtleS0yMDI1LTA0Igp9.ewogICJzdWIiOiAiY2xpZW50X2lkXzEyMyIsCiAgInNjb3BlIjogInBheW1lbnRzOnJlYWQgcGF5bWVudHM6d3JpdGUiLAogICJpYXQiOiAxNzEyNjQwMDAwLAogICJleHAiOiAxNzEyNjQzNjAwCn0.bWlrZWhlcmVfaXMtbXktc3VwZXJzZWNyZXQtbGlrZQ",
    "token_type": "bearer",
    "refresh_token": "efgh"
}

POST /api/4.0/oauth2/token HTTP/1.1 

Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=refresh_token
&refresh_token=efgh
&client_id=1234

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "access_token": "ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogImtleS0yMDI1LTA0Igp9.ewogICJzdWIiOiAiY2xpZW50X2lkXzEyMyIsCiAgInNjb3BlIjogInBheW1lbnRzOnJlYWQgcGF5bWVudHM6d3JpdGUiLAogICJpYXQiOiAxNzEyNjQ2MDAwLAogICJleHAiOiAxNzEyNjQ5NjAwCn0.bWlrZWhlcmVfaXMtbXktc3VwZXJzZWNyZXQtbGlrZQ",
    "token_type": "bearer",
    "refresh_token": "qwer"
}

GET /encryption/public-key

Returns the public encryption key to be used for encrypting card data for the Create card token endpoint.

It is structured as a JWK described by RFC 7517

Request headers

Accept

string required

Example:

application/json

Authorization

string required

Example:

Bearer {access_token}

Responses

200 OK

Headers

Content-Type

string optional

Example:

application/json

Body

JWK

Example 1

GET /encryption/public-key HTTP/1.1 

Accept: application/json
Authorization: Bearer {access_token}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "kty": "RSA",
    "kid": "key_20250406",
    "use": "enc",
    "alg": "RSA-OAEP-256",
    "n": "y7WkT3qvY...",
    "e": "AQAB"
}

POST /cards/tokens

Request headers

Content-Type

string required

Example:

application/json

Accept

string required

Example:

application/json

Authorization

string required

Example:

Bearer {access_token}

Request body

Object

payload

JWE

The JWE string containing the encrypted card data. See JWE and Encrypted card for details

permanent

boolean

Whether to save the card for permanent usage

Responses

201 Created

Headers

Content-Type

string optional

application/json

Body

Object

masked_pan

string required

Masked funding PAN of the card

expiration_month

string required

Expiration month MM

expiration_year

string required

Expiration year YY

scheme

Card scheme

Example:

MASTERCARD

brand

string

Card Brand

Example:

GOLD/STANDARD

service_type

Card Service Type

Card service type

Example:

DEBIT

corporate

boolean

Whether it is a corporate card

Example:

false

fingerprint

string required

Unique fingerprint identifying a specific card

token

string required

Card token used for payments

expires_in

string

Token expiration (one-time tokenization only)

card_art_url

string

Url for the card art picture (permanent tokenization only)

masked_virtual_pan

string

Masked virtual PAN of the card (permanent tokenization only)

card_id

string

Identifier of a saved card (permanent tokenization only)

Example:

8123456

Single-use token

Permanent token

POST /cards/tokens HTTP/1.1 

Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}

{
    "payload": "eyJalgIjoiUlNBLU9BRVAtMjU2IiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImtleV8yMDI1MDQwNl8wMDEifQ.aG93ZGlkYmFzZTY0.dGhpc2lzdGhlaXY.ZW5jcnlwdGVkY2FyZGhvbGRlcmRhdGE.YXV0aHRhZw",
    "permanent": false
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "masked_pan": "506821******1234",
    "expiration_month": "01",
    "expiration_year": "31",
    "scheme": "MASTERCARD",
    "brand": "GOLD/STANDARD",
    "service_type": "DEBIT",
    "corporate": false,
    "fingerprint": "klj54njk4njk54bn5jk4n",
    "token": "card-on3kno3i4ni3jn",
    "expires_in": "900"
}

POST /cards/tokens HTTP/1.1 

Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}

{
    "payload": "eyJalgIjoiUlNBLU9BRVAtMjU2IiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImtleV8yMDI1MDQwNl8wMDEifQ.aG93ZGlkYmFzZTY0.dGhpc2lzdGhlaXY.ZW5jcnlwdGVkY2FyZGhvbGRlcmRhdGE.YXV0aHRhZw",
    "permanent": true
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "card_id": "8123456"
    "masked_pan": "506821******1234",
    "expiration_month": "01",
    "expiration_year": "31",
    "scheme": "MASTERCARD",
    "brand": "GOLD/STANDARD",
    "service_type": "DEBIT",
    "corporate": false,
    "fingerprint": "klj54njk4njk54bn5jk4n",
    "token": "card-on3kno3i4ni3jn",
    "card_art_url": "https://card.art/pic.png",
    "masked_virtual_pan": "502168******9876"
}

POST /payments/{payment_id}/charges

Path variables

payment_id

string required

Request body

Object

type

Payment Instrument Type

payload

One of

Payment Card Payload

Google Pay Payload

Apple Pay Payload

return_url

string

Responses

201 Created

Body

Object

id

string

state

Charge State

action_url

string

payment_instrument

One of

Payment Card Charge

Challenge flow

Frictionless flow

3DS Skipped

POST /payments/{payment_id}/charges HTTP/1.1 

Content-Type: application/json

{
    "type": "PAYMENT_CARD",
    "payload": {
        "card_token": "card-on3kno3i4ni3jn"",
        "challenge_preference": "PREFER_CHALLENGE"
    },
    "return_url": "https://example.com/return"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "01JWVM8QB0VV98KW2C3KBV6DHA",
    "state": "ACTION_REQUIRED",
    "action_url": "https://pay.eewosecure.com/api/creq/brw",
    "payment_instrument": {
        "type": "PAYMENT_CARD",
        "masked_pan": "506821******1234",
        "expiration_month": "03",
        "expiration_year": "31",
        "input_method": "TOKEN",
        "3ds": {
            "auth_state": "CHALLENGE_REQUIRED"
        }
    }
}

POST /payments/{payment_id}/charges HTTP/1.1 

Content-Type: application/json

{
    "type": "GOOGLE_PAY",
    "payload": {
        "signature": "MEUCIQDhTxhHqwY8pXB9hpYxaSK5jFgsqpG2E1rX77QXssK8tAIgUBvYYAI/bnBS8T/Tfxnm2AF981Mv5y0pHyGexM5dMJk=",
        "protocolVersion": "ECv1",
        "signedMessage": "{\"encryptedMessage\":\"...\",\"ephemeralPublicKey\":\"...\",\"tag\":\"...\"}"
    },
    "return_url": "https://example.com/return"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "01JWVM8QB0VV98KW2C3KBV6DHA",
    "state": "PROCESSING",
    "payment_instrument": {
        "type": "PAYMENT_CARD",
        "masked_pan": "506821******1234",
        "expiration_month": "03",
        "expiration_year": "31",
        "input_method": "GOOGLE_PAY",
        "3ds": {
            "auth_state": "AUTHENTICATED_FRICTIONLESS"
        }
    }
}

POST /payments/{payment_id}/charges HTTP/1.1 

Content-Type: application/json

{
    "type": "APPLE_PAY",
    "payload": {
        "data": "V7OcjttPJnUJaQH7x7OjbIeZSINuc...",
        "signature": "MIAGCSqGSIb3DQEHAqCAM...",
        "version": "EC_v1",
        "header": {
            "ephemeralPublicKey": "MFkwEwYHKoZIzj...",
            "publicKeyHash": "L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=",
            "transactionId": "4f4fac7a1...a6a8ba2c0e8c5"
        }
    },
    "return_url": "https://example.com/return"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "01JWVM8QB0VV98KW2C3KBV6DHA",
    "state": "PROCESSING",
    "payment_instrument": {
        "type": "PAYMENT_CARD",
        "masked_pan": "506821******1234",
        "expiration_month": "03",
        "expiration_year": "31",
        "input_method": "APPLE_PAY"
    }
}

Object

alg

string

Will always be HS256

Example:

HS256

typ

string

Will always be JWT

Example:

JWT

kid

string

Key ID that was used to sign the token

Example:

key-2025-04

Example 1

{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "key-2025-04"
}

Object

sub

string

The client ID for which the token has been issued

Example:

client_id_123

scope

string

Space-separated list of scopes

Example:

payments:read payments:write

iat

integer

Timestamp of when the token was issued

Example:

1712640000

exp

integer

Timestamp of the token expiration

Example:

1712643600

Example 1

{
    "sub": "client_id_123",
    "scope": "payments:read payments:write",
    "iat": 1712640000,
    "exp": 1712643600
}

The JWT string as described by RFC 7519: JSON Web Token (JWT)

The JWT has 3 parts:

header -> JSON serialized JWT header
claims -> Contains the main part of the token - see JWT Claims for details
signature -> Contains the cryptographic signature of the token

Each of these parts is Base64URL-encoded and concatenated using dots so the overall structure is: BASE64URL(header).BASE64URL(claims).BASE64URL(signature)

string

Example:

ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogImtleS0yMDI1LTA0Igp9.ewogICJzdWIiOiAiY2xpZW50X2lkXzEyMyIsCiAgInNjb3BlIjogInBheW1lbnRzOnJlYWQgcGF5bWVudHM6d3JpdGUiLAogICJpYXQiOiAxNzEyNjQwMDAwLAogICJleHAiOiAxNzEyNjQzNjAwCn0.bWlrZWhlcmVfaXMtbXktc3VwZXJzZWNyZXQtbGlrZQ

Example 1

ewogICJhbGciOiAiSFMyNTYiLAogICJ0eXAiOiAiSldUIiwKICAia2lkIjogImtleS0yMDI1LTA0Igp9.ewogICJzdWIiOiAiY2xpZW50X2lkXzEyMyIsCiAgInNjb3BlIjogInBheW1lbnRzOnJlYWQgcGF5bWVudHM6d3JpdGUiLAogICJpYXQiOiAxNzEyNjQwMDAwLAogICJleHAiOiAxNzEyNjQzNjAwCn0.bWlrZWhlcmVfaXMtbXktc3VwZXJzZWNyZXQtbGlrZQ

The structure of the public encryption key. It is formatted according to RFC 7515: JSON Web Key (JWK)

Object

kty

string

Key type. Will be always RSA.

Example:

RSA

kid

string

Key ID containing the information about the key age.

Example:

key_20250406

use

string

Key usage. Will be always enc.

Example:

enc

alg

string

Algorithm to be used for encryption with the key.

Example:

RSA-OAEP-256

n

string

The RSA public key modulus part.

Example:

y7WkT3qvY...

e

string

The RSA public key exponent part.

Example:

AQAB

Example 1

{
    "kty": "RSA",
    "kid": "key_20250406",
    "use": "enc",
    "alg": "RSA-OAEP-256",
    "n": "y7WkT3qvY...",
    "e": "AQAB"
}

The header for the JWE payload described by RFC 7516 Section 4

Object

alg

string

The algorithm used to encrypt the CEK. Taken from the JWK.

Example:

RSA-OAEP-256

enc

string

The algorithm used to encrypt the content. A256GCM is preferred.

Example:

A256GCM

kid

string

The key id taken from the JWK

Example:

key_20250406

typ

string

Will be JWE

Example:

JWE

Example 1

{
    "alg": "RSA-OAEP-256",
    "enc": "A256GCM",
    "kid": "key_20250406",
    "typ": "JWE"
}

The structure containing the encrypted payload. It is described by RFC 7516: JSON Web Encryption (JWE)

The JWE has 5 parts:

header -> contains JSON serialized JWE header
encrypted_key -> contains the CEK (Content Encryption Key) encrypted by the public JWK
iv -> initiation vector used for content encryption
ciphertext -> contains the Encrypted card
tag -> encryption authentication tag

Each of these parts is Base64URL-encoded and concatenated using dots so the overall structure is: BASE64URL(header).BASE64URL(encrypted_key).BASE64URL(iv).BASE64URL(ciphertext).BASE64URL(tag)

string

Example:

eyJalgIjoiUlNBLU9BRVAtMjU2IiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImtleV8yMDI1MDQwNl8wMDEifQ.aG93ZGlkYmFzZTY0.dGhpc2lzdGhlaXY.ZW5jcnlwdGVkY2FyZGhvbGRlcmRhdGE.YXV0aHRhZw

Example 1

eyJalgIjoiUlNBLU9BRVAtMjU2IiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImtleV8yMDI1MDQwNl8wMDEifQ.aG93ZGlkYmFzZTY0.dGhpc2lzdGhlaXY.ZW5jcnlwdGVkY2FyZGhvbGRlcmRhdGE.YXV0aHRhZw

Object

card_pan

string

Example:

4444444444444448

exp_month

string

Example:

01

exp_year

string

Example:

27

cvv

string

Example:

258

Example 1

{
    "card_pan": "4444444444444448",
    "exp_month": "01",
    "exp_year": "27",
    "cvv": "258"
}

string

Enumeration:

client_credentials

refresh_token

string

Enumeration:

card:save

card:read

payment:create

payment:read

string

Enumeration:

VISA

MASTERCARD

Object

card_token

string

challenge_preference

Challenge preference nullable

Example 1

{
    "card_token": "card-on3kno3i4ni3jn",
    "challenge_preference": "AUTO"
}

string

Enumeration:

AUTO

PREFER_CHALLENGE

PREFER_SKIP

Object

signature

string

Example:

MEUCIQDhTxhHqwY8pXB9hpYxaSK5jFgsqpG2E1rX77QXssK8tAIgUBvYYAI/bnBS8T/Tfxnm2AF981Mv5y0pHyGexM5dMJk=

protocolVersion

string

Example:

ECv1

signedMessage

string

Example:

{"encryptedMessage":"...","ephemeralPublicKey":"...","tag":"..."}

Example 1

{
    "signature": "MEUCIQDhTxhHqwY8pXB9hpYxaSK5jFgsqpG2E1rX77QXssK8tAIgUBvYYAI/bnBS8T/Tfxnm2AF981Mv5y0pHyGexM5dMJk=",
    "protocolVersion": "ECv1",
    "signedMessage": "{\"encryptedMessage\":\"...\",\"ephemeralPublicKey\":\"...\",\"tag\":\"...\"}"
}

Object

data

string

Example:

V7OcjttPJnUJaQH7x7OjbIeZSINuc...

signature

string

Example:

MIAGCSqGSIb3DQEHAqCAM...

version

string

Example:

EC_v1

header

Object

ephemeralPublicKey

string

Example:

MFkwEwYHKoZIzj...

publicKeyHash

string

Example:

L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=

transactionId

string

Example:

4f4fac7a1...a6a8ba2c0e8c5

Example 1

{
    "data": "V7OcjttPJnUJaQH7x7OjbIeZSINuc...",
    "signature": "MIAGCSqGSIb3DQEHAqCAM...",
    "version": "EC_v1",
    "header": {
        "ephemeralPublicKey": "MFkwEwYHKoZIzj...",
        "publicKeyHash": "L6vppo38t31Q/9npxRy/xbA1+cs13h1LV+pMO/FYwvo=",
        "transactionId": "4f4fac7a1...a6a8ba2c0e8c5"
    }
}

Object

type

Payment Instrument Type

masked_pan

string

expiration_month

string

expiration_year

string

input_method

Card Input Method

3ds

3DS Data

Example 1

{
    "type": "PAYMENT_CARD",
    "masked_pan": "506821******1234",
    "expiration_month": "03",
    "expiration_year": "31",
    "input_method": "GOOGLE_PAY",
    "3ds": {
        "auth_state": "CHALLENGE_REQUIRED"
    }
}

string

Enumeration:

REQUESTED

PROCESSING

ACTION_REQUIRED

FINISHED

FAILED

string

Enumeration:

PAYMENT_CARD

Object

auth_state

Authentication state

auth_method

Authentication method nullable

Example 1

{
    "auth_state": "AUTHENTICATED_CHALLENGE",
    "auth_method": "OOB"
}

string

Enumeration:

CREATED

CHALLENGE_REQUIRED

AUTHENTICATED_CHALLENGE

AUTHENTICATED_FRICTIONLESS

NOT_AUTHENTICATED

REJECTED

string

Enumeration:

STATIC

DYNAMIC

OOB

DECOUPLED

FIDO

OTHER

string

Enumeration:

TOKEN

GOOGLE_PAY

APPLE_PAY

string

Enumeration:

PAYMENT_CARD

GOOGLE_PAY

APPLE_PAY

string

Enumeration:

DEBIT

Debit card

CREDIT

Credit card