Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel1
stylenone

1.        Overview

The Payment Initiation API Profile describes the flows and common functionality for the Payment Initiation API, which allows a Payment Initiation Service Provider ('PISP') to:

...

This profile should be read in conjunction with a compatible Read/Write Data API Profile , which provides a description of the elements that are common across all the Read/Write Data APIs, and compatible individual resources.

1.1

...

Document Overview

This document consists of the following parts:

...

Alternative Flows: Documents rules for alternative flows

1.2

...

Resources

Each of the Payment Initiation API resources are documented in the Resources and Data Models / PISP area of the specification. Each resource is documented with:

  • Endpoints

    • The API endpoints available for the resource.

  • Data Model

    • Resource definition.

    • UML diagram.

    • Data dictionary - which defines fields, re-usable classes, mandatory (1..1) or conditional (0..1) as defined in the Design Principles section, and enumerations.

  • Usage Examples

1.

...

Design Principles

1.3.1 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.

2.        Basics

2.

...

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 profile include:

...

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.

...

2.1.1 Steps

Step 1: Agree Payment-Order Initiation

...

  • The PISP can check the status of the payment-order consent (with the ConsentId) or payment-order resource (with the payment-order resource identifier) or payment-details (with the payment-order resource identifier).

  • This is carried out by making a GET request to the payment-order consent or payment-order or payment-details resource  

2.1.2 Sequence Diagram

 

...

2.

...

Payment Restrictions

The standard does not provide a uniform set of restrictions for payment-order types that can be supported through this API.

...

An ASPSP must reject the payment-order consent if the ASPSP is unable to handle the request.

2.2.1 CutOffDateTime Behaviour

An ASPSP may return the specific CutOffDateTime when responding to a payment-order consent request.

...

  • Reject the payment-order (and steps associated with the creation of payment-order) if received after the applicable CutOffDateTime

  • Accept the payment-order (and steps associated with the creation of payment-order) if received after the applicable CutOffDateTime

2.2.1.1  Reject the Payment-Order

In this scenario, the behaviour of payment-order execution is explicit to the PISP and PSU.

...

For a payment-order consent or a payment-order resource that has been rejected due to the elapsed CutoffDateTime, the PISP may decide to create a corresponding future dated payment endpoint to create a new payment-order consent. The PISP may use the /domestic-future-dated-payment-consents endpoint to create a consent for the same payment for the next working day.

2.2.1.2  Accept the Payment-Order

In this scenario, the behaviour of the payment-order execution is not explicit to the PISP and PSU, and the payment-order will be executed on the next available working day.

  • An ASPSP must accept the payment-order consent if the CutOffDateTime for a specific payment-order type has elapsed.

  • An ASPSP must accept an authorisation request when the underlying intent object is associated with a CutoffDateTime that has elapsed.

  • An ASPSP must accept the payment-order resource if the CutOffDateTime for a specific payment-order type, has been established and has elapsed.

  • An ASPSP may update the payment-order consent or payment-order resource with the CutOffDateTime, ExpectedExecutionDateTime and ExpectedSettlementDateTime, to communicate expected execution behaviour if the CutOffDateTime has elapsed 

2.

...

Release Management

This section overviews the release management and versioning strategy for the Payment Initiation API. It applies to all Payment Order Consent and Payment Order resources, specified in the Endpoints section.

2.3.1 Payment-Order Consent

2.3.1.1  POST

  • A PISP must not create a payment-order consent ConsentId on a newer version and use it to create a payment-order resource in a previous version

    • E.g., A ConsentId created in v3, must not be used to create a v1 PaymentSubmissionId

  • A PISP must not create a payment-order consent ConsentId on a previous version and use it to create a payment-order resource in a newer version

    • E.g., A PaymentId created in v1, must not be used to create a v3 DomesticPaymentId

