Versions Compared

Old Version 2

changes.mady.by.user Freddi Gyara

Saved on

compared with

New Version Current

changes.mady.by.user Freddi Gyara

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
outlinetrue

...

VersionDateAuthorComments
3.0-draft1 OB R/W API Team

First draft of v3

Changes to align with the structure of Accounts & Transactions API

  • Removed Overview / Design Principles - RESTful APIs, Standards,  ISO 20022, Extensibility, Idempotency  and Status Codes
  • Removed Overview / Design Principles / Non-repudiation
  • Removed Overview / Scope 
  • Removed Overview / Out of Scope 
  • Removed Basics / Actors, Character Encoding, Date Formats, Resource URI Path Structure, Headers, Return & Error Codes, Pre-conditions, Idempotency, Non-repudiation, Filtering, Pagination, Regulatory Considerations
  • Endpoints section updated to cross-reference child pages with end-point details
  • Documentation for individual end-points moved into child pages
  • Removed section Data Model except for Identifier Fields, Enumerations and Mapping to Schemes & Standards
  • Removed section Usage Examples
3.0-draft2 OB R/W API Team
  • Modified Basics / Overview to add details about standing orders
  • Generalise references to Single Immediate Payments to Payment Orders or add Standing Order references where appropriate.
3.0-draft3 OB R/W API Team

Draft 3 changes:

  • OBRisk1 class moved to this page (from the Payment resource page)
  • Updated references to payment setup to payment-order consent; and references to payment submission to payment-order resource
  • Design Principles / Status Codes:
    • Removed reference in Status Codes to "The Security Working Group have stated that granular error codes may expose threat vectors - so these are limited to the HTTP Status Codes for v1.0." as this is under review
  • Generalised Basics / Overview section to payment-order consent and payment-order resource. Clarified consent step and differences in GET requests.
  • Removed Consent Authorisation / Payment Status section - as this has been moved into the payment-order type sub pages.
  • Updated Mapping to Schemes & Standards / Transaction Status
  • Removed DebtorAgent and CreditorAgent from FP and Bacs mappings.
  • Aligned GET operations Mandatory? flag with the equivalent resource POST.
  • In Endpoint section - removed reference to "must respond with a 404 (Not Found) for requests to that URL." and moved to Read Write API page.
3.0-draft4 OB R/W API Team

Errata:

  • Generalised the references of PaymentId and PaymentSubmissionId to ConsentId and Payment Order Id

Draft 4 Changes:

  • Updated Enumerations table - Remove deprecated statuses for OBTransactionIndividualStatus1Code
  • Updated Payment Limits section to Payment Restrictions - clarified behaviour if an ASPSP is unable to handle a payment-order request
3.0-draft5 OB R/W API Team

Draft 5 Changes:

  • New subpages for new payment-order types:
    • International Standing Orders
    • File Payments
  • Usage Examples moved back into payment-order type pages
  • Included status values in overview sequence diagram
  • Added CutOffDateTime in Payment Restrictions section
  • Removed OBExternalAccountIdentification2Code enumeration reference
  • Removed Mapping to Schemes and Standards section - and moved to a sub-page for Domestic Payment Message Formats
  • Usage Examples and Alternate flows are moved back to the individual specification pages. New alternate flow for CutOffDateTime behaviour.
  • Errata:
    • Spelling errors
    • Reference to consent for payment-order updated to payment-order consent (for consistency)
3.0-draft6/rc1 OB R/W API Team

Draft6 Changes:

  • Removed "request" in statements relating to rejection - so that the ASPSP may set the Status of a resource as "Rejected" in the case of a rejection. 
  • Updated references to PersonToPerson to PartyToParty - as it generalises to business to business payments.
  • Added Consent Authorisation / Multiple Authorisation section
  • Referenced Read/Write Data API Specification in overview.
  • Added Release Management in Basics section
  • Errata:
    • Spelling
    • Typo on MSD.
    • Moved table under Data Model / Enumerations to Daa Model / Enumerations / Static Enumerations
    • Added section for Data Model / Enumerations /Namespaced Enumerations
3.0-draft7 OB R/W API Team

Draft7 Changes:

  • Changed the Grant Type for GET Requests to be Client Credentials Only.
  • Added definitions of reused classes - OBCharge1, OBAuthorisation1 and OBMultiAuthorisation1, and
    • Removed from all Payment Order pages.
  • Added Post PSU Authentication guideline in Payment Initiation>Consent Authorisation>Multiple Authorisation Section
  • Added Multi-Auth Payment Order Consent flow
  • Added Enumeration definitions for completeness
  • Added webhook notifications as an option to notify a TPP that a multi auth flow is complete

