Skip to main content

GoPay's Python SDK for Payments REST API

Project description

GoPay's Python SDK for Payments REST API

Build Status



The simplest way to install SDK is to use PIP:

pip install gopay

Basic usage

import gopay
from gopay.enums import TokenScope, Language

# minimal configuration
payments = gopay.payments({
    "goid": "{{YOUR-GOID}}",
    "client_id": "{{YOUR-CLIENT-ID}}",
    "client_secret": "{{YOUR-CLIENT-SECRET}}",
    "gateway_url": ''

# full configuration
payments = gopay.payments({
    "goid": "{{YOUR-GOID}}",
    "client_id": "{{YOUR-CLIENT-ID}}",
    "client_secret": "{{YOUR-CLIENT-SECRET}}",
    "gateway_url": ''
    "scope": TokenScope.ALL,
    "language": Language.CZECH

# Sandbox URL:
# Production URL:


Required fields

Required field Data type Documentation
goid string GoID assigned by GoPay (production or sandbox)
client_id string Client ID assigned by GoPay (production or sandbox)
client_secret string Client Secret assigned by GoPay (production or sandbox)
gateway_url string URL of the environment - production or sandbox (see Docs)

Optional fields

Optional field Data type Default value Documentation
scope string gopay.enums.TokenScope.ALL
language string gopay.enums.Language.ENGLISH default language to use + localization of errors

Available methods

API SDK method
Create a payment payments.create_payment(payment: dict)
Get status of a payment payments.get_status(payment_id: str | int)
Refund a payment payments.refund_payment(payment_id: int | str, amount: int)
Create a recurring payment payments.create_recurrence(payment_id: int | str, payment: dict)
Cancel a recurring payment payments.void_recurrence(payment_id: int | str)
Capture a preauthorized payment payments.capture_authorization(payment_id: int | str)
Capture a preauthorized payment partially payments.capture_authorization_partial(payment_id: int | str, payment: dict)
Void a preauthorized payment payments.void_authorization(payment_id: int | str)
Get payment card details payments.get_card_details(card_id: int | str)
Delete a saved card payments.delete_card(card_id: int | str)
Get allowed payment methods for a currency payments.get_payment_instruments(goid: int | str, currency: gopay.enums.Currency)
Get all allowed payment methods payments.get_payment_instruments_all(goid: int | str)
Generate an account statement payments.get_account_statement(statement_request: dict)

SDK response? Has my call succeed?

SDK returns wrapped API response. Every method returns gopay.http.Response object. Structure of the json should be same as in documentation. SDK throws no exception. Please create an issue if you catch one.

response = payments.create_payment(...)
if response.success:
    print(f"Hooray, API returned {response}")
    return response.json["gw_url"] # url for initiation of gateway
    # errors format:
    print(f"Oops, API returned  {response.status_code}: {response}")
Property/Method Description
response.success Checks if API call was successful
response.json decoded response, returned objects are converted into a dictionary if possiblem
response.status_code HTTP status code
response.raw_body raw bytes of the reponse content

Are required fields and allowed values validated?

Not yet. API validates fields pretty extensively so there is no need to duplicate validation in SDK. That's why SDK just calls API which behavior is well documented in In the future, we might use Pydantic for parsing and validation.

Advanced usage

Initiation of the payment gateway

# create payment and pass url to template (e.g. Flask, Django)
response = payments.create_payment(...)
if response.has_succeed():
    context = {
        'gateway_url': response.json['gw_url'],
        'embedjs_url': payments.get_embedjs_url
    # render template

Inline gateway

<form action="{{ gateway_url }}" method="post" id="gopay-payment-button">
  <button name="pay" type="submit">Pay</button>
  <script type="text/javascript" src="{{ embedjs_url }}"></script>

Redirect gateway

<form action="{{ gateway_url }}" method="post">
  <button name="pay" type="submit">Pay</button>

Asynchronous initialization using JavaScript


Instead of hardcoding bank codes string you can use predefined enums. Check using enums in create-payment example

Type Description
Language Payment language, localization of error messages
Token scope Authorization scope for OAuth2
Payment enums Enums for creating payment
Response enums Result of creating payment, executing payment operations

Cache access token

Access token expires after 30 minutes it's expensive to use new token for every request. By default, tokens are stored in memory so they are reused as long as the object exists. But you can implement your cache and store tokens in Memcache, Redis, files, ... It's up to you.

Your cache should inherit from and implement its methods get_token and set_token. Be aware that there are two scopes (TokenScope) and SDK can be used for different clients (client_id, gateway_url). So key passed to methods is unique identifier (str) that is built for current environment. Below you can see example implementation of caching tokens in memory:

from import AbstractCache
from gopay.http import AccessToken

class MyCache(AbstractCache):
    def __init__(self):
        self.tokens: dict[str, AccessToken] = {}

    def get_token(self, key: str) -> AccessToken | None:
        return self.tokens.get(key) # return None if token doesn't exist

    def set_token(self, key: str, token: AccessToken) -> None:
        self.tokens[key] = token

# register cache in optional service configuration
payments = gopay.payments(
    {...}, # your config
    {"cache": MyCache()}

Log HTTP communication

You can log every request and response from communication with API. Check available loggers below. Or you can implement your own logger, just implement function that matches the following signature:

def logger(gopay.http.Request, gopay.http.Response) -> Any: ...
# or
Callable[[gopay.http.Response, gopay.http.Request], Any]

For example:

from gopay.http import Request, Response

def my_logger(request: Request, response: Response) -> None:

# register logger in optional service configuration
payments = gopay.payments(
    {...}, # your config
    {"logger": my_logger}

The default logger uses logging.debug to log the responses and requests.


Contributions from others would be very much appreciated! Send pull request/ issue. Thanks!


Copyright (c) 2023 MIT Licensed, see LICENSE for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gopay-2.0.0.tar.gz (13.8 kB view hashes)

Uploaded Source

Built Distribution

gopay-2.0.0-py3-none-any.whl (12.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page