2.3.1.2  GET

  • A PISP must not access a payment-order ConsentId created in a newer version, via a previous version endpoint

    • E.g., A ConsentId created in v3 accessed via a v1 PaymentId

  • An  ASPSP may choose to make ConsentIds accessible across versions

    • E.g., for a PaymentId created in v1, an ASPSP may or may not make it available via v3, as this is a short-lived consent

2.3.2 Payment-Order Consent (Confirm Funds)

2.3.2.1  GET

  • A PISP must not confirm funds using a payment-order-consent ConsentId created in a different version.

    • E.g. A ConsentId created in v3, must not be used to confirm funds on a v1 endpoint.

2.3.3 Payment-Order Resource

2.3.3.1  POST

  • 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 a Payment Order in a newer version, and vice versa

2.3.3.2  GET

  • 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, which 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 the 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 the same, but the structure has changed in a newer version, sensible defaults may be used, with the ASPSP's Developer Portal clearly specifying the behaviour.

    • E.g., a new field StatusUpdateDateTime was introduced in v3, an ASPSPs must populate this with the last status update time (as the StatusUpdateDateTime is a mandatory field).

3.        Security & Access Control

3.1

...

Scopes

The access tokens required for accessing the Payment APIs must have at least the following scope:

payments: Generic payment scope

3.2

...

Grants Types

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 a client credentials grant to obtain a token to make GET requests (excluding confirming funds).

3.3

...

Consent Authorisation

OAuth 2.0 scopes are coarse-grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine-grained scopes e.g., a scope to enforce payments of a specified amount on a specified date.

...

Once these steps are complete, the consent is considered to have been authorised by the PSU.

3.3.1 Error Condition

If the PSU does not complete a successful consent authorisation (e.g., if the PSU has not authenticated successfully), the authorisation code grant ends with a redirection to the TPP with an error response. The PSU is redirected to the TPP with an error parameter indicating the error that occurred.

3.3.2 Consent Revocation

A PSU cannot revoke a payment-order consent once it has been authorised.

3.3.3 Changes to Selected Account

For a payment-order consent, the selected debtor account cannot be changed once the consent has been authorised.

3.3.4 Consent Re-authentication

Payment consents are short-lived and cannot be re-authenticated by the PSU.

3.4

...

Risk Scoring

...

Information 

Information for risk scoring and assessment will come via:

...

Payments for EcommerceGoods and EcommerceServices will be expected to have a MerchantCategoryCode and MerchantCustomerIdentification populated. Payments for EcommerceGoods will also have the DeliveryAddress populated.

4.        Data Model

4.

...

Reused Classes

4.1.1 OBRisk

This section describes the OBRisk class which is reused in the payment-order consent and payment-order resources.

4.1.1.1  UML Diagram

...

4.1.1.2  Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBRisk

 

OBRisk

The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments.

OBRisk

 

 

PaymentContextCode 

0..1

OBRisk/PaymentContextCode

Specifies the payment context

Stirng

Enum:

  • BillPayment

  • EcommerceGoods

  • EcommerceServices

  • Other

  • PartyToParty

 

MerchantCategoryCode

0..1

OBRisk/MerchantCategoryCode

Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.

String

 

 

MerchantCustomerIdentification

0..1

OBRisk/MerchantCustomerIdentification

The unique customer identifier of the PSU with the merchant

String

 

 

DeliveryAddress

0..1

OBRisk/DeliveryAddress

Information that locates and identifies a specific address, as defined by postal services or in free format text.

OBRisk/DeliveryAddress

 

 

AddressLine

0..7

OBRisk/DeliveryAddress/AddressLine

Information that locates and identifies a specific address, as defined by postal services, presented in free format text.

String

 

 

StreetName

0..1

OBRisk/DeliveryAddress/StreetName

Name of a street or thoroughfare

String

BuildingNumber

0..1

OBRisk/DeliveryAddress/BuildingNumber


Number that identifies the position of a building on a street

String

 

 

PostCode

0..1

