GoPay next-gen
by GoPay

GoPay next-gen

How API URLs are built

Api URLs are built from three parts:

  1. Environment root
  2. API version
  3. 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

Authentication
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"
}
show more
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"
}
show more
Public key
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"
}
Create card token
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
expiration_month
string required
expiration_year
string required
brand
Card scheme required
Example:
MASTERCARD
fingerprint
string required
token
string required
card_art_url
string
masked_virtual_pan
string
expires_in
string
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",
    "brand": "MASTERCARD",
    "fingerprint": "klj54njk4njk54bn5jk4n",
    "token": "card-on3kno3i4ni3jn",
    "expires_in": "900"
}
show more
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

{
    "masked_pan": "506821******1234",
    "expiration_month": "01",
    "expiration_year": "31",
    "brand": "MASTERCARD",
    "fingerprint": "klj54njk4njk54bn5jk4n",
    "token": "card-on3kno3i4ni3jn",
    "card_art_url": "https://card.art/pic.png",
    "masked_virtual_pan": "502168******9876"
}
show more
Charge payment
POST /payments/{payment_id}/charge

Path variables

payment_id
string required
JWT header
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"
}
JWT claims
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
}
JWT

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

The JWT has 3 parts:

  1. header -> JSON serialized JWT header
  2. claims -> Contains the main part of the token - see JWT Claims for details
  3. 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
JWK

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

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

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

The JWE has 5 parts:

  1. header -> contains JSON serialized JWE header
  2. encrypted_key -> contains the CEK (Content Encryption Key) encrypted by the public JWK
  3. iv -> initiation vector used for content encryption
  4. ciphertext -> contains the Encrypted card
  5. 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
Encrypted card
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"
}
Grant type
string
Enumeration:
client_credentials
refresh_token
Scope
string
Enumeration:
card:save
card:read
payment:create
payment:read
Card scheme
string
Enumeration:
VISA
MASTERCARD