Table of Contents | ||
---|---|---|
|
...
Version | Date | Author | Comments |
---|---|---|---|
3.0 | OB R/W API Team | This is the baseline version. No change from RC3. Swagger URLs have been updated to point to the latest stable version. | |
3.1-draft1 | OB R/W API Team | This is the initial draft version for 3.1. Errata
| |
3.1-draft2 | OB R/W API Team | Draft2 Changes:
| |
3.1-draft3 | OB R/W API Team | Draft3 Changes:
Errata
| |
3.1-draft4 | OB R/W API Team | Draft4 Changes:
| |
3.1-rc1 | OB R/W API Team | RC1 Changes:
| |
3.1 | OB R/W API Team | Version 3.1 final release. No changes from Version 3.1 RC1. Updated swagger links to latest release candidate. |
Overview
This Payment Initiation API Specification describes the flows and payloads for initiating a general payment-order.
...
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.
Steps
Step 1: Agree Payment-Order Initiation
- This flow begins with a PSU consenting to a payment being made. The consent is between the PSU 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 PSU's payment account and creates a new payment-order consent resource. This informs the ASPSP that one of its PSUs 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 PSU 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 PSU 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 PSU.
- The PSU 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 PSU is redirected back to the PISP.
- In a decoupled flow, the ASPSP requests the PSU to authorise consent on an authentication device that is separate from the consumption device on which the PSU 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 PSU paired with the consent to be authorised.
- The ASPSP authenticates the PSU
- The PSU 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.
- In a redirection flow, the PISP redirects the PSU to the ASPSP.
Step 4: Confirm Funds (Domestic and International Single Immediate Payments Only)
- Once the PSU is authenticated and 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 Payment-Order/Consent 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).
- This is carried out by making a GET request to the payment-order consent or payment-order resource.
Sequence Diagram
Code Block | ||||
---|---|---|---|---|
| ||||
participant PSU participant PISP participant ASPSP Authorisation Server participant ASPSP Resource Server note over PSU, ASPSP Resource Server Step 1: Agree Payment-Order Initiation end note PSU -> PISP: Agree payment-order initiation request note over PSU, ASPSP Resource Server Setup Payment-Order Consent end note PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server -> PISP: access-token PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: POST /payment-order-consents state over ASPSP Resource Server: Consent Status: AwaitingAuthorisation ASPSP Resource Server -> PISP: HTTP 201 (Created), ConsentId note over PSU, ASPSP Resource Server Step 3: Authorize Consent end note alt Redirection (Using authorization code grant) PISP -> PSU: HTTP 302 (Found), Redirect (ConsentId) PSU -> ASPSP Authorisation Server: Follow redirect (ConsentId) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: Select debtor account if required state over ASPSP Resource Server: Consent Status: Authorised ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (authorization-code) PSU -> PISP: Follow redirect (authorization-code) PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> PISP: access-token else Decoupled (Using CIBA) PISP -> ASPSP Authorisation Server: POST /bc-authorize (login_hint_token) ASPSP Authorisation Server -> PISP: OK PSU -> ASPSP Authorisation Server: Authorise (Consent Id) PSU <-> ASPSP Authorisation Server: authenticate PSU <-> ASPSP Authorisation Server: SCA if required PSU <-> ASPSP Authorisation Server: select accounts state over ASPSP Resource Server: Consent Status: Authorised alt Using callback ASPSP Authorisation Server -> PISP: Callback (authorization-code) PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Exchange authorization-code for access token ASPSP Authorisation Server -> PISP: access-token else Using polling PISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA PISP -> ASPSP Authorisation Server: Poll at /token using auth-req-id ASPSP Authorisation Server -> PISP: access-token end alt end alt note over PSU, ASPSP Resource Server Step 4: Confirm Funds (Domestic and International Single Immediate Payments Only) end note opt PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: GET /payment-order-consents/{ConsentId}/funds-confirmation ASPSP Resource Server -> PISP: HTTP 200 (OK) funds-confirmation resource end opt note over PSU, ASPSP Resource Server Step 5: Create Payment-Order end note PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: POST /payment-orders state over ASPSP Resource Server: Consent Status: Consumed alt Immediate Payment state over ASPSP Resource Server: Payment Status: Pending state over ASPSP Resource Server: Payment Status: AcceptedSettlementInProcess state over ASPSP Resource Server: Payment Status: AcceptedSettlementComplete else Standing Order or Future Dated Payment state over ASPSP Resource Server: Payment Status: InitiationPending state over ASPSP Resource Server: Payment Status: InitiationCompleted end alt ASPSP Resource Server -> PISP: HTTP 201 (Created), Payment-Order Id note over PSU, ASPSP Resource Server Step 6: Get Payment-Order/Consent Status end note opt payment-order-consent PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: GET /payment-order-consents/{ConsentId} ASPSP Resource Server -> PISP: HTTP 200 (OK) payment-order-consent resource end opt opt payment-order PISP <-> ASPSP Resource Server: Establish TLS 1.2 MA PISP -> ASPSP Resource Server: GET /payment-orders/{Payment-Order Id} ASPSP Resource Server -> PISP: HTTP 200 (OK) payment-order resource end opt option footer=bar |
...
- 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
...
- A PISP must refer to the ASPSP's online Developer Portal for guidelines on accessibility of a payment-order resource in a newer version
- A PISP must not access the payment-order resource types introduced in a newer version, on an older version endpoint:
- E.g., an international-payment created in v3, that is accessed via the v1 payment-submissions endpoint.
- A PISP must not access the payment-order resource created in a newer version on an older version endpoint:
- E.g., for a domestic-payment resource created in v3, access via the v1 payment-submissions endpoint is not permitted.
- An ASPSP must document the behaviour on the accessibility of a payment-order resource in a newer version on 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).
...
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 authorization 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 "Authorization Code".
...
The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).
...
The Swagger Specification for Payment Initiation APIs can be downloaded from the following links:
Data Model
Reused Classes
OBRisk1
...
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 | Anique identification as assigned by the ASPSP to uniquely identify the payment-order resource. DomesticPaymentId DomesticScheduledPaymentId DomesticStandingOrderId InternationalPaymentId InternationalScheduledPaymentId |
ASPSP / Payment Scheme | Scheme Payment ID | This is generated by the ASPSP to uniquely identify a payment through a processing scheme. In the case of FPS, this is the FPID. |
...
Code Class | Name | Definition |
---|---|---|
OBExternalPaymentContext1Code | BillPayment | The context of the payment initiation is a bill payment. |
OBExternalPaymentContext1Code | EcommerceGoods | The context of the payment initiation is for goods via an ecommerce channel. |
OBExternalPaymentContext1Code | EcommerceServices | The context of the payment initiation is for services via an ecommerce channel. |
OBExternalPaymentContext1Code | PartyToParty | The context of the payment initiation is a party to party payment. |
OBExternalPaymentContext1Code | Other | The context of the payment initiation is of an other type. |
OBTransactionIndividualStatus1Code | AcceptedSettlementCompleted | Settlement on the debtor's account has been completed. PISPs must not use this status as confirmation that settlement is complete on the creditor's account. |
OBTransactionIndividualStatus1Code | AcceptedSettlementInProcess | All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution. |
OBTransactionIndividualStatus1Code | Pending | Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed. |
OBTransactionIndividualStatus1Code | Rejected | Payment initiation or individual transaction included in the payment initiation has been rejected. |
OBExternalConsentStatus1Code | AwaitingAuthorisation | The consent resource is awaiting PSU authorisation. |
OBExternalConsentStatus1Code | Rejected | The consent resource has been rejected. |
OBExternalConsentStatus1Code | Authorised | The consent resource has been successfully authorised. |
OBExternalConsentStatus1Code | Consumed | The consented action has been successfully completed. This does not reflect the status of the consented action. |
OBChargeBearerType1Code | BorneByCreditor | All transaction charges are to be borne by the creditor. |
OBChargeBearerType1Code | BorneByDebtor | All transaction charges are to be borne by the debtor. |
OBChargeBearerType1Code | FollowingServiceLevel | Charges are to be applied following the rules agreed in the service level and/or scheme. |
OBChargeBearerType1Code | 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. |
OBExternalAuthorisation1Code | Any | Any authorisation type is requested. |
OBExternalAuthorisation1Code | Multiple | Multiple authorisation type is requested. |
OBExternalAuthorisation1Code | Single | Single authorisation type is requested. |
OBExternalStatus1Code | InitiationCompleted | The payment-order initiation has been completed. |
OBExternalStatus1Code | InitiationFailed | The payment-order initiation has failed. |
OBExternalStatus1Code | InitiationPending | The payment-order initiation is pending. |
OBExternalStatus2Code | Authorised | The multiple authorisation flow has been fully authorised. |
OBExternalStatus2Code | AwaitingFurtherAuthorisation | The multiple authorisation flow is awaiting further authorisation. |
OBExternalStatus2Code | Rejected | The multiple authorisation flow has been rejected. |
OBExchangeRateType2Code | Actual | Exchange rate is the actual rate. |
OBExchangeRateType2Code | Agreed | Exchange rate is the agreed rate between the parties. |
OBExchangeRateType2Code | Indicative | Exchange rate is the indicative rate. |
OBPriority2Code | Normal | Priority is normal. |
OBPriority2Code | 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. |
...