OBRisk/DeliveryAddress/PostCode

Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail

String

 

 

TownName

0..1

OBRisk/DeliveryAddress/TownName

Name of a built-up area, with defined boundaries, and a local government

String

 

 

CountrySubDivision

0..1

OBRisk/DeliveryAddress/CountrySubDivision


Identifies a subdivision of a country, for instance state, region

String

 

 

Country

0..1


OBRisk/DeliveryAddress/Country


Nation with its own government, occupying a particular territory.

String

 


^[A-Z]{2,2}$

4.1.2 OBCharge

This section describes the OBCharge class - which is reused in the response payloads in the payment-order consent and payment-order resources.

4.1.2.1  UML Diagram

 

...

4.1.2.2  Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBCharge

 

OBCharge

Set of elements used to provide details of a charge for the payment initiation.

OBCharge

 

 

ChargeBearer

1..1

OBCharge/ChargeBearer

Specifies which party/parties will bear the charges associated with the processing of the payment transaction.

String

Enum:

  • BorneByCreditor

  • BorneByDebtor

  • FollowingServiceLevel

  • Shared

 

Type

1..1

OBCharge/Type

Charge type, in a coded form.

String

Enum:

·  To be determined

 

 

Amount

1..1

OBCharge/Amount

Amount of money associated with the charge type.

OBActiveOrHistoricCurrencyAndAmount

 

 

Amount

1..1

OBCharge/Amount/Amount

A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.

String

 

^\d{1,13}.\d{1,5}$

Currency

1..1

OBCharge/Amount/Currency

A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".

String

 

^[A-Z]{3,3}$

 

4.1.3 OBAuthorisation

This section describes the OBAuthorisation class which is used in the payment-order consent request and payment-order consent response payloads.

4.1.3.1  UML Diagram

...

4.1.3.2  Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBAuthorisation

 

OBAuthorisation

The authorisation type request from the TPP.

OBAuthorisation

 

 

AuthorisationType

1..1

OBAuthorisation/AuthorisationType

Type of authorisation flow requested.

String

Enum:

  • Single

 

CompletionDateTime

0..1

OBAuthorisation/CompletionDateTime

Date and time at which the requested authorisation flow must be completed.

DateTime

 

 

 

4.1.4 OBDomesticRefundAccount

This section describes the OBDomesticRefundAccount class which is used in the response payloads of Domestic Payment, Domestic Future Dated Payment and Domestic Standing Order.

4.1.4.1  UML Diagram

...

4.1.4.2  Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBDomesticRefundAccount

 

OBDomesticRefundAccount

Unambiguous identification of the refund account to which a refund will be made as a result of the transaction.

OBDomesticRefundAccount

 

 

Account

1..1

OBDomesticRefundAccount/Account

Provides the details to identify an account.

OBDomesticRefundAccount/Account

 

 

SchemeName

1..1

OBDomesticRefundAccount/Account/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

String

Enum:

  • BH.OBF.BBAN

  • BH.OBF.IBAN

  • BH.OBF.PAN

 

Identification

1..1

OBDomesticRefundAccount/Account/Identification

Identification assigned by an institution to identify an account. This identification is known by the account owner.

String

 

 

Name

0..1

OBDomesticRefundAccount/Account/Name

Name of the account, as assigned by the account servicing institution. Usage: The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account. OB: ASPSPs may carry out name validation for Confirmation of Payee, but it is not mandatory.

String

 

 

 

4.1.5        OBInternationalRefundAccount

This section describes the OBInternationalRefundAccount class which is used in the response payloads of International Payment, International Future Dated Payment and International Standing Order.

4.1.5.1   UML Diagram

 

...

4.1.5.2   Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBInternationalRefundAccount

 

OBInternationalRefundAccount

Unambiguous identification of the refund account to which a refund will be made as a result of the transaction.

OBInternationalRefundAccount

 

 

Creditor

0..1

OBInternationalRefundAccount/Creditor