Errata

  • In the Release Management Section, GET payment-order consent updated:
    A PISP must not access a payment-order ConsentId created in a previous newer version, via a newer previous version endpoint
3.0-RC2 OB R/W API Team

RC2 Changes:

  • Updated file types to UK.OBIE.pain.001.001.08 and UK.OBIE.PaymentInitiation.3.0.
  • Referred to Event Notification API Specification (renamed from Webhook Notification Specification).
  • Removed 'generalised for all payment types' comment on the Multi-Auth Payment Order Consent as specific to Domestic Payments.
  • Removed section on 'Handling Expired Access Tokens'
  • Added section on Consent Re-authorisation
  • Updated LocalInstrument Enumeration section to
    • Include wording of a "payment service"
    • Include international payment services 
  • CutOffDateTime Behaviour updated in accordance with draft Decision 162
  • Removed AuthorisationType "Multiple"
  • Changes to cater for CIBA
    • Modified Basics / Overview / Steps
    • Added  alternative Sequence Diagram for Decoupled Flow
    • Updated Grant Types
  • Clarification - the OBMultiAuthorisation1/NumberRequired field is the total number required at the start of the multi authorisation journey
  • Added Swagger specification.
3.0-RC3 OB R/W API Team

RC3 Changes:

  • Added BalanceTransfer and MoneyTransfer to Namespaced Enumerations for LocalInstrument:
    • UK.OBIE.BalanceTransfer
    • UK.OBIE.MoneyTransfer
  • Clarified that an ASPSP may optionally return a CutOffDateTime.
  • Renamed Consent Re-authorisation to Consent Re-authentication
    • Added UK.OBIE.Link as a LocalInstrument enumeration. 
  • Clarified the definitions for the FileTypes in the core UK.OBIE.* namespace
    • Added Swagger-based API specification files encoded in JSON and YAML.
3.0 OB R/W API Team

This is the baseline version. No change from RC3.

Swagger URLs updated to point to latest stable version.

Overview

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

...

  • A PISP must use a payment-order consent ConsentId within the same version to create the payment-order resource (in that version)
    • E.g., A v3 payment-order consent can only be used to create a payment-order resource in v3.
  • An ASPSP must not allow a PISP to use a ConsentId from a previous version to create Payment Order in a newer version, and vice versa

