Skip to main content
Payments Canada Developer Portal

Payments Canada API Standards

Table of Contents

Executive Summary

Broadly speaking, the API strategy and standards for Payments Canada needs to address some simple characteristics of the development community at large. These critical characteristics are: 

  • Consistency – consistency within the tools, interfaces and models not just across the catalogue of APIs but also in comparison to the industry at large.  Picking methods and standards that are already being rolled out by Payments Canada’s industry partners will make the uptake of its APIs that much simpler.
  • Stability – infrastructure needs to be designed and deployed to ensure the accessibility and availability of APIs at all times.
  • Performance – APIs should be delivering a published set of performance metrics that meet the threshold of the business requirements.

Whether the APIs are being developed for internal, closed community or open release to the public, these aspects will cultivate trust and understanding among our development communities.  This document supplies the detailed options and selections made to establish the standards that will be applied to API development to address the Consistency aspect above.  In summary, the following API design standards are being adopted for Payments Canada:

  • API Interface Standard: RESTful API
  • API Hypermedia Format: JSON
  • API Documentation Standard: OAS 3.0 (deprecated: Swagger 2.0)
  • API Prototyping and usage definition tools: Postman
  • API Security: OAuth 2.0
  • API Message body format: ISO 20022 JSON messages or proprietary JSON messages
  • API Versioning Model: Media Type Method
  • Resource naming best practices are also provided

Using these resources and standards, Payments Canada will be able to publish a set of consistent and stable API interfaces that are in line with existing standards and are aligned with the standards being adopted within the banking industry.

API Standardization

Payments Canada API Interface Standards

There are a variety of API interface standards available to choose from that have been created throughout the industry over the past 40 years.

The API Interface standard for Payments Canada will be focused initially on the RESTful model, with a strong preference to constrain the operations of APIs across all interfaces to a single request/response model using the RESTful API specification over the HTTPS-secured HTTP protocol.

This will drive a resource-bound implementation of APIs that can leverage a microservice or orchestrate several microservices to complete the associated resource request.

At Payments Canada, we choose to follow RESTful design patterns. You can find more details on these patterns on Microsoft's website, available at

Payments Canada Hypermedia Standard

With an established standard for building RESTful APIs, there needs to be a set standard for the hypermedia format of the messaging embedded in those API interfaces.

Payments Canada will look to adopt the JSON:API Hypermedia format standard where it makes sense to align with the most popular industry API Hypermedia usage. This will make it easier for development teams to understand and define their API requests. 

Overview of API Hypermedia Formats

The following table elaborates on the various Hypermedia formats available and the acceptance, pros, and cons of each:






Designed to ensure separation between clients and servers, while also minimizing the number of requests without compromising readability, flexibility, or discovery.

  • simple versatile format
  • easy to read/ implement
  • flat link grouping
  • URL templating
  • wide adoption/strong community
  • recognized as a hypermedia standard
  • JSON only
  • lack of identifier for documentation
  • still a work in progress


HAL incorporates 'CURIEs', a feature that makes it unique and allows for the inclusion of documentation links in responses – they are tightly coupled to the link name. HAL is one of the most supported and most widely used hypermedia specs and is surrounded by a strong and vocal community.

  • Dynamic
  • Nestable
  • easy to read/ implement
  • multi-format
  • URL templating
  • inclusion of documentation
  • wide adoption/strong community
  • recognized as a standard hypermedia spec
  • RFC proposed
  • JSON/XML formats are architecturally different
  • CURIEs are tightly coupled


Collection+JSON is a JSON-based read/write hypermedia-type designed to support the management and querying of simple collections. It is based on the Atom Publication and Syndication specs, defining both in a single spec and supporting simple queries through the use of templates.

  • a strong choice for collections
  • templated queries
  • early wide adoption
  • recognized as a standard
  • JSON only
  • lack of identifier for documentation
  • more complex/ difficult to implement


A more advanced and compact message method from Google that can be substituted for JSON

  • Extremely small size
  • Easily readable by machines and humans
  • Compilable to machine code
  • Sponsored by Google
  • New spec
  • Limited support

API Documentation Standards

As with other aspects of APIs discussed above, there are a variety of methods for documenting and representing APIs which need to be considered.

Payments Canada API Documentation Standard

All API services need to reside in a repository such as GitHub or Bitbucket. Here are the base elements of what is contained within each repository:

  • OpenAPI - A JSON definition for the surface area of an API, including the request, responses, and underlying schema used as part of both.
  • Postman Collection - A JSON Postman Collection that has been exported from the Postman client after importing the complete OpenAPI definition, and fully tested.

The goal is to establish a complete index of the APIs using OpenAPI and make it available in our developer portal, including the postman collection when applicable.

API Documentation Methods

Of the many API documentation and specification formats, we've selected OpenAPI Specification (OAS3) which is one of the most popular API documentation methods. There is a wealth of tools available to generate code and documentation which gives the ability to present specs in a standardized manner.

  • Pros:
    • Widely adopted
    • Integrated in many tools and platforms for APIs
    • Follows JSON formatting
    • Language Agnostic
  • Cons:
    • Lacks advanced constructs for metadata

API Versioning Standards

Another area where a range of standards have proliferated in the industry is around how you identify and manage API versions.  Your API Governance and Lifecycle should be able to take care of the creation of new versions, the time to live of those APIs and the retiring process of various versions of an API, but the version of the API itself is usually embedded somehow into the interaction model of the API itself such that it is fairly clear, by looking at the request or the URI, what version of that API is being used.