Party to which an amount of money is due.

OBInternationalRefundAccount/Creditor

 

 

Name

0..1

OBInternationalRefundAccount/Creditor/Name

Name by which a party is known and which is usually used to identify that party.

String

 

 

PostalAddress

0..1

OBInternationalRefundAccount/Creditor/PostalAddress

Information that locates and identifies a specific address, as defined by postal services.

OBPostalAddress

 

 

AddressType

0..1

OBInternationalRefundAccount/Creditor/PostalAddress/AddressType

Identifies the nature of the postal address.

String

Enum:

  • Business

  • Correspondence

  • DeliveryTo 

  • MailTo 

  • POBox 

  • Postal 

  • Residential

  • Statement

 

Department

0..1

OBInternationalRefundAccount/Creditor/PostalAddress/Department

Identification of a division of a large organisation or building.

String

 

 

SubDepartment

0..1

OBInternationalRefundAccount/Creditor/PostalAddress/SubDepartment

Identification of a sub-division of a large organisation or building.

String

 

 

AddressLine

0..7

OBInternationalRefundAccount/Creditor/PostalAddress/AddressLine

Information that locates and identifies a specific address, as defined by postal services, presented in free format text.

String

 

 

StreetName

0..1

 OBInternationalPaymentInitiation/Creditor/PostalAddress/StreetName

Name of a street or thoroughfare

String

BuildingNumber

0..1

 OBInternationalPaymentInitiation/Creditor/PostalAddress/BuildingNumber

Number that identifies the position of a building on a street

String

 

 

PostCode

0..1

 OBInternationalPaymentInitiation/Creditor/PostalAddress/PostCode

Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail

String

 

 

TownName

0..1

 OBInternationalPaymentInitiation/Creditor/PostalAddress/TownName

Name of a built-up area, with defined boundaries, and a local government

String

 

 

CountrySubDivision

0..1

 OBInternationalPaymentInitiation/Creditor/PostalAddress/CountrySubDivision

Identifies a subdivision of a country such as state, region, country

String

 

 

Country

0..1

OBInternationalRefundAccount/Creditor/PostalAddress/Country

Nation with its own government.

String

 

^[A-Z]{2,2}$

Agent

0..1

OBInternationalRefundAccount/Agent

Financial institution servicing an account for the creditor.

OBInternationalRefundAccount/Agent

 

 

SchemeName

0..1

OBInternationalRefundAccount/Agent/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

String

 Enum:

  • BH.OBF.IBAN 

 

 

Identification

0..1

OBInternationalRefundAccount/Agent/Identification

Unique and unambiguous identification of a financial institution or a branch of a financial institution.

String

 

 

Name

0..1

OBInternationalRefundAccount/Agent/Name

Name by which an agent is known and which is usually used to identify that agent.

String

 

 

PostalAddress

0..1

OBInternationalRefundAccount/Agent/PostalAddress

Information that locates and identifies a specific address, as defined by postal services.

OBPostalAddress

 

 

AddressType

0..1

OBInternationalRefundAccount/Agent/PostalAddress/AddressType

Identifies the nature of the postal address.

String

Enum:

  • Business

  • Correspondence

  • DeliveryTo 

  • MailTo 

  • POBox 

  • Postal 

  • Residential

  • Statement

 

Department

0..1

OBInternationalRefundAccount/Agent/PostalAddress/Department

Identification of a division of a large organisation or building.

String

 

 

SubDepartment

0..1

OBInternationalRefundAccount/Agent/PostalAddress/SubDepartment

Identification of a sub-division of a large organisation or building.

String

 

 

AddressLine

0..7

OBInternationalRefundAccount/Agent/PostalAddress/AddressLine

Information that locates and identifies a specific address, as defined by postal services, presented in free format text.

String

 

 

StreetName

0..1

 OBInternationalPaymentInitiation/CreditorAgent/PostalAddress/StreetName

