Payment Initiation API Specification - v2

Coventry Building Society Payment Initiation API Specification V2.0

Contents

Coventry Building Society ....................................................................................................................................................1 Version control .....................................................................................................................................................................5 Release Note .......................................................................................................................................................................5 Overview ..............................................................................................................................................................................5

Document Overview ........................................................................................................................................................5 Design Principles .............................................................................................................................................................6

RESTful APIs...............................................................................................................................................................6 Idempotency ................................................................................................................................................................6 Payment API - Scheme Agnostic ................................................................................................................................6 Status Codes ...............................................................................................................................................................6 Scope ...............................................................................................................................................................................6 Out of Scope ....................................................................................................................................................................7 Basics ...................................................................................................................................................................................7 Steps ...........................................................................................................................................................................7 Sequence Diagram....................................................................................................................................................10 Actors .............................................................................................................................................................................11 Character Encoding .......................................................................................................................................................11 Date Formats .................................................................................................................................................................11 Resource URI Path Structure ........................................................................................................................................12 Payment Limits. .............................................................................................................................................................12 Headers .........................................................................................................................................................................12 Request Headers.......................................................................................................................................................12 Response Headers....................................................................................................................................................13 Return & Error Codes ....................................................................................................................................................13 400 (Bad Request) v/s 404 (Not Found) ...................................................................................................................14 403 (Forbidden) .........................................................................................................................................................14 422 (Invalid)...............................................................................................................................................................14 429 (Too Many Requests) .........................................................................................................................................15 Pre-Conditions ...............................................................................................................................................................15 Pre-conditions for TPPs ............................................................................................................................................15 Idempotency ..................................................................................................................................................................15 Filtering ..........................................................................................................................................................................16 Pagination ......................................................................................................................................................................16 Regulatory Considerations ............................................................................................................................................16 PSD2 - Article 48 .......................................................................................................................................................16 Endpoints ...........................................................................................................................................................................16 POST /token ..................................................................................................................................................................17

POST /open-banking/v2.0/payments.............................................................................................................................17 Payment Status .........................................................................................................................................................18 Error Information........................................................................................................................................................18

GET /open-banking/v2.0/payments/{PaymentId} ..........................................................................................................19 Payment Status .........................................................................................................................................................19 Error Information........................................................................................................................................................19

POST /open-banking/v2.0/payment-submissions .........................................................................................................21 Payment Submission Status .....................................................................................................................................21 Error Information........................................................................................................................................................21

GET /open-banking/v2.0/payment-submissions/{PaymentSubmissionId} ....................................................................22 Payment Submission Status .....................................................................................................................................22 Error Information........................................................................................................................................................22

GET /open-banking/v2.0/payments/{PaymentId}/funds-confirmation............................................................................23 Error Information........................................................................................................................................................23

POST /open-banking-extensions/v2.0/mandates ..........................................................................................................24 Payment Status .........................................................................................................................................................24 Error Information........................................................................................................................................................25

GET /open-banking-extensions/v2.0/mandates/{PaymentId}.......................................................................................27 Payment Status .........................................................................................................................................................27 Error Information........................................................................................................................................................27

POST /open-banking-extensions/v2.0/mandate-submissions......................................................................................28 Payment Submission Status .....................................................................................................................................29 Error Information........................................................................................................................................................29

GET /open-banking-extensions/v2.0/mandate-submissions/{PaymentSubmissionId}..................................................29 Payment Submission Status .....................................................................................................................................30 Error Information........................................................................................................................................................30

Sandbox API Endpoints .....................................................................................................................................................31 Security & Access Control..................................................................................................................................................31

API Scopes ....................................................................................................................................................................31 Grants Types .................................................................................................................................................................31 Consent Authorisation ...................................................................................................................................................32

Payment Status .........................................................................................................................................................32 Error Condition ..........................................................................................................................................................32 Consent Revocation ..................................................................................................................................................32 Changes to Selected Account ...................................................................................................................................32 Handling Expired Access Tokens..............................................................................................................................34 Data Model .........................................................................................................................................................................34 High Level Payload Structure ........................................................................................................................................34 Request Structure......................................................................................................................................................34

Response Structure...................................................................................................................................................35 Data Payload .................................................................................................................................................................35

Payment Setup - Request .........................................................................................................................................35 Payment Setup - Response ......................................................................................................................................39 Payment Submission - Request ................................................................................................................................43 Payment Submission - Response .............................................................................................................................47 Payments/{PaymentId}/funds-confirmation - Response............................................................................................47 Mandates setup - Request ........................................................................................................................................48 Mandates setup ? Response.....................................................................................................................................53 Mandate Submission - Request ................................................................................................................................58 Mandate Submission - Response .............................................................................................................................62 Data Payload ? Error Response Structure ....................................................................................................................63 Example.....................................................................................................................................................................63 Data Payload - Enumerations........................................................................................................................................64 Identifier Fields...............................................................................................................................................................65 Merchant Flow ...........................................................................................................................................................66 Person to Person Flow ..............................................................................................................................................66 Mapping to Schemes & Standards ................................................................................................................................67 Transaction Status.....................................................................................................................................................67 Usage Examples ................................................................................................................................................................67 Merchant ........................................................................................................................................................................67 Sequence Diagram....................................................................................................................................................69 Illustrative Interactions ...................................................................................................................................................70 POST /payments request ..........................................................................................................................................70 POST /payment-submissions Request .....................................................................................................................71 GET /payments Request ...........................................................................................................................................72 GET /payment-submissions Request........................................................................................................................74 GET /payments/{PaymentId}/funds-confirmation ......................................................................................................74 POST /mandates Request ........................................................................................................................................75 POST /mandate-submissions Request .....................................................................................................................77 GET /mandates Request ...........................................................................................................................................80 GET /payment-submissions Request........................................................................................................................83 Alternative and Error Flows................................................................................................................................................84 Idempotent Payment Setup ...........................................................................................................................................84 Idempotent Payment Submission ..................................................................................................................................85 Missing or Expired Access Token..................................................................................................................................86 Incomplete or Malformed Request Payload ..................................................................................................................87

Version control

Version 1.0 1.1 2.0

Date 07 Feb 2018 13 Feb 2019 28 Feb 2019

Updated by Coventry Building Society Coventry Building Society Coventry Building Society

Changes made

Baseline version

Addition of token endpoints

New error contract for all APIs Additional confirm funds endpoint Additional data models for mandates and mandatesubmissions

Release Note

This release note explains what's new in The Payment API Specifications between versions.

Version 2.0 ? Changes

Our APIs follow OpenBanking:

Payment API Specification v1.1 for immediate payments. For version 1.1, CBS created endpoints for mandates (future dated and regular) under open-banking-

extensions as these had not been defined in the OpenBanking Payment API Specfication v1.1. error response structure as defined in OpenBanking Payment API Specification v3.1. These comprise of:

o The error contract for each API has been modified to comply with the OpenBanking Read/Write Data API Specification v3.1. defined contract.

o A new funds-confirmation endpoint added as per OpenBanking Payment Intitiation API Specification\Domestic Payments v3.1

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a single immediate payment, regular payment and future dated payment.

The API endpoints described here allow a PISP to:

Register an intent to setup a payment instruction Subsequently submit the payment instruction for processing Optionally retrieve the status of a payment setup or submission.

Document Overview

This document consists of the following parts:

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

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download