/
Payment Initiation API Specification - v3.1.1

Payment Initiation API Specification - v3.1.1

Apr 12, 2019

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

3.0

Sep 7, 2018 

OB R/W API Team

This is the baseline version. No change from RC3.

Swagger URLs have been updated to point to the latest stable version.

3.1-draft1

Sep 11, 2018 

OB R/W API Team

This is the initial draft version for 3.1.

Errata

  • Grammatical Fixes

3.1-draft2

Oct 1, 2018 

OB R/W API Team

Draft2 Changes:

  • Confirmation of Funds for PISP changes.

  • Updated file type enumeration UK.OBIE.PaymentInitiation.3.0 to UK.OBIE.PaymentInitiation.3.1.

3.1-draft3

Oct 11, 2018 

OB R/W API Team

Draft3 Changes:

  • Removed OBFundsConfirmationConsentType1Code

  • Namespaced Enumerations are moved to a separate page

  • Charge Data Model updated with a typed field for Charge/Type to reference in Namespaced Enumerations page.

  • Added the step “The PSU selects the debtor account at this stage (if it has not been previously specified in Step 1)” in payment sequence

  • Swagger Specification updated.

Errata

  • Fixed the type for ../Amount/Amount field from ActiveCurrencyAndAmount_SimpleType to OBActiveCurrencyAndAmount_SimpleType

3.1-draft4

Nov 6, 2018 

OB R/W API Team

Draft4 Changes:

  • Added a section "ISO enumerations" for fields which are using ISO defined enumeration

  • Swagger Specification updated.

3.1-rc1

Nov 12, 2018 

OB R/W API Team

RC1 Changes:

  • Removed ExternalPurpose1Code from ISO Enumerations used list

  • Fixed the OBCharge2 class naming error

  • Swagger Specification links updated

3.1

Nov 30, 2018

OB R/W API Team

Version 3.1 final release.

No changes from Version 3.1 RC1.

Dec 12, 2018 Updated swagger links to latest release candidate.

3.1.1-draft1

Jan 31, 2019 

OB R/W API Team

v3.1.1 RC1 changes:

  • Clarified a PISP can optionally confirm available funds for an international scheduled (immediate debit) payments in Overview section.

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a general payment-order. 

The API endpoints described here allow a PISP to: 

  • Register an intent to stage a payment-order consent.

  • Optionally confirm available funds for a payment-order

    • Domestic immediate, international immediate and international scheduled (immediate debit) payments only.

  • Subsequently submit the payment-order for processing.

  • Optionally retrieve the status of a payment-order consent or payment-order resource.

This specification should be read in conjunction with Read/Write Data API Specification which provides a description of the elements that are common across all the Read/Write Data APIs.

Document Overview

This document consists of the following parts:

Overview: Provides an overview of the API and the key decisions and principles that contributed to the specification.

Basics: The section begins with an introduction to how the API is to be used to initiate a payment order, using the example of a single immediate payment. It goes on to identify the resources and operations that are permitted on those resources and various special cases.

Security & Access Control: Specifies the means for PISPs and PSUs to authenticate themselves and provide consent.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Data Model: Describes the data model for the API payloads.

Usage Examples: Provides examples for normal flows, and alternate flows.

Design Principles

Scheme Agnostic

The API has been be designed so that it is agnostic to the underlying payment scheme that is responsible for carrying out the payment.

In doing so, this means we will not design field lengths and payloads to only match the Faster Payments message, and will instead rely on the field lengths and definitions in ISO 20022. Due diligence has been carried out to ensure that the API has the necessary fields to function with Bacs payments as per the agreed scope.

Further mapping guidance has been provided to ensure that differences are understood between the Open Banking Payment API standard, and other message formats in the Domestic Payment Message Formats sub-page.

Status Codes

The API uses two status codes that serve two different purposes:

  • The HTTP Status Code reflects the outcome of the API call (the HTTP operation on the resource).

  • The Status field for the payment-order consent reflects the status of the PSU consent authorisation.

  • The Status field for the payment-order resource reflects the status of the payment-order initiation or execution.

Basics

Overview

The figure below provides a general outline of a payment flow for all payment-order types using the Payment APIs. The payment-order types covered in this specification include:

  • Domestic payments.

  • Domestic scheduled payments.

  • Domestic standing orders.

  • International payments.

  • International scheduled payments.

The payment-order consent and payment-order resource in the following flow generalises for the different payment-order types. e.g. for a domestic payment, the payment-order consent resource is domestic-payment-consents; and the payment-order resource is domestic-payments.