Name of a street or thoroughfare

String

BuildingNumber

0..1

 OBInternationalPaymentInitiation/CreditorAgent/PostalAddress/BuildingNumber

Number that identifies the position of a building on a street

String

 

 

PostCode

0..1

 OBInternationalPaymentInitiation/CreditorAgent/PostalAddress/PostCode

Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail

String

 

 

TownName

0..1

 OBInternationalPaymentInitiation/CreditorAgent/PostalAddress/TownName

Name of a built-up area, with defined boundaries, and a local government

String

 

 

CountrySubDivision

0..1

 OBInternationalPaymentInitiation/CreditorAgent/PostalAddress/CountrySubDivision

Identifies a subdivision of a country such as state, region, country

String

 

 

Country

0..1

OBInternationalRefundAccount/Agent/PostalAddress/Country

Nation with its own government.

String

 

^[A-Z]{2,2}$

Account

1..1

OBInternationalRefundAccount/Account

Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.

OBInternationalRefundAccount/Account

 

 

SchemeName

1..1

OBInternationalRefundAccount/Account/SchemeName

Name of the identification scheme, in a coded form as published in an external list.

String

 Enum:

  • BH.OBF.IBAN

 

Identification

1..1

OBInternationalRefundAccount/Account/Identification

Identification assigned by an institution to identify an account. This identification is known by the account owner.

String

 

 

Name

1..1

OBInternationalRefundAccount/Account/Name

The account name is the name or names of the account owner(s) represented at an account level. Note, the account name is not the product name or the nickname of the account. OB: ASPSPs may carry out name validation for Confirmation of Payee, but it is not mandatory.

String

 

 

 

4.1.6 OBWritePaymentDetails

This section describes the OBWritePaymentDetails class which used in the response payloads of payment-detail sub resources.

4.1.6.1  UML Diagram

...

4.1.6.2  Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBWritePaymentDetails

 

OBWritePaymentDetails

Payment status details.

OBWritePaymentDetails

 

 

PaymentTransactionId

1..1

OBWritePaymentDetails/PaymentTransactionId

Unique identifier for the transaction within an servicing institution. This identifier is both unique and immutable

String

 

 

Status

1..1

OBWritePaymentDetails/Status

Status of a transfer, as assigned by the transaction administrator.

String

Enum:

  • Accepted

  • AcceptedCancellationRequest

  • AcceptedCreditSettlementCompleted

  • AcceptedCustomerProfile

  • AcceptedFundsChecked

  • AcceptedSettlementCompleted

  • AcceptedSettlementInProcess

  • AcceptedTechnicalValidation

  • AcceptedWithChange

  • AcceptedWithoutPosting

  • Cancelled

  • NoCancellationProcess

  • PartiallyAcceptedCancellationRequest

  • PartiallyAcceptedTechnicalCorrect

  • PaymentCancelled

  • Pending

  • PendingCancellationRequest

  • Received

  • Rejected

  • RejectedCancellationRequest

 

StatusUpdateDateTime

1..1


OBWritePaymentDetails/StatusUpdateDateTime

Date and time at which the status was assigned to the transfer.

DateTime

 

 

StatusDetail

0..1

OBWritePaymentDetails/StatusDetail

Payment status details as per underlying Payment Rail.

OBWritePaymentDetails/StatusDetail

 

 

LocalInstrument

0..1


OBWritePaymentDetails/StatusDetail/LocalInstrument

User community specific instrument.

Usage: This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level.

String

Enum:

  • BH.OBF. DNS 

  • BH.OBF. NRT

  • BH.OBF. BIL

 

Status

1..1

OBWritePaymentDetails/StatusDetail/Status

Status of a transfer, as assigned by the transaction administrator.

String

 

 

StatusReason

0..1

OBWritePaymentDetails/StatusDetail/StatusReason


Reason Code provided for the status of a transfer.

String

