Repository Standards

Appearance

On this page

Prerequisite Information ​

This part of the Payment Specification documentation outlines the process for implementing a Payment Gateway. A Payment Gateway is defined as a RESTful service capable of handling requests from a client.

TIP

Keep the following in mind:

  • Clients will always append /v2/ on the API calls they make to a server.
  • A Payment Gateway must always use HTTPS and at least TLS 1.2.
  • Payment Gateways are responsible for preventing abuse and implementing rate-limiting.
  • Payment Gateways are expected to use data passed by the client (Common Client Headers)

A client will pass the following information on every request it makes to a Payment Gateway:

  • An Authorization header containing a bearer token.
  • An X-Repository-URI header including the APT repository URL.
  • All the headers outlined on the Client Documentation.

A simple way to handle these headers is to employ middleware on your RESTful API. You should be keeping a track of the allowed repository hosts that may interact with your Payment Gateway. Be sure to check if the repository host is allowed to interact with your Payment Gateway and return a response with the 403 Forbidden status code if not.

Getting Started ​

To declare a Payment Gateway on an APT repository, the Release file needs to be modified. Add the Payment-Gateway key which points to a RESTful API that the Payment Gateway is on.

yaml
Origin: MyRepo
Label: MyRepo
Suite: stable
Version: 1.0
Codename: test
Architectures: iphoneos-arm
Components: main
Description: My Repository!
Date: Wed, 16 Feb 2022 10:00:17 +0000
Payment-Gateway: https://mygateway.com/api

Additionally, it's possible to attach a Payment Gateway to a single package. Simply adding the Payment-Gateway key to a package in the Packages file will accomplish this. If both the Release file and the package have a gateway, the one on the package will take priority.

yaml
Package: com.myrepo.mypackage
Name: MyPackage
Architecture: iphoneos-arm
Description: My Package!
Maintainer: Me
Version: 1.1.1
Filename: pool/mypackage.deb
Size: 433
Payment-Gateway: https://notmygateway.com/api

Due to this change, Payment Gateways are able to facilitate and support multiple repositories. The client will check if a Payment Gateway supports a specific repository host by making a web request (outlined below).
OPTIONS /v2/authorized

If the Payment Gateway recognizes the repository host as one that it can interact with, then it must return a status code of 100 Continue else 401 Unauthorized if not supported. Please keep in mind that the client will continue to pass this header on every subsequent request made to the Payment Gateway, leaving the gateway responsible for enforcing this check.

TIP

If the Payment Gateway returns 401 Unauthorized on the OPTIONS request, the client is responsible for exiting early, notifying the user that a repository is attempting to interact with a Payment Gateway that has not allowed it to.