Payments Canada API Versioning Standard

The current Payments Canada versioning method is the Media Type accept header method. This allows the consumers of the API to control the content version with their request.

API Versioning Methods





Media Type
(Content Negotiation)
(Accept Header)

Customization of the 'Accept' media type header to include the version of the API:

Accept: application/payments.myapi.v2+json

Accept: Application/payments.api.article+json; version=1.0

You can version directly at the resource level (preserve your URIs between versions)

This is the closest to the original RESTful specification

Better for Proxy Caching

Harder to test as the versions are not shown on the URL

You will need something else than just a browser (i.e. API Store or developer tools) to explore the different versions

They distort the HTTP headers’ purpose: clients will need to know the media type for each resource and request the same one throughout their use of your API to ensure their code continues to function normally as you push out new changes.

(Custom) Headers

Creating header-specific versioning content in the API request:

X-API-Version: 2

Preserve your URIs between versions (because you do not add any version information to the URI)

Cleaner looking than the URI versioning method 

If you are already versioning resources with this technique, versioning the API as well can lead to a hard-to-manage configuration


Different versions of the API will take a different URI path

The most common method currently in use by APIs today

It allows exploring different versions with just a browser. (Enables visual identification of the version being requested)

Easy to use/understand

Better for Client caching

Can load balance versions separately

It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version)

Just like the 'Custom Headers' method, you should try to avoid this method if you are also versioning resources.

Not HATEOS compliant


Embeds the API Version into the domain name of the URI instead of the URI string:

The same pros as the URI method

easily routed to completely different servers

Interesting method if you want to write something very different for the same resource

Same cons as the URI method, plus users may have to change their security settings to be able to make calls to this new version

Not HATEOS compliant

(Request) Parameter

Use a parameter within the URI string to identify the version to be used:

GET /something/?version=0.1 HTTP/1.1

This is mostly indicated for JavaScript API (CORS-enabled APIs)

Just like the URI versioning allows visual identification

Can be optional (if no parameter is specified, the last version will be provided)

Mixing resource versions with this type of API versioning can get very messy

(Dynamic Date)

The initial request to the API sets that point in time via a timestamp to become their version reference until they choose to manually move the date up. Essentially the newest version of the API as of or prior to the timestamp.

Allows shipping new API features without changing an endpoint.

Being able to easily see which customers are using which versions of the API

It’s a bit complex to implement

Makes traceability of what has changed more difficult 

Dev needs to understand whether the timestamp is compilation time or the timestamp when the API was released)


API Naming Standards

As mentioned earlier in the document, REST’s primary data representation is called a Resource.  Having a strong and consistent REST resource naming strategy will prove to be one of the best design decisions in the long term.  Since RESTful APIs operate within the HTTP protocol, the resources are cataloged using a Uniform Resource Identifier and are presented in the same format as a web address i.e.

A resource can represent a single item or a collection of items. For example, “accounts” is a collection resource and “account” is a single-item resource. We can identify the “accounts” collection resource using the URI “/accounts”. We can identify a single “account” resource using the URI “/accounts/{accountId}”.

A resource can also contain a sub-collection of resources.  For example, the sub-collection resource “accounts” of a particular “customer” can be identified using the URI “/customers/{customerId}/accounts”. Similarly, a single resource “account” inside the sub-collection resource “accounts” can be identified as follows: “/customers/{customerId}/accounts/{accountId}”.

REST API designers should create URIs that convey the REST API’s resource model to its potential developers. When resources are named well, an API is intuitive and easy to use. 

Use nouns to represent resources

RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties as verbs do not – like resources have attributes. Some examples of resources are:

  • Users of the system
  • User Accounts
  • Network Devices etc.

and their resource URIs can be designed as below:


To make it even clearer, resources should be divided into four simple archetypes or categories: document; collection; store; or controller, a resource should then always be assigned to one of these archetypes, and its naming convention used consistently. For the sake of uniformity, resist the temptation to design resources that are hybrids of more than one archetype.

API Message Format

Selection of the API messaging format is critical to the success of the tooling, security and integration of the APIs with the rest of Payments Canada’s infrastructure.

ISO 20022 Implications on API Messages

At present, the ISO 20022 messaging formats for payments are rendered in both XML XSD format and ASN.1 format.  The ASN.1 format is good for older EDI interfaces, and the XML formats are aging rapidly.  We need to keep in mind that the ISO 20022 messages are meant to be format agnostic and that the renders available from ISO are published as guidelines and examples. Tooling for developing and publishing ISO 20022 is also designed to output in XML schemas. 

While the XML schemas may be largely easier to follow and understand, the format is too bulky and too hard to validate quickly in line with API-style operations.  The Tooling for APIs is moving forward faster than the tooling for ISO 20022.  Thus Payments Canada will look to provide all of their ISO 20022 messages for Canada in a variety of formats for simplified conversion and adoption of the messages.  The tools developing the messages will provide the base XML schemas as the reference point against the published standards from ISO.  This will then be converted into a JSON Schema and where necessary we will also publish the ProtoBuf message schema for any gRPC-based APIs that are implemented.

API Security

Authorization & Authentication

We leverage OAuth 2.0 where possible. OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This specification and its extensions are being developed within the IETF OAuth Working Group.


We require the use of SSL for all API calls.