Enum:

  • Cancelled

  • PendingFailingSettlement

  • PendingSettlement

  • Proprietary

  • ProprietaryRejection

  • Suspended

  • Unmatched

 

StatusReasonDescription

0..1

OBWritePaymentDetails/StatusDetail/StatusReasonDescription

Reason provided for the status of a transfer.

String

 

 

 

4.1.7 OBSCASupportData

This section describes the OBSCASupportData class, which is used across all payment order consent request resources, enabling PISPs to provide Supporting Data when requesting ASPSP for SCA Exemption.

4.1.7.1  UML Diagram

...

4.1.7.2  Data Dictionary

Name

Occurrence

Xpath

Enhanced Definition

Class

Codes

Pattern

OBSCASupportData

 

SCASupportData

Supporting Data provided by TPP, when requesting SCA Exemption.

OBSCASupportData

 

 

RequestedSCAExemptionType

0..1

SCASupportData/RequestedSCAExemptionType

This field allows a PISP to request specific SCA Exemption for a Payment Initiation

String

Enum:

  • BillPayment

  • ContactlessTravel

  • EcommerceGoods

  • EcommerceServices

  • Kiosk

  • Parking

  • PartyToParty

 

AppliedAuthenticationApproach

0..1

SCASupportData/AppliedAuthenticationApproach

Specifies a character string with a maximum length of 40 characters.

Usage: This field indicates whether the PSU was subject to SCA performed by the TPP

String

Enum:

  • CA

  • SCA

 

ReferencePaymentOrderId

0..1

SCASupportData/ReferencePaymentOrderId

Specifies a character string with a maximum length of 140 characters.

Usage: If the payment is recurring, then the transaction identifier of the previous payment occurrence so that the ASPSP can verify that the PISP, amount and the payee are the same as the previous occurrence.

String

 

 

 

4.

...

Identifier Fields

This section describes the identifiers used through the Payment API flows, the direction of flow through the system, and how they are used.

...

Generated

Identifier

Business Description

Merchant/PISP Sent in API Payload

EndToEndIdentification

The 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

The PISP generates the InstructionIdentification which is a unique transaction Id and passes it to the ASPSP (this is mandatory), but this does not 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

RemittanceInformation

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

ASPSP / API System

ConsentId

A unique identification as assigned by the ASPSP to uniquely identify the payment-order consent resource.

ASPSP / API System

Payment Order Id

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

  • DomesticPaymentId

  • DomesticFutureDatedPaymentId

  • DomesticStandingOrderId

  • InternationalPaymentId

  • InternationalFutureDatedPaymentId

ASPSP / Payment Scheme

Scheme Payment ID

This is generated by the ASPSP to uniquely identify a payment through a processing scheme.

 

4.

...

Enumerations

4.3.1        Static 1 Static Enumerations

This section gives the definitions for enumerations used in the Payment APIs.

Code Class

Name

Definition

OBExternalPaymentContextCode

BillPayment

The context of the payment initiation is a bill payment.

OBExternalPaymentContextCode

EcommerceGoods

The context of the payment initiation is for goods via an ecommerce channel.

OBExternalPaymentContextCode

EcommerceServices

The context of the payment initiation is for services via an ecommerce channel.

OBExternalPaymentContextCode

PartyToParty

The context of the payment initiation is a party to party payment.

OBExternalPaymentContextCode

Other

The context of the payment initiation is of another type.

OBTransactionIndividualStatusCode

AcceptedSettlementCompleted

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.

OBTransactionIndividualStatusCode

AcceptedSettlementInProcess

All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

OBTransactionIndividualStatusCode

Pending

Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.

OBTransactionIndividualStatusCode

Rejected

Payment initiation or individual transaction included in the payment initiation has been rejected.

OBTransactionIndividualStatusCode

AcceptedWithoutPosting

Payment instruction included in the credit transfer is accepted without being posted to the creditor customer's account.

OBTransactionIndividualStatusCode

AcceptedCreditSettlementCompleted

