| Table of Contents | ||||
|---|---|---|---|---|
|
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:
Register an intent to stage a payment-order consents.
Optionally confirm available funds for a payment-order for Domestic and International payments.
Subsequently submit the payment-order for processing.
Optionally retrieve the status of a payment-order consents or payment-order resource.
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:
Overview: Provides an overview of the profile.
Basics: Identifies the flows, restrictions etc.
Security & Access Control: Specifies the means for PISPs and users/customers to authenticate themselves and provide consents.
Data Model: Documents mappings and enumerations that apply to all the end-points.
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.3 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 consents reflects the status of the user/customer consents authorisation.
The Status field for the payment-order resource reflects the status of the payment-order initiation or execution.
2. Basics
2.1 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:
Single Domestic Payment.
Single Future Dated Domestic Payment.
Single International payment.
Bulk/Batch Payment.
The payment-order consents and payment-order resource in the following flow generalises for the different payment-order types. E.g. for a domestic payment, the payment-order consents resource is domestic-payment-consents; and the payment-order resource is domestic-payments.
...
2.1.1 Steps
Step 1: Agree Payment-Order Initiation
This flow begins with a user/customer consenting to a payment being made. The consents is between the user/customer and the PISP.
The debtor account details can optionally be specified at this stage.
Step 2: Setup Payment-Order Consents
The PISP connects to the ASPSP that services the user’s/customer’s payment account and creates a new payment-order consents resource. This informs the ASPSP that one of its users/customers intends to make a payment-order. The ASPSP responds with an identifier for the payment-order consents resource (the ConsentId, which is the intent identifier).
This step is carried out by making a POST request to the payment-order consents resource.
Step 3: Authorise Consents
The PISP requests the user/customer to authorise the consents. The ASPSP may carry this out by using a redirection flow or a decoupled flow.
In a redirection flow, the PISP redirects the user/customer to the ASPSP .
The redirect includes the ConsentId generated in the previous step.
This allows the ASPSP to correlate the payment order consents that was setup.
The ASPSP authenticates the user/customer.
The user/customer selects the debtor account at this stage (if it has not been previously specified in Step 1).
The ASPSP updates the state of the payment order consents resource internally to indicate that the consents has been authorised.
Once the consents has been authorised, the user/customer is redirected back to the PISP.
In a decoupled flow, the ASPSP requests the user/customer to authorise consents on an authentication device that is separate from the consumption device on which the user/customer is interacting with the PISP.
The decoupled flow is initiated by the PISP calling a back-channel authorisation request.
The request contains a 'hint' that identifies the user/customer paired with the consents to be authorised.
The ASPSP authenticates the user/customer.
The user/customer selects the debtor account at this stage (if it has not been previously specified in Step 1).
The ASPSP updates the state of the payment order consents resource internally to indicate that the consents has been authorised.
Once the consents has been authorised, the ASPSP can make a callback to the PISP to provide an access token.
Step 4: Confirm Funds (Domestic and International Single Immediate Payments Only)
Once the user/customer is authenticated and authorised the payment-order-consents, the PISP can check whether funds are available to make the payment.
This is carried out by making a GET request, calling the funds-confirmation operator on the payment-order-consents resource.
Step 5: Create Payment-Order
The PISP creates a payment-order resource to indicate that the payment created in the steps above should be submitted for processing.
This is carried out by making a POST request to the appropriate payment-order resource.
The ASPSP returns the identifier for the payment-order resource to the PISP.
Step 6: Get Consents/Payment-Order/Payment-Details Status
The PISP can check the status of the payment-order consents (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 consents or payment-order or payment-details resource.
2.1.2 Sequence Diagram
...
2.2 Payment Restrictions
The standard does not provide a uniform set of restrictions for payment-order types that can be supported through this API.
For example, but not limited to:
The maximum InstructedAmount allowable.
The domestic-standing-order Frequency patterns supported.
The maximum future date on a future dated payment.
Each ASPSP must determine appropriate restrictions that they support based on their individual practices, standards and limitations. These restrictions should be documented on ASPSP developer portals.
An ASPSP must reject the payment-order consents 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 consents request.
An ASPSP must document the behaviour for a payment receipt before and after the CutOffDateTime for a payment-order has elapsed.
Two strategies for handling behaviour are:
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 user/customer.
An ASPSP must reject the payment-order consents if the CutOffDateTime for a specific payment-order type has elapsed.
An ASPSP must reject an authorisation request when the underlying intent object is associated with a CutoffDateTime that has elapsed. The ASPSP must not issue an access token in such a situation. The ASPSP must set the status of the payment-order consents resource to “Rejected”.
An ASPSP must reject the payment-order resource if the CutOffDateTime for a specific payment-order type, has been established and has elapsed.
A PISP must ensure that the user/customer consents authorisation is completed and the payment-order resource is created before the CutOffDateTime elapses.
For a payment-order consents 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 consents. The PISP may use the /domestic-future-dated-payment-consents endpoint to create a consents 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 user/customer, and the payment-order will be executed on the next available working day.
An ASPSP must accept the payment-order consents 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 consents or payment-order resource with the CutOffDateTime, ExpectedExecutionDateTime and ExpectedSettlementDateTime, to communicate expected execution behaviour if the CutOffDateTime has elapsed
2.3 Release Management
This section overviews the release management and versioning strategy for the Payment Initiation API. It applies to all Payment Order Consents and Payment Order resources, specified in the Endpoints section.
2.3.1 Payment-Order Consents
2.3.1.1 POST
A PISP must not create a payment-order consents 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 consents 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 consents.
2.3.2 Payment-Order Consents (Confirm Funds)
2.3.2.1 GET
A PISP must not confirm funds using a payment-order-consents 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 consents ConsentId within the same version to create the payment-order resource (in that version).
E.g., A v3 payment-order consents 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 ASPSP 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 consents endpoints. In the specification, this grant type is referred to as "Client Credentials".
PISPs must use an authorisation code grant using a redirect or decoupled flow to obtain a token to make POST requests to the payment-order resource endpoints. This token may also be used to confirm funds on a payment-order consents resource. In the specification, this grant type is referred to as "Authorisation Code".
PISPs must use a client credentials grant to obtain a token to make GET requests (excluding confirming funds).
3.3 Consents 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.
A consents authorisation is used to define the fine-grained scope that is granted by the user/customer to the PISP.
The PISP must begin a payment-order request by creating a payment-order consents resource through a POST operation. These resources indicate the consents that the PISP claims it has been given by the user/customer. At this stage, the consents is not yet authorised as the ASPSP has not yet verified this claim with the user/customer.
The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorisation code grant.
As part of the authorisation code grant:
The ASPSP authenticates the user/customer.
The ASPSP plays back the consents (registered by the PISP) back to the user/customer to get consents authorisation. The user/customer may accept or reject the consents in its entirety (but not selectively).
If the consents did not indicate a debtor account the ASPSP presents the user/customer with a list of accounts from which the user/customer may select one.
Once these steps are complete, the consents is considered to have been authorised by the user/customer.
3.3.1 Error Condition
If the user/customer does not complete a successful consents authorisation (e.g., if the user/customer has not authenticated successfully), the authorisation code grant ends with a redirection to the PISP with an error response. The user/customer is redirected to the PISP with an error parameter indicating the error that occurred.
3.3.2 Consents Revocation
A user/customer cannot revoke a payment-order consents once it has been authorised.
3.3.3 Changes to Selected Account
For a payment-order consents, the selected debtor account cannot be changed once the consents has been authorised.
3.3.4 Consents Re-Authentication
Payment consents are short-lived and cannot be re-authenticated by the user/customer.
3.4 Risk Scoring Information
Note: This section currently considers indicative data fields required for banks to do Transactional risk analysis where needed.
Information for risk scoring and assessment will come via:
FAPI HTTP headers.
Additional fields identified by the industry as business logic security concerns which will be passed in the Risk section of the payload in the JSON object.
These are the set of additional fields in the risk section of the payload which will be specified by the PISP:
PaymentContextCode.
MerchantCategoryCode.
MerchantCustomerIdentification.
DeliveryAddress.
The PaymentContextCode describes the payment context and can have these values:
BillPayment.
EcommerceGoods.
EcommerceServices.
Other.
PartyToParty.
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.1 Reused Classes
4.1.1 OBRisk
This section describes the OBRisk class which is reused in the payment-order consents 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.
...
String
...
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 user/customer 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
...
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
...
String
...
...
...
Country
...
0..1
...
String
...
...
4.1.2 OBCharge
This section describes the OBCharge class - which is reused in the response payloads in the payment-order consents 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:
|
|
Type | 1..1 | OBCharge/Type | Charge type, in a coded form. | String | Enum:
|
|
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 consents request and payment-order consents 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 PISP. | OBAuthorisation |
|
|
AuthorisationType | 1..1 | OBAuthorisation/AuthorisationType | Type of authorisation flow requested. | String | Enum:
|
|
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 and Domestic Future Dated Payment.
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:
|
|
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. | String |
|
|
4.1.5 OBInternationalRefundAccount
This section describes the OBInternationalRefundAccount class which is used in the response payloads of International Payment.
4.1.5.1 UML Diagram
...
...
| Table of Contents | ||||
|---|---|---|---|---|
|
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 25th Aug 2020 | Initial Release |
2. Overview
The Payment Initiation API Profile describes the flows and common functionalities for the Payment Initiation API, which allows a Payment Initiation Service Provider ('PISP') to:
Register an intent to stage a payment-order consent
Optionally confirm available funds for a payment-order for Domestic payments and international immediate payments only
Subsequently submit the payment-order for processing
Retrieve the status of a payment-order consent or payment-order resource
2.1 Chapter Overview
This chapter (Payment Initiation Services) consists of the following parts:
Overview: Provides an overview of the profile
Basics: Identifies the flows, restrictions, etc.
Security & Access Control: Specifies the means for PISPs and users/customers to authenticate themselves and provide consent
Data Model: Mappings and enumerations that apply to all the end-points
Alternative Flows: Rules for alternative flows
2.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)
Usage Examples
2.3 Design Principles
2.3.1 Status Codes
The API uses three status codes that serve three 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 user/customer consent authorisation
The status field for the payment-order resource reflects the status of the payment-order initiation or execution
3. Basics
3.1 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:
Single Domestic Payment
Single Future Dated Domestic Payment
Single International Payment
Bulk/Batch Payment
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.
...
3.1.1 Steps
Step 1: Agree Payment-Order Initiation
This flow begins with a user/customer consenting to a payment being made. The consent is between the user/customer and the PISP
The debtor account details can optionally be specified at this stage
Step 2: Setup Payment-Order Consent
The PISP connects to the ASPSP that services the user’s/customer's payment account and creates a new payment-order consent resource. This informs the ASPSP that one of its users/customers intends to make a payment-order. The ASPSP responds with an identifier for the payment-order consent resource (the ConsentId, which is the intent identifier)
This step is carried out by making a POST request to the payment-order consent resource
Step 3: Authorise Consent
The PISP requests the user/customer to authorise the consent. The ASPSP may carry this out by using a redirection flow or a decoupled flow
In a redirection flow, the PISP redirects the user/customer to the ASPSP
The redirect includes the ConsentId generated in the previous step
This allows the ASPSP to correlate the payment-order consent that was setup
The ASPSP authenticates the user/customer
The user/customer selects the debtor account at this stage (if it has not been previously specified in Step 1)
The ASPSP updates the state of the payment-order consent resource internally to indicate that the consent has been authorised
Once the consent has been authorised, the user/customer is redirected back to the PISP
In a decoupled flow, the ASPSP requests the user/customer to authorise consent on an authentication device that is separate from the consumption device on which the user/customer is interacting with the PISP
The decoupled flow is initiated by the PISP calling a back-channel authorisation request
The request contains a 'hint' that identifies the user/customer paired with the consent to be authorised
The ASPSP authenticates the user/customer
The user/customer selects the debtor account at this stage (if it has not been previously specified in Step 1)
The ASPSP updates the state of the payment-order consent resource internally to indicate that the consent has been authorised
Once the consent has been authorised, the ASPSP can make a callback to the PISP to provide an access token
Step 4: Confirm Funds (Domestic and international immediate Payments Only)
Once the user/customer is authenticated and has authorised the payment-order consent, the PISP can check whether funds are available to make the payment
This is carried out by making a GET request, calling the funds-confirmation operator on the payment-order consent resource
Step 5: Create Payment-Order
The PISP creates a payment-order resource to indicate that the payment created in the steps above should be submitted for processing
This is carried out by making a POST request to the appropriate payment-order resource
The ASPSP returns the identifier for the payment-order resource to the PISP
Step 6: Get Consent/Payment-Order/Payment-Details Status
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
3.1.2 Sequence Diagram
...
* CIBA- Client Initiated Backchannel Authentication
3.2 Payment Restrictions
The standard does not provide a uniform set of restrictions for payment-order types that can be supported through this API.
For example, but not limited to:
The maximum InstructedAmount allowable
The maximum future date on a Future Dated Payment
Each ASPSP must determine appropriate restrictions that they support based on their individual practices, standards and limitations. These restrictions should be documented on ASPSP developer portals.
An ASPSP must reject the payment-order consent if the ASPSP is unable to handle the request.
3.2.1 CutOffDateTime Behaviour
An ASPSP may return the specific CutOffDateTime when responding to a payment-order consent request.
An ASPSP must document the behaviour for a payment receipt before and after the CutOffDateTime for a payment-order that has elapsed.
Two strategies for handling behaviour are:
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
3.2.1.1 Reject the Payment-Order
In this scenario, the behaviour of payment-order execution is explicit to the PISP and user/customer.
An ASPSP must reject the payment-order consent if the CutOffDateTime for a specific payment-order type has elapsed
An ASPSP must reject an authorisation request when the underlying intent object is associated with a CutoffDateTime that has elapsed. The ASPSP must not issue an access token in such a situation. The ASPSP must set the status of the payment-order consent resource to “Rejected”
An ASPSP must reject the payment-order resource if the CutOffDateTime for a specific payment-order type, has been established and has elapsed
A PISP must ensure that the user/customer consent authorisation is completed and the payment-order resource is created before the CutOffDateTime elapses
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.
3.2.1.2 Accept the Payment-Order
In this scenario, the behaviour of the payment-order execution is not explicit to the PISP and user/customer, 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
3.3 Release Management
This section coverss 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.
3.3.1 Payment-Order Consents
3.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
3.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
3.3.2 Payment-Order Consents (Confirm Funds)
3.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
3.3.3 Payment-Order Resource
3.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
3.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., a domestic-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)
4. Security & Access Control
4.1 Scopes
The access tokens required for accessing the Payment APIs must have the following scope:
Payments: Generic payment scope
4.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 an authorisation code grant using a redirect or decoupled flow to obtain a token to make POST requests to the payment-order resource endpoints. This token may also be used to confirm funds on a payment-order consent resource. In the specification, this grant type is referred to as "Authorisation Code".
PISPs must use a client credentials grant to obtain a token to make GET requests (excluding confirming funds).
4.3 Consents 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.
A consent authorisation is used to define the fine-grained scope that is granted by the user/customer to the PISP.
The PISP must begin a payment-order request by creating a payment-order consent resource through a POST operation. These resources indicate the consent that the PISP claims it has been given by the user/customer. At this stage, the consent is not yet authorised as the ASPSP has not yet verified this claim with the user/customer.
The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorisation code grant.
As part of the authorisation code grant:
The ASPSP authenticates the user/customer
If the consent did not indicate a debtor account the ASPSP presents the user/customer with a list of accounts from which the user/customer may select one
The ASPSP plays back the consent (registered by the PISP) back to the user/customer to get consent authorisation. The user/customer may accept or reject the consent in its entirety (but not selectively)
Once these steps are complete, the consent is considered to have been authorised by the user/customer.
4.3.1 Error Condition
If the user/customer does not complete a successful consent authorisation (e.g., if the user/customer has not authenticated successfully), the authorisation code grant ends with a redirection to the PISP with an error response. The user/customer is redirected to the PISP with an error parameter indicating the error that occurred.
4.3.2 Consents Revocation
A user/customer cannot revoke a payment-order consent once it has been authorised.
4.3.3 Changes to Selected Account
For a payment-order consent, the selected debtor account cannot be changed once the consent has been authorised.
4.3.4 Consents Re-Authentication
Payment consents are short-lived and cannot be re-authenticated by the user/customer.
4.4 Risk Scoring Information
Note: This section currently considers indicative data fields required for banks to do transactional risk analysis where needed.
Information for risk scoring and assessment will come via:
FAPI HTTP headers (Please refer Security Standards and Guidelines for further information)
Additional fields identified by the industry as business logic security concerns which will be passed in the Risk section of the payload in the JSON object
These are the set of additional fields in the risk section of the payload which will be specified by the PISP:
PaymentContextCode
MerchantCategoryCode
MerchantCustomerIdentification
DeliveryAddress
The PaymentContextCode describes the payment context and can have these values:
BillPayment
EcommerceGoods
EcommerceServices
Other
PartyToParty
Payments for EcommerceGoods and EcommerceServices will be expected to have a MerchantCategoryCode and MerchantCustomerIdentification populated. Payments for EcommerceGoods will also have the DeliveryAddress populated.
5. Data Model
5.1 Reused Classes
5.1.1 OBRisk
This section describes the OBRisk class which is reused in the payment-order consent and payment-order resources.
5.1.1.1 UML Diagram
...
5.1.1.2 Data Dictionary
Name | Occurrence | Xpath | Enhanced Definition | Class | Codes | Pattern | |||||||||
OBInternationalRefundAccountOBRisk |
| 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/CreditorOBRisk | 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 |
|
|
NamePaymentContextCode | 0..1 | OBInternationalRefundAccountOBRisk/Creditor/NameName by which a party is known and which is usually used to identify that party.PaymentContextCode | Specifies the payment context | String | Enum: OBPostalAddress
| PostalAddress | 0..1 | OBInternationalRefundAccount/Creditor/PostalAddress | Information that locates and identifies a specific address, as defined by postal services. |
|
|
| |||
AddressTypeMerchantCategoryCode | 0..1 | OBInternationalRefundAccount/Creditor/PostalAddress/AddressType | Identifies the nature of the postal address. | String | Enum:
|
| DepartmentOBRisk/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 | OBInternationalRefundAccount/Creditor/PostalAddress/Department | Identification of a division of a large organisation or building. | OBRisk/MerchantCustomerIdentification | The unique customer identifier of the user/customer with the merchant | String |
|
| |||||||
SubDepartmentDeliveryAddress | 0..1 | OBInternationalRefundAccount/Creditor/PostalAddress/SubDepartment | Identification of a sub-division of a large organisation or building. | StringOBRisk/DeliveryAddress | Information that locates and identifies a specific address, as defined by postal services or in free format text | OBRisk/DeliveryAddress |
|
| |||||||
AddressLine | 0..7 | OBInternationalRefundAccountOBRisk/CreditorDeliveryAddress/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/CreditorOBRisk/PostalAddressDeliveryAddress/StreetName | Name of a street or thoroughfare. | String |
|
| |||||||||
BuildingNumber | 0..1 | OBInternationalPaymentInitiationOBRisk/Creditor/PostalAddressDeliveryAddress/BuildingNumber |
| String |
|
| |||||||||
PostCode | 0..1 | OBInternationalPaymentInitiationOBRisk/Creditor/PostalAddressDeliveryAddress/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 | OBInternationalPaymentInitiationOBRisk/Creditor/PostalAddressDeliveryAddress/TownName | Name of a built-up area, with defined boundaries, and a local government. | String |
|
| |||||||||
CountrySubDivision | 0..1 | OBInternationalPaymentInitiationOBRisk/Creditor/PostalAddressDeliveryAddress/CountrySubDivision |
| String |
|
| |||||||||
Country | 0..1 |
|
| String |
|
| |||||||||
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:
|
| |||||||||
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:
|
| |||||||||
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}$
5.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.
5.1.2.1 UML Diagram
...
5.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:
|
|
Type | 1..1 | OBCharge/Type | Charge type, in a coded form | String | Enum:
|
|
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,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}$ |
5.1.3 OBAuthorisation
This section describes the OBAuthorisation class which is used in the payment-order consent request and payment-order consent response payloads.
5.1.3.1 UML Diagram
...
5.1.3.2 Data Dictionary
Name | Occurrence | Xpath | Enhanced Definition | Class | Codes | Pattern |
OBAuthorisation |
| OBAuthorisation | The authorisation type request from the PISP | OBAuthorisation |
|
|
AuthorisationType | 1..1 | OBAuthorisation/AuthorisationType | Type of authorisation flow requested | String | Enum:
|
|
CompletionDateTime | 0..1 | OBAuthorisation/CompletionDateTime | Date and time at which the requested authorisation flow must be completed | DateTime |
|
|
5.1.4 OBDomesticRefundAccount
This section describes the OBDomesticRefundAccount class which is used in the response payloads of Single Domestic Payment and Single Future Dated Domestic Payment.
5.1.4.1 UML Diagram
...
5.1.4.2 Data Dictionary
Name | Occurrence | Xpath | Enhanced Definition | Class | Codes | Pattern | |
OBDomesticRefundAccount | 1..1 | OBDomesticRefundAccount | Unambiguous identification of the refund account to which a refund will be made as a result of the transaction | OBDomesticRefundAccount |
|
| |
Account | 1..1 | OBInternationalRefundAccountOBDomesticRefundAccount/Account | Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. | OBInternationalRefundAccountProvides the details to identify an account | OBDomesticRefundAccount/Account |
|
|
SchemeName | 1..1 | OBInternationalRefundAccountOBDomesticRefundAccount/Account/SchemeName | Name of the identification scheme, in a coded form as published in an external list.Name of the identification scheme, in a coded form as published in an external list | String | EnumEnum:
|
| |
Identification | 1..1 | OBInternationalRefundAccount/Account/Identification | Identification assigned by an institution to identify an account. This identification is known by the account owner.OBDomesticRefundAccount/Account/Identification | Identification assigned by an institution to identify an account. This identification is known by the account owner | String |
|
|
Name | 10..1 | OBInternationalRefundAccountOBDomesticRefundAccount/Account/Name | The account name is the name or names of the account ownerName 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. Note, the account name is not the product name or the nickname of the account. represented at an account level. The account name is not the product name or the nickname of the account | String |
|
|
...
5.1.
...
5 OBWritePaymentDetails
This section describes the OBWritePaymentDetails class which used in the response payloads of payment-detail sub resources.
...
5.1.
...
5.1 UML Diagram
...
...
5.1.
...
5.2 Data Dictionary
Name | Occurrence | Xpath | Enhanced Definition | Class | Codes | Pattern |
OBWritePaymentDetails | 1..1 | OBWritePaymentDetails | Payment status details. | OBWritePaymentDetails |
|
|
PaymentTransactionId | 1..1 | OBWritePaymentDetails/PaymentTransactionId | Unique identifier for the transaction within an a 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:
|
|
StatusUpdateDateTime | 1..1 |
| 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 | 1..1 |
| 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:
|
|
Status | 1..1 | OBWritePaymentDetails/StatusDetail/Status | Status of a transfer, as assigned by the transaction administrator. | String |
|
|
StatusReason | 0..1 | OBWritePaymentDetails/StatusDetail/StatusReason |
| String | Enum:
|
|
StatusReasonDescription | 0..1 | OBWritePaymentDetails/StatusDetail/StatusReasonDescription | Reason provided for the status of a transfer. | String |
|
|
...
5.1.
...
6 OBSCASupportData
This section describes the OBSCASupportData class, which is used across all payment-order consents consent request resources, enabling PISPs to provide Supporting Data when requesting ASPSP for SCA Exemption.
...
5.1.
...
6.1 UML Diagram
...
...
5.1.
...
6.2 Data Dictionary
Name | Occurrence | Xpath | Enhanced Definition | Class | Codes | Pattern |
OBSCASupportData |
| SCASupportData | Supporting Data provided by PISP, 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
|
|
AppliedAuthenticationApproach | 0..1 | SCASupportData/AppliedAuthenticationApproach | Specifies a character string with a maximum length of 40 characters. Usage: This field indicates whether the user/customer was subject to SCA performed by the PISP. | String | Enum:
|
|
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 |
|
|
...
5.2 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.
The standard definitions for the elements in the API payloads are described in the Data Payload section. However, this table gives further detail on the business meaning, 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 consents consent resource. |
ASPSP / API System | Payment Order Id | A unique identification as assigned by the ASPSP to uniquely identify the payment-order resource.
|
ASPSP / Payment Scheme | Scheme Payment ID | This is generated by the ASPSP to uniquely identify a payment through a processing scheme. |
...
5.3 Enumerations
...
5.3.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 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 consents consent resource is awaiting user/customer authorisation. | |||
OBExternalConsentStatusCode | Rejected | The consents consent resource has been rejected. | |||
OBExternalConsentStatusCode | Authorised | The consents 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. |
OBAddressTypeCodeMailTo | 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.address |
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. | |||
OBTransactionIndividualStatusReasonCode | Suspended | Reason why the payment status is suspended | |||
OBTransactionIndividualStatusReasonCode | Unmatched | Reason why the payment status is unmatched | |||
OBExternalAppliedAuthenticationApproachCode | CA | Single Factor Strong Customer Authentication. | |||
OBExternalAppliedAuthenticationApproachCode | SCA | Multi Factor Strong Customer Authentication. | |||
OBReadRefundAccountCode | Yes | Yes. | |||
OBReadRefundAccountCode | No | No. |
...
5.3.2 ISO Enumerations
These following ISO Enumerations are used in the Payment APIs.
ISO Data Type | Fields | ISO Enumeration Values URL |
String | MerchantCategoryCode | |
String | Currency | https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets |
String | Country |
4.3.3 Namespaced Enumerations
The enumerated values specified by Open Banking are documented in Swagger specification.
...
6. Alternative and Error Flows
...
6.1 Idempotent Payment-Order Consents
Note: This flow has been generalised for all payment-order types.
...
...
6.2 Idempotent Payment-Order
Note: This flow has been generalised for all payment-order types.
...
...
6.3 Reject the Payment-Order Consents Creation after CutOffDateTime
This example illustrates a scenario where an ASPSP choses to Reject the Payment-Order consentsconsent/resource request, after the CutoffTime. We have a payment-order consents consent created after the CutOffDateTime, and ASPSP rejects the ConsentsConsent, and the PISP chooses to place a Future Dated Payment-Order consentsconsent.
...
...
6.4 Reject the Payment-Order Creation after CutOffDateTime
This example illustrates a scenario where an ASPSP choses to Reject the Payment-Order consentsconsent/resource request, after the CutoffTime. We have a payment-order Consents Consent created and the Authorisation completed before the CutOffDateTime, but the Payment-Order submission happened after the CutOffDateTime, so the ASPSP has rejected it.
...
...
7. Swagger Code
The swagger code file for the Payment Initiation APIs can be accessed at this link.
CENTRAL BANK OF BAHRAIN © 2020