...

  • A PISP must refer to the ASPSP's online Developer Portal for guidelines on accessibility of a payment-order resource in a newer version
  • A PISP must not access the payment-order resource types introduced in a newer version, on an older version endpoint
    • E.g., an international-payment created in v3, that is accessed via the v1 payment-submissions endpoint
  • A PISP must not access the payment-order resource created in a newer version on an older version endpoint
    • E.g., for a domestic-payment resource created in v3, access via the v1 payment-submissions endpoint is not permitted
  • An ASPSP must document the behaviour on the accessibility of a payment-order resource in a newer version on ASPSP's online Developer Portal
  • An ASPSP must allow access to the payment-order resource created in a previous version on a newer version endpoint (depending on an ASPSP's legal requirement for data retention):
    • E.g., a payment-submission created in v1, must be accessible as a v3 domestic-payment, with sensible defaults for additional fields introduced in v3 (e.g., if an ASPSP must make payment resources available for 7 years).
    • In the case where a payment-order type is same, but the structure is changed in a newer version - sensible defaults may be used, with ASPSP's Developer Portal clearly specifying the behaviour.
      • E.g., a new field StatusUpdateDateTime was introduced in v3 - an ASPSPs must populate with this with the last status update time - as the StatusUpdateDateTime is a mandatory field

...

PISPs must use a client credentials grant to obtain a token to make POST requests to the payment-order consent endpoints. In the specification, this grant type is referred to as "Client Credentials".

PISPs must use grant using a redirect or decoupled flow to obtain a token to make POST requests to the payment-order resource endpoints. In the specification, this grant type is referred to as "Authorization Code".

...

The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

...

The Swagger Specification for Payment Initiation APIs can be downloaded from the following links:

Data Model

Reused Classes

OBRisk1

...

GeneratedIdentifierBusiness Description

Merchant/PISP

Sent in API Payload

EndToEndIdentificationThe EndToEndIdentification reference is a reference that can be populated by the debtor (or merchant in the ecommerce space). This reference is important to the debtor (could be an internal reference Id against the transaction), it Is NOT the reference information that will be primarily populated on the statement of the creditor (beneficiary).

Merchant/PISP

Sent in API Payload

InstructionIdentification

PISP generates the InstructionIdentification which is a unique transaction Id and passes it to the ASPSP (this is mandatory), but this doesn’t have to go any further in the payment flow. The flow of this identifier needs to align with payment scheme rules.

The expectation is that this is unique indefinitely across all time periods. The PISP can ensure this is indefinitely unique by including a date or date time element to the field, or by inserting a unique Id.

Merchant/PISP

Sent in API Payload

RemittanceInformationThe RemittanceInformation is the reference information that creditor (or beneficiary) will need to reconcile (e.g. Invoice 123).

ASPSP / API System

ConsentIdUnique identification as assigned by the ASPSP to uniquely identify the payment-order consent resource.
ASPSP / API System

Payment Order Id

Unique identification as assigned by the ASPSP to uniquely identify the payment-order resource.

DomesticPaymentId

DomesticScheduledPaymentId

DomesticStandingOrderId

InternationalPaymentId

InternationalScheduledPaymentId

ASPSP / Payment Scheme

Scheme Payment IDThis is generated by the ASPSP to uniquely identify a payment through a processing scheme. In the case of FPS - this is the FPID.

...

Code ClassName Definition 
OBExternalPaymentContext1CodeBillPaymentThe context of the payment initiation is a bill payment.
OBExternalPaymentContext1CodeEcommerceGoodsThe context of the payment initiation is a for goods via an ecommerce channel.
OBExternalPaymentContext1CodeEcommerceServicesThe context of the payment initiation is a for services via an ecommerce channel.
OBExternalPaymentContext1CodePartyToPartyThe context of the payment initiation is a party to party payment.
OBExternalPaymentContext1CodeOtherThe context of the payment initiation is of an other type.
OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted

Settlement on the debtor's account has been completed.

Usage : this can be used by the first agent to report to the debtor that the transaction has been completed. Warning : this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

PISPs must not use this status as confirmation that settlement is complete on the creditor's account.

OBTransactionIndividualStatus1CodeAcceptedSettlementInProcessAll preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
OBTransactionIndividualStatus1CodePendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
OBTransactionIndividualStatus1CodeRejectedPayment initiation or individual transaction included in the payment initiation has been rejected.
OBExternalConsentStatus1CodeAwaitingAuthorisationThe consent resource is awaiting PSU authorisation.
OBExternalConsentStatus1CodeRejectedThe consent resource has been rejected.
OBExternalConsentStatus1CodeAuthorisedThe consent resource has been successfully authorised.
OBExternalConsentStatus1CodeConsumedThe consented action has been successfully completed. This does not reflect the status of the consented action.
OBChargeBearerType1CodeBorneByCreditorAll transaction charges are to be borne by the creditor.
OBChargeBearerType1CodeBorneByDebtorAll transaction charges are to be borne by the debtor.
OBChargeBearerType1CodeFollowingServiceLevelCharges are to be applied following the rules agreed in the service level and/or scheme.
OBChargeBearerType1CodeSharedIn a credit transfer context, means that transaction charges on the sender side are to be borne by the debtor, transaction charges on the receiver side are to be borne by the creditor. In a direct debit context, means that transaction charges on the sender side are to be borne by the creditor, transaction charges on the receiver side are to be borne by the debtor.
OBExternalAuthorisation1CodeAnyAny authorisation type is requested.
OBExternalAuthorisation1CodeMultipleMultiple authorisation type is requested.
OBExternalAuthorisation1CodeSingleSingle authorisation type is requested.
OBExternalStatus1CodeInitiationCompletedThe payment-order initiation has been completed.
OBExternalStatus1CodeInitiationFailedThe payment-order initiation has failed.
OBExternalStatus1CodeInitiationPendingThe payment-order initiation is pending.
OBExternalStatus2CodeAuthorisedThe multiple authorisation flow has been fully authorised.
OBExternalStatus2CodeAwaitingFurtherAuthorisationThe multiple authorisation flow is awaiting further authorisation.
OBExternalStatus2CodeRejectedThe multiple authorisation flow has been rejected.
OBExchangeRateType2CodeActualExchange rate is the actual rate.
OBExchangeRateType2CodeAgreedExchange rate is the agreed rate between the parties.
OBExchangeRateType2CodeIndicativeExchange rate is the indicative rate.
OBPriority2CodeNormalPriority is normal.
OBPriority2CodeUrgentPriority is urgent.
OBAddressTypeCodeBusinessAddress is the business address.
OBAddressTypeCodeCorrespondenceAddress is the address where correspondence is sent.
OBAddressTypeCodeDeliveryToAddress is the address to which delivery is to take place.
OBAddressTypeCodeMailToAddress is the address to which mail is sent.
OBAddressTypeCodePOBoxAddress is a postal office (PO) box.
OBAddressTypeCodePostalAddress is the complete postal address.
OBAddressTypeCodeResidentialAddress is the home address.
OBAddressTypeCodeStatementAddress is the address where statements are sent.

...