Settlement on the creditor's account has been completed.

OBExternalConsentStatusCode

AwaitingAuthorisation

The consent resource is awaiting PSU authorisation.

OBExternalConsentStatusCode

Rejected

The consent resource has been rejected.

OBExternalConsentStatusCode

Authorised

The consent resource has been successfully authorised.

OBExternalConsentStatusCode

Consumed

The consented action has been successfully completed. This does not reflect the status of the consented action.

OBChargeBearerTypeCode

BorneByCreditor

All transaction charges are to be borne by the creditor.

OBChargeBearerTypeCode

BorneByDebtor

All transaction charges are to be borne by the debtor.

OBChargeBearerTypeCode

FollowingServiceLevel

Charges are to be applied following the rules agreed in the service level and/or scheme.

OBChargeBearerTypeCode

Shared

In 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.

OBExternalAuthorisationCode

Single

Single authorisation type is requested.

OBExternalStatusCode

InitiationCompleted

The payment-order initiation has been completed.

OBExternalStatusCode

InitiationFailed

The payment-order initiation has failed.

OBExternalStatusCode

InitiationPending

The payment-order initiation is pending.

OBExternalStatusCode

InitiationCompleted

The payment-order initiation has been completed.

OBExternalStatusCode

InitiationFailed

The payment-order initiation has failed.

OBExternalStatusCode

InitiationPending

The payment-order initiation is pending.

OBExternalStatusCode

Cancelled

Payment initiation has been successfully cancelled after having received a request for cancellation.

OBExchangeRateTypeCode

Actual

Exchange rate is the actual rate.

OBExchangeRateTypeCode

Agreed

Exchange rate is the agreed rate between the parties.

OBExchangeRateTypeCode

Indicative

Exchange rate is the indicative rate.

OBPriorityCode

Normal

Priority is normal.

OBPriorityCode

Urgent

Priority is urgent.

OBAddressTypeCode

Business

Address is the business address.

OBAddressTypeCode

Correspondence

Address is the address where correspondence is sent.

OBAddressTypeCode

DeliveryTo

Address is the address to which delivery is to take place.

OBAddressTypeCode

MailTo

Address is the address to which mail is sent.

OBAddressTypeCode

POBox

Address is a postal office (PO) box.

OBAddressTypeCode

Postal

Address is the complete postal address.

OBAddressTypeCode

Residential

Address is the home address.

OBAddressTypeCode

Statement

Address is the address where statements are sent.

OBTransactionIndividualExtendedISOStatusCode

Accepted

Request is accepted.

OBTransactionIndividualExtendedISOStatusCode

AcceptedCancellationRequest

Cancellation is accepted.

OBTransactionIndividualExtendedISOStatusCode

AcceptedCreditSettlementCompleted

Settlement on the creditor's account has been completed.

OBTransactionIndividualExtendedISOStatusCode

AcceptedCustomerProfile

Preceding check of technical validation was successful. Customer profile check was also successful.

OBTransactionIndividualExtendedISOStatusCode

AcceptedFundsChecked

Preceding check of technical validation and customer profile was successful and an automatic funds check was positive.

OBTransactionIndividualExtendedISOStatusCode

AcceptedSettlementCompleted

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

OBTransactionIndividualExtendedISOStatusCode

AcceptedSettlementInProcess

All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.

OBTransactionIndividualExtendedISOStatusCode

AcceptedTechnicalValidation

Authentication and syntactical and semantical validation are successful

OBTransactionIndividualExtendedISOStatusCode

AcceptedWithChange

Instruction is accepted but a change will be made, such as date or remittance not sent.

OBTransactionIndividualExtendedISOStatusCode

AcceptedWithoutPosting

Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account.

OBTransactionIndividualExtendedISOStatusCode

Cancelled

Request is cancelled.

OBTransactionIndividualExtendedISOStatusCode

NoCancellationProcess

No cancellation process.

