Payment Gateways in Shopsys

This documentation provides an overview of the payment gateway system in Shopsys, including how to implement and configure payment gateways, with a specific focus on the GoPay integration.

Payment Gateway Architecture

The Shopsys payment system is designed with a flexible architecture that supports multiple payment gateways. The core of this architecture is the PaymentServiceInterface, which defines the contract that all payment gateway implementations must follow.

Core Components

Payment Model

  • Located in Shopsys\FrameworkBundle\Model\Payment namespace
  • Contains all core payment-related classes and interfaces

Payment Service Interface

  • Defines the contract for payment gateways with three key methods:
    • createTransaction(): Creates a new payment transaction
    • updateTransaction(): Updates the status of an existing transaction
    • refundTransaction(): Processes refunds for a transaction
  • see PaymentServiceInterface

Payment Service Facade

  • Coordinates operations across different payment types
  • Routes payment operations to the appropriate payment service implementation
  • See PaymentServiceFacade

Transaction Handling

  • The system includes robust transaction handling capabilities
  • Supports creating, updating, and refunding transactions
  • See PaymentTransaction and related classes in the Shopsys\FrameworkBundle\Model\Payment\Transaction namespace

Supported Payment Types

Shopsys currently supports the following payment types (defined by the PaymentTypeEnum):

Basic Payment Type

  • Simple payment methods include cash on delivery, bank transfer, and others
  • Does not require integration with external payment processors

GoPay Payment Type

  • Online payments processed through the GoPay service
  • Supports various payment methods, including credit cards and bank transfers

GoPay Integration

Shopsys includes a complete implementation of the GoPay payment gateway, which can serve as a reference for implementing other payment gateways.

GoPay Components

GoPayFacade

GoPayClient

  • Handles low-level communication with the GoPay API
  • Manages authentication and API requests
  • Processes responses from the GoPay service
  • See GoPayClient

GoPayClientFactory

  • Creates instances of the GoPayClient
  • Manages configuration for different domains
  • Supports both production and test environments
  • See GoPayClientFactory

Cron Modules

Configuring GoPay

To configure GoPay in your Shopsys project, you need to set up the GOPAY_CONFIG environment variable. The variable defines your GoPay merchant ID (goid), your client ID, and client secret. Moreover, it specifies whether to use the production or test environment, and which domains should have GoPay enabled. For inspiration, see the configuration in .env.test file.

When your application is using HTTP authentication, you need to set the GoPay servers' IPs to the WHITELIST_IPS variable in your deploy-project.sh to enable GoPay to send requests back to your application.

Local development and testing

For local development and testing, you can use the GoPay test environment. Set the GOPAY_CONFIG environment variable in your .env.local file to use the test credentials provided by GoPay. This allows you to simulate payment transactions without affecting real accounts.

Moreover, GoPay does not allow the usage of localhost or 127.0.0.1 as a return URL for payment callbacks. Instead, you can use the following local setup:

  • modify your /etc/hosts file to include a custom domain, such as app.test. You will need to use sudo to edit this file.
  • set the same domain URL in your app/config/domains_urls.yaml config file
  • edit your storefront/.env.local:
DOMAIN_HOSTNAME_1=http://app.test:8000/
PUBLIC_GRAPHQL_ENDPOINT_HOSTNAME_1=http://app.test:8000/graphql/
  • recreate the storefront container with docker compose up -d --force-recreate storefront
  • enjoy the GoPay integration in your local environment on http://app.test:8000/

For automated tests, there is a test GoPay client that simulates the GoPay API responses. This allows you to run tests without needing access to the actual GoPay service. See the GoPayClient class for more details.

Implementing a Payment Gateway

To implement a new payment gateway in Shopsys:

Add a new payment type

Implement the PaymentServiceInterface

Register your implementation

Configure frontend components

  • Implement the necessary frontend components for your payment gateway
  • Update the order process to support your payment gateway

Frontend API Integration

The Shopsys Frontend API provides GraphQL queries and mutations for working with payment methods:

Queries

payments

  • Returns a complete list of payment methods with details like name, price, and associated transport methods
  • Example: query { payments { uuid, name, price { priceWithVat } } }

payment

  • Returns detailed information about a specific payment method
  • Example: query { payment(uuid: "...") { uuid, name, description } }

orderPayments

  • Returns payments available for a given order
  • Example: query { orderPayments(orderUuid: "...") { ... } }

GoPaySwifts

  • Returns a list of available banks for GoPay bank transfer payment
  • Example: query { GoPaySwifts(currencyCode: "CZK") { ... } }

orderPaymentPageContent

  • Returns HTML content for the order payment page depending on the state of the payment
  • Example: query { orderPaymentPageContent(orderUuid: "...") { ... } }

Mutations

PayOrder

  • Creates a payment transaction in a payment gateway and returns payment setup data
  • Example: mutation { PayOrder(orderUuid: "...") { ... } }

UpdatePaymentStatus

  • Checks the payment status of an order after a callback from the payment service
  • Example: mutation { UpdatePaymentStatus(orderUuid: "...") { ... } }

ChangePaymentInOrder

  • Changes payment in an order after order creation (available for unpaid GoPay orders only)
  • Example: mutation { ChangePaymentInOrder(input: { ... }) { ... } }

ChangePaymentInCart

  • Adds a payment to the cart or removes a payment from the cart
  • Example: mutation { ChangePaymentInCart(input: { ... }) { ... } }

These GraphQL operations allow frontend applications to display payment options to customers and process payments through the selected payment gateway.

Conclusion

The payment gateway system in Shopsys provides a flexible and extensible framework for integrating various payment processors. The GoPay integration serves as a comprehensive example of how to implement a payment gateway in Shopsys.

For more detailed information about specific payment gateways or implementation details, refer to the code in the Shopsys\FrameworkBundle\Model\Payment and Shopsys\FrameworkBundle\Model\GoPay namespaces.