OBTransactionIndividualExtendedISOStatusCode

PartiallyAcceptedCancellationRequest

Cancellation is partially accepted.

OBTransactionIndividualExtendedISOStatusCode

PartiallyAcceptedTechnicalCorrect

Authentication and syntactical and semantical validation are successful.

OBTransactionIndividualExtendedISOStatusCode

PaymentCancelled

Transaction has been cancelled.

OBTransactionIndividualExtendedISOStatusCode

Pending

Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed.

OBTransactionIndividualExtendedISOStatusCode

PendingCancellationRequest

Cancellation request is pending.

OBTransactionIndividualExtendedISOStatusCode

Received

Payment initiation has been received by the receiving agent.

OBTransactionIndividualExtendedISOStatusCode

Rejected

Payment initiation or individual transaction included in the payment initiation has been rejected.

OBTransactionIndividualExtendedISOStatusCode

RejectedCancellationRequest

Cancellation request is rejected

OBTransactionIndividualStatusReasonCode

Cancelled

Reason why the payment status is cancelled

OBTransactionIndividualStatusReasonCode

PendingFailingSettlement

Reason why the payment status is pending (failing settlement).

OBTransactionIndividualStatusReasonCode

PendingSettlement

Reason why the payment status is pending (settlement).

OBTransactionIndividualStatusReasonCode

Proprietary

Defines a free text proprietary reason.

OBTransactionIndividualStatusReasonCode

ProprietaryRejection

Defines the reason that has been used by the Local Instrument system to reject the transaction

OBTransactionIndividualStatusReasonCode

Suspended

Reason why the payment status is suspended.

OBTransactionIndividualStatusReasonCode

Unmatched

Reason why the payment status is unmatched.

OBExternalSCAExemptionTypeCode

BillPayment

Bill Payment

OBExternalSCAExemptionTypeCode

ContactlessTravel

Contactless Travel

OBExternalSCAExemptionTypeCode

EcommerceGoods

Ecommerce Goods

OBExternalSCAExemptionTypeCode

EcommerceServices

Ecommerce Services

OBExternalSCAExemptionTypeCode

Kiosk

Kisok

OBExternalSCAExemptionTypeCode

Parking

Parking

OBExternalSCAExemptionTypeCode

PartyToParty

Party To Party

OBExternalAppliedAuthenticationApproachCode

CA

Single Factor Strong Customer Authentication

OBExternalAppliedAuthenticationApproachCode

SCA

Multi Factor Strong Customer Authentication

OBReadRefundAccountCode

Yes

Yes

OBReadRefundAccountCode

No

No

4.3.2        ISO 2 ISO Enumerations

These following ISO Enumerations are used in the Payment APIs.

ISO Data Type

Fields

ISO Enumeration Values URL

String

MerchantCategoryCode

https://www.iso.org/standard/33365.html

String

Currency

https://www.iso20022.org/external_code_list.page

String

Country

https://www.iso.org/iso-3166-country-codes.html

5.        Alternative and Error Flows

5.

...

Idempotent Payment Order Consent

Note: This flow has been generalised for all payment-order types.

...

5.

...

Idempotent Payment Order

Note: This flow has been generalised for all payment-order types.

...

5.

...

Reject the Payment Order Consent Creation after CutOffDateTime

This example illustrates a scenario where an ASPSP choses to Reject the Payment-Order consent/resource request, after the CutoffTime. We have a payment-order consent created after the CutOffDateTime, and ASPSP rejects the Consent, and the PISP chooses to place a Future Dated Payment-Order consent.

...

5.

...

Reject the Payment Order Creation after CutOffDateTime

This example illustrates a scenario where an ASPSP choses to Reject the Payment-Order consent/resource request, after the CutoffTime. We have a payment-order Consent created and the Authorisation completed before the CutOffDateTime, but the Payment-Order submission happened after the CutOffDateTime, so the ASPSP has rejected it.

...