Get Preferences

Endpoint: Get /preferences/{Psuid}

This API can be used to retrieve the iDEAL preferences of a PSU. This will only work after an initial payment by this PSU was successfully completed. More details about the fields can be found in the API reference.

Data model

Legend Orange fields: mandatory for iDEAL preferences Purple fields: optional for iDEAL preferences
Request	Response

Example

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

Address: https://localhost:8443/xs2a/routingservice/services/ob/pis/v3/preferences/896587495-51254-85475893254
    HttpMethod: GET
    Headers: {Accept=application/json, AspspId=10002, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=08cc7007-f3c4-6586-4449-8dbf7a92740b, Authorization=Bearer 788b75b7ea27116c74d4a271404c5f49074fbc786ae67cf771a3a44a02a387d8, MessageCreateDateTime=2023-03-15T13:16:40.448Z, Signature=keyId="8D0F688AD3E6C2D4D5FB99FE129F2A2E3B496AF7",algorithm="SHA256withRSA",headers="digest x-request-id messagecreatedatetime (request-target)",signature="hjSmi6wuf/FTDyJ5W7F7QnzDj2X1KVjYuy5hbig+gF6JBhxBfJtZT4utnBgw6OG9dPyqB0EYHPJby786k+q44kl+pWMPJWAJjNHeXyNufNDENF3GGsRsnqBjwrNp9575vsIeimG34A6x47Ap1/01Nmsqk4NzGr0F0HAVyIbeX0Q9oKd6MJHBaswkv9nqaQTajIpmdesAA5D6eNTSfz4oBOCgk2FlJpUAdaAg9Nd1uZuXV+Jeug2coU+jc5FZUQXyZRaV7hiE5UtBIQVxpml6aydFZwCD6OaRJrGvluebVprYc1bqSsiMmS4Pk+qDJshSk5cWWhnp/bVsUFIIK+NU3g=="}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

ResponseCode: 200
 
    Headers: {X-Request-ID=2db64c57-fc84-4998-a83c-aa33ff7fbd9b, MessageCreateDateTime=2023-03-15T13:16:40.898Z, Digest=SHA-256=bd7zfJ14uHY5YwvcXpqr78Df5jUpb0Z64styUET3afI=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="kBpt9O2Auydz0398VFDf0M9lVWcGVI8CsNJbpvAcXxtmTnlO9cH2MlqZQqlMHGjDqcOMmjGeELaQLAft/R1p8HQoyIMJRxh9PtauyKTnHqLavLj6bJr4BoEUeQpE+xfXaR3tebVWz6zr+c7guHEqDjfNKaoKs5HjQIMm/qjKaptU7zkTCIiFsTWh0tmy/h+biI3MJzxqwpZcGdlOCgJ0LI1squZaQXmgA+AsC+uOomBgyhBMPRxMiFIyYPKnA3Ev+UL7UEm3F49B4d/AWYyO2E6B+9p470eA4Ippc4PHeBGvdNgX6zKERsDhCM8ZTmWlOeBh3i5QWvpJF/5Kv6qYHA==",  Date=Wed, 15 Mar 2023 13:16:40 GMT}
    Payload: {
    "AspspName": "IssuerName",
    "AspspLogoUrl": "https://checkout.company.com/login",
    "DebtorAccountIdentification": "NL44RABO******6789"
}

The iDEAL payment api uses a subset of the available open banking API's. In this chapter only the api's needed for iDEAL payment initiation are described, furthermore the fields applicable to an iDEAL payment are marked purple (optional) and orange (mandatory).

Payment Status

Payments have different status depending on the actual state of processing: 

• Open
• SettlementCompleted
• Cancelled
• Expired
• Error

In the following picture the possible iDEAL status are shown in an activity diagram:

POST Payments

Endpoint: POST /payments

The base URL for the payment initiation service API is: /xs2a/routingservice/services/ob/pis/v3

This endpoint is used by the Initiating Party to make an iDEAL 2.0 payment request towards the Open Banking Service.

Data model

Legend Orange fields: mandatory for an iDEAL payment Purple fields: conditionally mandatory for an iDEAL payment
Request (click to enlarge)	Response (click to enlarge)

Example: Standard iDEAL payment without Debtor token

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments
    HttpMethod: POST
    Content-Type: application/json; charset=UTF-8
    ExchangeId: b02d7597-3109-4291-86c3-a1d7faaee11c
    Headers: {Accept=application/json, Digest=SHA-256=0P2tSst5wZ/1rBS+ZF5Pvp79klNUek7tetk0j9w+mNs=, X-Request-ID=fd3a9dae-5323-ea5a-5460-48857a264b9d, Authorization=Bearer 55aefa2dbd728d28dce18ef04e12e7014cde1e665901bc55ae0be044f114001e, MessageCreateDateTime=2023-12-29T16:38:45.770Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="a94S2WkCTBMdzx3nZrDcA61YkAsesjR9BjKkwvGLEmsCPyEUqk55zYHHE0rLVHwVD7YNchMZnEWFR3Vf63egGSTMPTD0xfmHZJua7Wz/VZVpmIkckCjfYiaQTilVImTcKeBIjhnkAd7MP2qQkr6bDtyQQ1zy1DGwDQgTlNVxOHbv+WcMKJxoQcFn5qLTvaq6fnat3a2Ka/jAUHRytAJ+5xWRT0tKq85LvjB10fho8gMgHQ+4q/0H2gmPhh9QYDwCawbBdgdDWb5HtX0qjhftO3iAb4G5HOlrqSBdTprYVDJmtqwh3YEekfy8KyHifiMMWiKVMrKohAcdvazlSMpKXA=="}
    Payload: {
    "PaymentProduct": ["IDEAL"],
    "CommonPaymentData": {
        "Amount": {
            "Amount": "1.00"
        },
        "RemittanceInformation": "iDEAL Standard Flow Minimum fields",
        "RemittanceInformationStructured": {
            "Reference": "iDEALStandardFlow"
        }
    }
}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

ResponseCode: 201
    
Headers: X-Request-ID=d04820e1-d2da-4def-8def-13062b57d3a6, MessageCreateDateTime=2023-12-29T16:38:45.949Z, Digest=SHA-256=kyULomhnKJVz5IfrMDOWTs5ZpmBTKwjFrF6HO/LQG6s=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="m//b5oj7D4Vuw5leONeJnlV6P2YvQEPs/fNq9WxE+HsS68iEICh3uMPPwhqv5JLh5UMDudZG0fY/YtvYx3GMUr5DqGaTxplUWW5+l8dV6JM94POvgOveJOPayCMAW0pWd55sbt/IvBJmc19+z6UKMJ5liNwrvYboxYQp3gb9iCeVyqkUPjjDZmo3EvQXV/6gcZAJCNwPy7vAKmGqiI57f/8EJQEZnwopTVMgn77JdpKht/dMw1oulCot4xaxmgcCwwWVxS951yqsNLxKhOnga4zHCe6anjr1F0qL0qZr85z1eDwVfwwAOiv7tGEzGaXszZnOAnsmwMNjktaVvFBPUQ==", Date=Fri, 29 Dec 2023 16:38:45 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "CommonPaymentData": {
        "ExpiryDateTimestamp": "2023-12-29T20:38:45.925Z",
        "PaymentStatus": "Open",
        "PaymentId": "142641",
        "AspspPaymentId": "0001143558019460"
    },
    "Links": {
        "RedirectUrl": {
            "Href": "https://worldline.com"
        },
        "GetPaymentStatus": {
            "Href": "https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/142641/status"
        }
    },
    "UseWaitingScreen": false
}

Example: iDEAL Payment with Fast Checkout

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

    Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments
    HttpMethod: POST
    Headers: {Accept=application/json, Digest=SHA-256=OCbJurWSWF7ltmMlP/kM4oT9C2p5ZEjh4Oh0hcGrzek=, X-Request-ID=8221d7a3-f41b-514f-bbc8-c39a744d145d, Authorization=Bearer 175a6d1c801969021f1071168661d617a17e3f8ba3824b7401491968644d2704, MessageCreateDateTime=2024-02-14T17:33:58.301Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="CAK3vtjrbVlYjtoi5nmor+hGvOTMHGRT4p+hXHU8MnLv5mJvtQRmQVbzujHENclCxTIyQjo01wy/ckBuYdFj1hyJfWW/JPJ0h1qCZX8/XBrI+IA89ZDqNvcd62wUHOcYeFMtIhcySk03Ln7YRjObIJ1g/ky/jB4/aA0UStAWOstc72YU8S2A+5JLy+lN7MzQoV2KNo3QzOyOzPZ9Ga6/2xdMnq7bG+uSBP9n07JljQPoqPr6onsX7UFSjYtind0kX+6wfH2XjQI2pFEhF1q8brL3ponnmQ053JJpp+dX68HFIuDSXn+O9CHL7HLY51xQIbDilPaocA1dPlPLeSsU+Q==", content-type=application/json; charset=UTF-8}
    Payload: {
    "PaymentProduct": ["IDEAL"],
    "CommonPaymentData": {
        "Amount": {
            "Type": "Fixed",
            "Amount": "24.50",
            "AmountBreakdown": {
                "OrderAmount": "20.50",
                "ShippingCost": "4.00"
            }
        },
        "RemittanceInformation": "iDEAL2.0 FastCheckout Flow",
        "RemittanceInformationStructured": {
            "Reference": "iDEALpurchase21"
        }
    },
    "IDEALPayments": {
        "FlowType": "FastCheckout",
        "ExpectedCheckoutData": {
            "DebtorContactDetails": {
                "FirstName": true,
                "LastName": true,
                "PhoneNumber": true,
                "Email": true
            },
            "ShippingAddress": true,
            "BillingAddress": true
        }
    }
}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

    ResponseCode: 201
    Headers: {X-Request-ID=e3727e35-e3fd-4bb9-9c6c-1725da231527, MessageCreateDateTime=2024-02-14T17:33:58.939Z, Digest=SHA-256=16eS+f5lOwGtN05ukpGcKvDrKt2DR5QCNNsDQfLBe5c=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="RcDMNd5jy/HiJ9s2QxmzwfKuXMTzT4Pk5lp8z0NhOG9fS1VrPVsEcq0u8Hm3C+6UwdPjGDekSC1kytvOm/gHSoZQTIEvpbh99w7yeBCzQNbIQNWr9Fnl4QyXgyrUfVgR889yEGntw+0esl0vu+LpFqi+0CI4rdu5vbzaqLz/oG00D9NC8W0PfEmj469XBevp3hDcnb6ieINmOVo4ZYu2ByaD3p6TC1vN+YYRqw6t/n+qZVjYG3DIhceTtiqsPvoucU7wYVRplqta7GyAK9RGevXzZfY6guiZrsDHl6mWhToKiQoS2YjGE6COF89oOeCfC5NXy4n+/fwKAhqmWBdPsQ==", Date=Wed, 14 Feb 2024 17:33:58 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "CommonPaymentData": {
        "ExpiryDateTimestamp": "2024-02-14T21:33:58.919Z",
        "PaymentStatus": "Open",
        "PaymentId": "174142",
        "AspspPaymentId": "0001077680035886"
    },
    "Links": {
        "RedirectUrl": {
            "Href": "https://worldline.com"
        },
        "GetPaymentStatus": {
            "Href": "https://routingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/174142/status"
        }
    },
    "UseWaitingScreen": false
}

GET Payment Status

Endpoint: GET /payments/{paymentId}/status

This endpoint is used to retrieve the status of a payment.

Data model

Legend Orange fields: mandatory for an iDEAL payment Purple fields: conditionally mandatory for an iDEAL payment
Request	Response (click to enlarge)

Example: iDEAL payment status

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/143374/status
HttpMethod: GET
Headers: {Accept=application/json, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=aa9ec3e7-dc34-f625-2e97-e16644ea1e77, Authorization=Bearer 59519322f1f56db6bd1d23ac0e22cf5015088f085970fb9b461ff2684bc2e96a, MessageCreateDateTime=2024-01-08T12:55:34.630Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="W/6ViHZJ/x0/KM61H7mwCZQp2/3WPax5seqLpCby0BXwgpVoFrSmCu5oHF2pLS2AdHuTiE6qFsBnMkfeGMEDwtqCdY0GZVQGwZ6j9+6zjJHwm21xZ+BmXXH4puRgqxt7DSnOou3SkstzCblf4gSL8MqIyYu7n+eLQlWvjl57t7dNgX0sNTwJE/1GgU/ukDyUoJl4aO1n9ID8EnLDUpXunbZ+1pyCPGbfz5/pDMrJsKZ9l58tLxj7IneU+Mnai8UJEqrQ441ONgYCHF7KoDxu15XA+IY7DnwkA5u/+QN7IY5KpHG3zP19m7jiOimkI6lrqLAc2Ld4iehjNMGve7Ci7w=="}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

    ResponseCode: 200
     
    Headers: {X-Request-ID=3a3df5d3-fa9e-4fee-b9fd-067c23dc91fa, MessageCreateDateTime=2024-01-08T12:55:35.032Z, Digest=SHA-256=pV9HQh/XGpLmawhfj9d/hxYucKkOQCKV9BJ978PeW5k=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="DMvxRTvhRG1kFAy0JPbBzdoRrXq5C9OUJHl6GMQkdNriG4SeuHGaFpdaDA6NgFw2+Ky/RBYiruL18ul+1ZvmdhlyhMaRqR0J7Jg/m9JMyu3wFunBVINysQ+2yj0ucXRMck/CoBW1mYwjDCGCN7xOofw2mZLV6PHjP9xHaDA855iPYE7HUaukB/qveA/S6B2qsjFxDs5AJh6VSWEoknA1+NJZCEX2VC23bnkMgy92qN6bZch5bL3462yFA/0uA75k9XH3O7+Jesl86tBU3kKATNk5n2//vun+Bg4NlSQjU21m6B+nOZT1M+TUkVzG0KWdByf6yFv/x0rp7hifnFZvjA==", Date=Mon, 08 Jan 2024 12:55:35 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "PaymentProductUsed": "IDEAL",
    "CommonPaymentData": {
        "PaymentStatus": "SettlementCompleted",
        "PaymentId": "143374",
        "AspspPaymentId": "0001092688873027",
        "AspspId": "10002",
        "DebtorInformation": {
            "Name": "Edsger Wybe Dijkstra - Callback",
            "Agent": "ABNANL2AXXX",
            "Account": {
                "SchemeName": "IBAN",
                "Identification": "NL44RABO0123456789"
            }
        }
    }
}

In this chapter the transaction flows of two iDEAL payment types are described:

• Standard iDEAL payment
  • Without profile recognition
  • With profile recognition (based on debtor token)
• Fast Checkout iDEAL payment (based on browser cookie)

Additional requirements for the iDEAL payments are described in the chapter iDEAL requirements

Standard iDEAL Payment

An iDEAL transaction for a simple single payment is the basis of the iDEAL flow. The actual iDEAL transaction flow that the PSU follows, depends on where the iDEAL transaction is started at the Initiating Party (mobile app or browser, desktop browser) and where the payment authorization takes place at the ASPSP (mobile banking app, desktop browser, mobile browser). Next to this, it also depends on whether a PSU is already registered for iDEAL, and whether a registered PSU is recognized by the iDEAL Hub via a Debtor Token.

The full iDEAL transaction flow broadly follows the following steps:

1. Shopping Process: The PSU places an order at an Initiating Party and chooses iDEAL as payment method. If the Initiating Party makes use of Debtor Tokens, the Initiating Party shows the preferred ASPSP and IBAN of the recognized PSU alongside the iDEAL payment button.
2. Transaction Initiation: A transaction is created at the Open Banking Service using the Post /payments API, which responds with a redirect URL to the iDEAL payment page or the ASPSP directly.
3. Customer Recognition / ASPSP Selection: The PSU is redirected by the Initiating Party (or CPSP) to the iDEAL payment page, where he can choose an ASPSP or scan a QR code (depending on the web/app context). Alternatively, a recognized PSU (by means of browser cookie or debtor token) may be redirected directly to his preferred ASPSP or receive a push notification from his preferred ASPSP to authorize the iDEAL transaction (decoupled flow).
4. ASPSP Authorization: The PSU is presented with the transaction details at the ASPSP, where he authorizes the iDEAL transaction.
5. Transaction Confirmation & Return to Initiating Party: When the PSU authorizes the payment, a confirmation is sent by the ASPSP to the iDEAL Hub. If applicable, the PSU may be asked to register a profile with iDEAL. The iDEAL Hub informs the Open Banking Service of the payment status, who in turn informs the Initiating Party. In case the Initiating Party implemented the Post status API, they are informed of the payment status directly by the Open Banking Service. In case of a redirect flow, the PSU is ultimately redirected back to the Initiating Party.

Below are two example screen flows. The top one is using a mobile device throughout. The bottom one starts on a non-mobile device and switches to a mobile device for the ASPSP Authorization.

Figure 1 iDEAL transaction flow example on mobile

Figure 2 iDEAL transaction flow starts on non-mobile device (example)

For the initiation of an iDEAL payment two authentication flows are applicable; described in the table below.

Sequence diagrams

The sequence diagrams in this paragraph are examples of possible flows for standard iDEAL payments with and without profile recognition, they do not encompass all the possible flows.

In the diagrams below the sequence of requests is shown. The vertical green bars indicate which party is responsible for the session of the PSU. If a party has the session a screen can be displayed. Notice that in the iDEAL 2.0 flow the Initiating Party can receive a notification when the authorisation of the payment is finished on the ASPSP side. In order to receive this notification, the Initiating Party should implement the Post status API, so this can be called by the Open Banking Service. The initiating party also has the option to request the status by calling the Get /payments/status API of the Open Banking Service.

Redirect and no Debtor token

This is an example of an iDEAL payment where the PSU is not recognized by the iDEAL Hub. 

Redirect with newly generated Debtor token

The iDEAL payment product has the option to store information about the PSU, such as the favorite bank and the IBAN. In order to use this functionality, the Initiating Party should set the field 'UseDebtorToken = true' in a Post /payments request towards the Open Banking Service. If a new debtor token is generated by the iDEAL Hub the Open Banking Service will return, next to the Status of the payment in Post /status, a PsuID in Post /debtorToken. This PsuID can then be used in subsequent iDEAL payments request for the same PSU (again with 'UseDebtorToken' set to true). 

Redirect with existing Debtor token

The Open Banking Service also offers a separate API which can be used to retrieve the preferences of the PSU, the Get /preferences API.

In the sequence diagram below the Get /preferences api is the optional step in the beginning. This flow is using the Debtor Token to reduce the number of steps for the PSU to complete the payment (no ASPSP selection required in the iDEAL Hub).

Decoupled with existing Debtor token

This sequence diagram shows a possible decoupled flow, but is otherwise the same as the 'Redirect with existing debtor token' flow.

In a decoupled flow another device is used to authenticate and authorize the payment, this can be seen in the sequence diagram below by the fact that 2 sessions (green vertical bars) are active at the same time. The PSU doesn't leave the session with the Initiating Party, in the meantime a session is started on another device (for example a smartphone) which handles the interaction between the PSU and the ASPSP. The decoupled flow can potentially speed up the authentication process when bio-metrics are used in the ASPSP's app on the smartphone. 

If the following fields are provided in the Post /payments request a decoupled flow can be initiated by the ASPSP:

• HttpHeaderUserAgent
• PsuId
• UseDebtorToken = true

In case of a decoupled flow the Post /payments response will have 'UseWaitingScreen = true' field.

Fast Checkout iDEAL Payment

An iDEAL payment with iDEAL Checkout allows a PSU to centrally manage his shipping, invoice and contact details in its iDEAL profile and provide these to an Initiating Party as part of the iDEAL payment.

In an iDEAL payment with iDEAL Checkout, a PSU is redirected to the iDEAL Payment Page. If the PSU is recognized by a cookie and an iDEAL profile is detected, the shipping address preferences are shown to him on the iDEAL payment page. The PSU then confirms its preferred contact details and shipping address on the iDEAL payment page, after which he proceeds with the transaction through either a redirect to the ASPSP, a QR code scan, or a push notification to its mobile banking app. After the PSU has authorized the payment at the ASPSP, he is redirected back to the Initiating Party. Upon authorization, the Initiating Party receives confirmation of the payment (similar to a regular iDEAL transaction), which will additionally include the chosen contact details and shipping address of the PSU.

Currently only Dutch shipping addresses are allowed for PSUs

Below an example screen flow of a Fast Checkout iDEAL Payment.

Initiating an iDEAL Checkout transaction with the Open Banking v3 API

An iDEAL Checkout transaction can be initiated by indicating this in the FlowType field of the Post /payments. A breakdown of the transaction amount needs to be added to this call, which will be shown to the PSU during the iDEAL Checkout transaction flow alongside its shipping details.

Initiating an iDEAL Checkout transaction

• To mark a transaction as iDEAL Checkout, the field FlowType MUST be set to FastCheckout
• To initiate an iDEAL Checkout transaction, the AmountBreakdown group MUST be included in the POST /payments call.
  • This group MUST include both an OrderAmount and a ShippingCost. If no shipping costs apply, the field must be filled with 0.
• The sum of the OrderAmount and ShippingCost MUST be equal to the Amount field, which represents the total transaction amount to be payed by the PSU.
• To specify the desired iDEAL Checkout data to be received, the ExpectedCheckoutData group can be set. Only those data fields that are set to true will be included in the callback.

In a iDEAL Checkout transaction, the response of the Post /payments call will always include a URL to the payment page in the Links.RedirectUrl field.

Shipping amount and shipping/invoice address restrictions

• When initiating an iDEAL Checkout transaction, the Initiating Party MUST specify the desired iDEAL Checkout data to be received, which can be included in the payment initiation via the ExpectedCheckoutData group
  • The Initiating Party MUST comply with the General Data Protection Regulation (GDPR). The Initiating Party SHOULD only request the personal data which is needed to fullfill the agreement with the PSU;
• The Initiating Party MUST provide both an OrderAmount and ShippingCost.
• The PSU can only add Shipping and Invoice addresses in The Netherlands. Any other non-NL addresses are currently not allowed. Initiating Party's therefore can trust to receive only NL addresses.
• It is (currently) not possible to dynamically define or alter the shipping amount based on the PSU’s chosen shipping address. The shipping amount can only be provided one time in the transaction initiation. The shipping amount can also be 0.
• In case the PSU cannot or does not want to provide its iDEAL Checkout data, the transaction is canceled. This means that if an iDEAL Checkout transaction is initiated, a successful and payed transaction will always include the iDEAL Checkout data.

Selection/registration of iDEAL Checkout data by PSU

After initiating an iDEAL Checkout, the PSU is redirected to the iDEAL Payment Page. Here, the amount breakdown in order amount and shipping amount is shown, next to the regular payment details.

• If the PSU is recognized by a browser cookie, the known shipping address preferences from its iDEAL profile are shown, in addition to the regular profile preferences. Note that only the data fields indicated in ExpectedCheckoutData will be shown to the PSU (this applies to all iDEAL Checkout flows).
• Profile information presented will be partly masked and can only be fully shown if the PSU authenticates via its ASPSP.
• If a registered PSU does not have any shipping address registered with its profile yet, it will first be asked to provide an address before continuing with the iDEAL Checkout transaction.
• If the PSU is not recognized, it will first be asked whether the PSU has a registered iDEAL profile. In case of an existing profile, the PSU will be asked to select its ASPSP and is redirected to that ASPSP for authentication. After successful authentication, the PSU will return to the iDEAL payment page to view its (unmasked) profile and iDEAL Checkout data.
• At any time during the iDEAL Checkout flow, the PSU may choose to change its preferred address for the transaction or add a new address. This is done on the iDEAL payment page.
• If the PSU is not recognized and is a new PSU, the PSU is asked to register an iDEAL profile, including data for iDEAL Checkout.

Shipping data in transaction callback

After confirming the selected delivery details and preferred IBAN, the PSU is redirected to the ASPSP for authenticating and authorizing the payment. This is done at the ASPSP, similar to a regular transaction.

If the PSU was not registered with iDEAL yet, a registration flow was initiated at the iDEAL payment page.

After the PSU has confirmed the transaction payment at the ASPSP, the PSU’s iDEAL Checkout data (like shipping address) is added to the Post /status callback alongside the other payment details. The iDEAL Checkout data can be found in the DebtorInformation group. Note that only data fields that were indicated in the ExpectedCheckoutData will be included in the callback.

Sequence diagram

This iDEAL Fast Checkout flow is based on de the recognition of the PSU by the iDEAL 2.0 Hub based on a browser cookie. In the sequence diagram below the PSU is recognized. This flow will simplify the checkout screen of the Initiating Party; shipping, invoice and contact details are all handled by the iDEAL Hub. The shipping data is provided in the Post /status request or the Get /payments/status response after the payment was finalized at the ASPSP. 

The Ideal interface has a few additional security features regarding Digital Signatures on top of what is described in the Security page.

Digital Signatures, iDEAL specific

Signing requests for iDEAL by the Initiating Party

If signatures are enforced by the Initiating Party's Acquirer, the following headers will be mandatory in the API requests sent by the Initiating Party to the Open Banking Service:

• Signature
• Digest

The Signature header

The digital signing is done by applying the “Signature” scheme as described in https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12. This is equivalent to the “Authorization” scheme (see Signing the authorization request) and the same procedure is followed to generate the signature and header parts but it uses the Signature header instead of the Authorization header.

In order to generate the signature string that is signed with a key, the Initiating Party must use the values of following HTTP header fields:

• Digest
• X-Request-ID
• MessageCreateDateTime

The headers used to generate the signature string also have to appear in the `headers` parameter of the Signature header, in the fixed order appearing below:

headers=”digest x-request-id messagecreatedatetime (request-target)”

To include the HTTP request target in the signature calculation, use the special `(request-target)` header field name. You can generate the header field value by concatenating the lowercased :method, an ASCII space, and the :path.

The (request-target) header field value to be used for the different APIs is:

*The placeholders {{paymentId}} and {{psuId}} must be substituted with the values as obtained within the respective flows.

The signature string is created by concatenating the lowercased header field names followed with an ASCII colon `:`, an ASCII space ` `, and the header field value. Leading and trailing optional whitespace (OWS) in the header field value MUST be omitted. If the value is not the last value, then an ASCII newline `\n` is appended.

Example: For the payment request with the following required headers

POST /payments HTTP/1.1>
Digest: SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q=
X-Request-ID: 1aad5e0f-02d7-aefb-61e3-6f4d3322cf71
MessageCreateDateTime: 2023-03-15T10:07:26.264Z

The concatenated "Signature String" would be:

Digest: SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q=
X-Request-ID: 1aad5e0f-02d7-aefb-61e3-6f4d3322cf71
MessageCreateDateTime: 2023-03-15T10:07:26.264Z
(request-target): post /xs2a/routingservice/services/ob/pis/v3/payments

The resulting signature parameter of the Signature header would be: 

signature="N7kFLMMi/2R5hCd1gdO+GYhS70DOLMl+n8hborf42nFuu0HFjreoqU70gvxFWzgTPaWjdmNYY/7sOAUAQWudsM61Vc536XmaOGrrSxOINlH9l9QBk31xZMlJBf/+1+GtPb1BR26PYBjxKDMbN9W7PEVZLCDoObSnVLkvKbkLRWl0U8a39mDkUBu70Jw8yWusDU0g1OVN+5YRfENPNtC2ZnVD80gxih4JoFV6f4WCcX4HXVl229veFNO5joNQyUc7qOkXUGN2g0omgN4iJxVGnzEJ9BCrNe+vK9T25LC0fwSp/W6A9dDfuHQzMZgDJZZKpaX0Gg34i68etmi5oLrM3A=="

The algorithm parameter of the Signature header is fixed:

algorithm=”SHA256withRSA”

The ‘keyId’ parameter of the Signature header is the thumbprint of the used certificate, viewed with the SHA1 algorithm. The private key associated with `keyId` is used to generate a digital signature on the concatenated signature string applying the SHA256withRSA algorithm. The complete SIgnature header looks then like this:

Signature: Signature keyId=”DCAC7209573D506FC56095B8B23E8555A8F38B29”, algorithm=”SHA256withRSA”, headers=”digest x-request-id messagecreatedatetime (request-target)”, signature="N7kFLMMi/2R5hCd1gdO+GYhS70DOLMl+n8hborf42nFuu0HFjreoqU70gvxFWzgTPaWjdmNYY/7sOAUAQWudsM61Vc536XmaOGrrSxOINlH9l9QBk31xZMlJBf/+1+GtPb1BR26PYBjxKDMbN9W7PEVZLCDoObSnVLkvKbkLRWl0U8a39mDkUBu70Jw8yWusDU0g1OVN+5YRfENPNtC2ZnVD80gxih4JoFV6f4WCcX4HXVl229veFNO5joNQyUc7qOkXUGN2g0omgN4iJxVGnzEJ9BCrNe+vK9T25LC0fwSp/W6A9dDfuHQzMZgDJZZKpaX0Gg34i68etmi5oLrM3A=="

The Initiating Party must upload the used public certificate in the Back-office so that Open Banking Service is able to validate the signature. If the signature could be validated and the sender has a valid iDEAL subscription a successful response is returned. 

The Digest header

Calculate the Digest header as follows:

• Step1: Create a SHA-256 hash of the Payload
  • Note-1: if the output is hex-encoded, please make sure to convert it to binary data (convert the hex-encoded string to a byte array)
  • Note-2: payload formatting is important. If you generate the Digest by using an unformatted JSON payload, then please make sure that it matches with an unformatted request body used in the API request
• Step 2: Base64-encode the SHA-256 hash
• Step 3: Prepend 'SHA-256=' to the resulting base64-encoded value

Example: For the following payload:

{
    "PaymentProduct": [
        "IDEAL"
    ],
    "CommonPaymentData": 
        "Amount": 
            "Type": "Fixed",
            "Amount": "10.00",
            "Currency": "EUR"
        },
        "RemittanceInformation": "Cookie",
        "RemittanceInformationStructured": 
            "Reference": "iDEALpurchase21"
        }
    },
    "IDEALPayments": 
        "UseDebtorToken": false,
        "FlowType": "Standard"
    }
}

Step 1: The SHA-256 hash of this request body is: "07f3b5b06d0bf3e6c402a585dda3199f7234af1e58562f2be5c33a2479535bb4" (Note: this is a hex-encoded representation)

Step 2: The base64-encoded hash (Note: hex to base64 encoding): "B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q="

Step 3: The Digest header value: "SHA-256=B/O1sG0L8+bEAqWF3aMZn3I0rx5YVi8r5cM6JHlTW7Q="

Signing Requests to the Initiating Party (notification requests) and Responses sent to the Initiating Party

If signatures are enforced by the Initiating Party's Acquirer, the following headers will be present in the API requests and responses sent by the Open Banking Service to the Initiating Party:

• Digest 
• Signature

The digital signing performed by the Open Banking Service is done by applying the same “Signature” scheme as described above.

A notification request or response from Open Banking Service to the Initiating Party may contain for example a header like:

Signature: keyId="2DOXXL7lNBNKJSMHKO2IBQC1", algorithm="SHA256withRSA", headers="digest x-request-id messagecreatedatetime (request-target)", signature="lulVhOhRwFs5G8+uGCh3BjJHBG540AyTCyaKhr9QE71YTtljxFt1b7i55C9QROw/zGt+iac3cBfGGRiTAfW4ta9Hn8+u7LvyfYHFcdxBhNj7T6dgrv+MLG6aI6hw/3Cwmkz/OwESBrQJzISWf8/0bgYNuXnuPf5r7BGMhHdhIr+RNxocW6wkSOEVQfOGYazy7YsoJhVEwNEt9gN++sw9HVfaxmwjl8MqxGNcLoVAgoGMcUOvNhjATA1MSzOj2cmw6kdi2yY2w7XiMuU9Tma0jQ3CGKhxIkD8Na2Vq1K2bs/n2DOxxL7lNbnKjsmhkO2ibQc1+RV3pXQJ1SDSI3EW/w=="

In order to ensure that the contents of the sent messages are correct and have not been altered during transmission or storage the Initiating Party can validate the received signature. For the validation of the signature, the Initiating Party can use the public certificate of the Open Banking Service which can be downloaded from the Back-office.

The iDEAL scheme has some additional rules defined by Currence, the scheme owner.

Redirecting of PSU's

As a response to an iDEAL transaction initiation, the Initiating Party will receive a RedirectUrl, which is either an ASPSP URL (directing the PSU directly to the ASPSP domain) or a Payment Page URL (directing the PSU to the iDEAL Payment Page).

• If redirected from a browser, the redirect to the ASPSP URL or iDEAL Payment page MUST be performed from the browser window where the PSU selected iDEAL as payment method. The complete page of the InItiating Party shall be replaced by the complete iDEAL Payment page.
  • Initiating Parties MUST NOT open the redirect to the iDEAL Payment page or ASPSP URL in a new browser window.
  • Initiating Parties MUST NOT present the iDEAL Payment page or ASPSP URL embedded within its own page, as this disallows recognition of a cookie.
• If redirected from an Initiating Party app, the redirect MUST take place outside the app in the default browser of the PSU.

Initiating Parties MUST NOT redirect PSU's in a custom made in-app webview browser. Doing so will disallow for PSU's to be redirected to their mobile banking apps and will seriously breach privacy regulations.

Exceptions to the above are the use of  SafariViewController for Apple iOS and Chrome Custom Tabs for Android. However be aware that these may not correspond to the PSU's default browsers, so that PSU recognition based on cookie might not work.

• During the migration period to the updated iDEAL specifications, the Initiating Party is still allowed to share a preferred ASPSP (for example when the Initiating Party also stores this preference). This feature will be discontinued after the migration period ends.

Retrieving the Status of the transaction

• If the Initiating Party has not yet received a confirmation of the payment status when the PSU opens the returnURL, the Initiating Party MUST retrieve the transaction status by calling the status API of the Open Banking Service.
• The Initiating Party MUST inform the PSU of a success status of the transaction, so that the PSU is certain that the payment status was correctly received by the Initiating Party.
• The Initiating Party MUST NOT poll the status and MUST adhere to the retry scheme, see Common API elements.

Presentation of Standard iDEAL payment on Initiating Party environment

There are some rules regarding the presentation of iDEAL on the Initiating Party's environment. The main purpose of these is to create a uniform user experience for PSU's whenever and wherever they pay with iDEAL.

• The iDEAL payment option must be presented in the list of payment options in such a way that it receives at least the same amount of attention as other payment options.
• The rules on presentation the iDEAL Payment button and the iDEAL logo can be found here: https://www.ideal.nl/en/marketing-ideal.
  • In cases where the iDEAL logo cannot be displayed at the required size on a mobile device the mandatory free space of 15px around the logo may be reduced to accommodate the requirements of the mobile device.

Presentation of Fast Checkout iDEAL payment on Initiating Party environment

• To indicate to PSUs that iDEAL Checkout is offered the Initiating Party MUST show the iDEAL Checkout logo. Logo’s can be found here: https://www.ideal.nl/en/marketing-ideal. This logo may be accompanied by the term ‘Snel Bestellen’ to provide additional clarity on the flow the PSU will enter after selecting this option;
• Before the PSU selects iDEAL Checkout, the applicable shipping costs MUST be communicated to the PSU, to prevent that the PSU is confronted with a higher amount in the iDEAL screens than expected;
• The Initiating Party MUST confirm the datafields, received from Currence, to the PSU, preferably on the order confirmation screen.

Profile recognition via Debtor Tokens

For an enhanced user flow for returning PSU's, the Initiating Party may want to make use of Debtor Tokens. The Debtor Tokens allow the Initiating Party to present the PSU’s preferred IBAN within its Initiating Party Domain, and prevent a redirect to the iDEAL Payment Page.

If an Initiating Party wishes to make use of Debtor Tokens for its PSU's, the following applies:

• The PSU MUST hold an account with the Initiating Party;
• To retrieve the preferred ASPSP and (masked) IBAN of the PSU, the Initiating Party MUST provide a Debtor Token that uniquely identifies the PSU at the Initiating Party;
• The Initiating Party MUST be able to recognize the PSU on a return visit;
• The Initiating Party MUST retrieve and display the preferred ASPSP and masked IBAN of the PSU together with the iDEAL payment button;
• The Initiating Party MUST only use Debtor Token that was received in the last transaction for that PSU

Please note that a Debtor Token can only be linked to one iDEAL profile.

Some ASPSPs supports payment cancellation. Customer (PSU) / Initiating party (user) can cancel the initiated payment with ASPSP if payment settlement process not started by the customer’s (PSU) bank.

As an Open Banking Service provider, we are allowing to cancel the payment if payment status are as below,

PaymentStatus
{
       “Open”,
       “Pending”,
       “PartiallyAuthorised”,
       “Authorised” 
}

Remark : Payment cancellation is not allowed if payment status for initiated payment is apart from any other from mentioned above.

For this scenario, we have considered that payment status = “Authorised” for the initiated payment.

Take the following steps to complete this scenario.

Step – 1 : Get the reach details :

Reach details provides list of APIs needs to be used for this scenario and mandatory fields needs to be passed for successful API call towards ASPSP mock.

Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment Cancellation” and the ASPSP ID = “20114”, which has to be used to cancel the initiated payment and other further payment related requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

Step – 2 : Initiate the payment :

Call the POST /payments API with mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive payment ID, ASPSP redirect link to authorise the initiated payment and link to call GET /payments/status API to get the status of the initiated payment.

If GET /payments/status endpoint has been called before user provides his / her approval, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.

Step – 3 : Authorise or Cancel the payment at ASPSP Mock :

With ASPSP redirect link received in response of POST /payments, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (user) can provide dummy credential details as this is example purpose only. Once customer (PSU) provides his / her dummy credentials, he / she will be redirected to ASPSP Mock GUI page with “Approve” & “Deny” buttons to authorise or cancel the payment.

If customer (PSU) “Approve” the payment, payment will get initiated with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).

If customer (PSU) “Deny” the payment, ASPSP Mock will reject the initiated payment and customer (PSU) will redirect back to initiating party (user).

Remark : GUI page of ASPSP Mock to approve or deny the payment is just a demo purpose. Actual ASPSP GUI page to approve or deny the payment may vary based on ASPSP.

Step – 4 : Get the payment status :

Call the GET /payments/status API to get the latest payment status from ASPSP Mock.

If payment is authorised by customer (PSU), initiating party (user) will receive payment status = “Authorised.

If payment is deny by customer (PSU), initiating party (user) will receive payment status = “Cancelled” as final payment status.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Step – 5 : Cancel the payment :

If payment status = “Authorised”, call DELETE /payments API to cancel the initiated payment.

Step – 6 : Get the payment status :

Call the GET /payments/status API to get the latest payment status from ASPSP Mock.

If payment is cancelled by ASPSP Mock sucessfully, initiating party (user) will receive payment status = “Cancelled”.

Sequence Diagram :

Some ASPSP requires hybrid payment authorisation for payment processing.

Take the following steps to complete this scenario.

Step – 1 : Get the reach details :

Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment Redirect with Embedded – Hybrid flow” and the ASPSP ID = “20121”, which has to be used to initiate the payment with hybrid mode of authorisation and other further payment related requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

Step – 2 : Payment initiation and customer authentication :

• Initiate the payment : Call the POST /payments API without ASPSP PSU-ID and with other mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive Payment ID, “AspspRedirectUrl” URL for  customer (PSU) authentication at ASPSP Mock & GET /payments/status API link.

• Customer Authentication : Customer (PSU) will be redirected to ASPSP Mock GUI page to provide his / her PSU-ID (Customer ID) which is known to the Bank. At this point, customer (PSU) can provide his / her authentication to ASPSP Mock or cancel the payment initiation.

Remark : Customer can provide dummy PSU-ID (Customer ID) to ASPSP Mock.

If GET /payments/status endpoint has been called, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.

Step – 3 : Get the payment status and select authentication method :

• Get the payment status : Call the GET /payments/status API. If customer cancel the authentication process, ASPSP Mock will respond with payment status = “Cancelled” to initiating party (user). If customer (PSU) authenticated successfully at ASPSP Mock, Mock will respond with list of available SCA methods (if multiple SCA methods available at ASPSP) for the customer (PSU) to choose.

• Select authentication method : For this scenario, customer (PSU) need to choose ‘SCARedirect’ method for payment authorisation and initiating party (user) need to call the PUT /payments/authorisations to update the selected SCA method to ASPSP Mock. In response, ASPSP Mock will respond with “ASPSPRedirectURL” for payment authorisation.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Step – 4 : Authorise or Cancel the payment at ASPSP Mock :

With ASPSP redirect link received in response of PUT /payments/authorisation, customer (PSU) will get redirect to ASPSP Mock GUI page with “Approve” & “Deny” buttons to authorise or cancel the payment.

If customer (PSU) “Approve” the payment, payment will get initiated with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).

If customer (PSU) “Deny” the payment, ASPSP Mock will reject the initiated payment and customer (PSU) will redirect back to initiating party (user).

Remark : GUI page of ASPSP Mock to approve or deny the payment is just a demo purpose. Actual ASPSP GUI page to approve or deny the payment may vary based on ASPSP.

Step – 5 : Get the payment status :

Call the GET /payments/status API to get the latest payment status from ASPSP Mock.

If payment is authorised by customer (PSU), initiating party (user) will receive payment status = “SettlementCompleted”.

If payment is deny by customer (PSU), initiating party (user) will receive payment status = “Cancelled” as final payment status.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Sequence Diagram :

For this scenario, explicit embedded Pre-Authentication is require with payment in embedded authorisation.

Take the following steps to complete this scenario.

Step – 1 : Get the reach details :

Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment embedded with Explicit PreAuth Embedded” and the ASPSP ID = “20120”, which has to be used to initiate the payment and other further payment related requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

Below is example of pre-authentication reach details for ASPSP.

{
      "AspspId": "20120",
      "Name": [
        {
          "Label": "Payment embedded with Explicit PreAuth embedded",
          "Language": "en"
        }
      ],
      "Country": "XX",
      "CategoryLabel": [
        "Retail"
      ],
      "Details": [
        {
          "Api": "POST /payments",
          "Fieldname": "CommonPaymentData.EndToEndId",
          "Type": "MANDATORY",
          "ProtocolVersion": "CREALOGIX_V_1_0_5",
          "Condition": "!(PaymentProduct=IDEAL)"
        },
        {
          "Api": "POST /scheduled-payments",
          "Fieldname": "DebtorAccount",
          "Type": "MANDATORY",
          "ProtocolVersion": "CREALOGIX_V_1_0_5"
        },
        {
          "Api": "POST /payments",
          "Fieldname": "CommonPaymentData.InitiatingPartyReferenceId",
          "Type": "MANDATORY",
          "ProtocolVersion": "CREALOGIX_V_1_0_5",
          "Condition": "!(PaymentProduct=IDEAL)"
        },
        {
          "Api": "POST /v1/payments",
          "Fieldname": "PaymentProduct",
          "Type": "MANDATORY",
          "Value": "Normal|Instant|Domestic",
          "ProtocolVersion": "CREALOGIX_V_1_0_5"
        },
        {
          "Api": "POST /pre-authentication",
          "Type": "SUPPORTED",
          "ProtocolVersion": "CREALOGIX_V_1_0_5"
        },
        {
          "Api": "POST /payments/{paymentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "CREALOGIX_V_1_0_5"
        }
      ],
      "Options": [],
      "BIC": "XXPIS003"
    },

In above example, POST /pre-authentication API is mentioned without FieldName and Type = “SUPPORTED” means, ASPSP is supporting pre-authentication.

"Api": "POST /pre-authentication", 
"Type": "SUPPORTED",
"ProtocolVersion": "CREALOGIX_V_1_0_5" 

Step – 2 : Initiate the payment :

To initiate the payments, below processes needs to be follow.

• Explicit Pre-Authentication in Embedded
• Payment authorisation in Embedded

Step – 3 : Initiate Explicit Pre-Authentication in Embedded :

Perform below steps to initiate explicit pre-authentication in embedded.

• Initiate explicit pre-authentication : Call POST /pre-authentication to initiate explicit Pre-Authentication process. In response of POST /pre-authentication, initiating party (user) will receive PreAuthenticationId, link for “UpdatePsuCredentialsForPreAuthentication” API endpoint for customer (PSU) authentication and “GetPreAuthenticationStatus” API link to get the status of the PreAuth from ASPSP Mock.
• Perform customer (PSU) authentication : Call the PUT /pre-authentication API with customer’s (PSU) credential details. Once ASPSP Mock identifies customer (PSU) successfully, it will response with list of available SCA methods with “SelectAuthenticationMethod” link (if multiple SCA methods available at ASPSP) for the customer (PSU) to choose.
• Authorisation method selection : Once appropriate SCA method chosen to authorise the payment by customer (PSU), initiating party (user) need to call the PUT /pre-authentication API to inform ASPSP Mock.
• Provide challenge data for selected SCA method : Based on selected SCA method by customer (PSU), ASPSP will response with Challenge Data for customer (PSU) for authentication. Once customer (PSU) respond with answer to Challenge Data, initiating party (user) need to call the PUT /pre-authentication API to inform ASPSP Mock. ASPSP Mock will verify the details.

Remark : If initiating party (user) calls GET /pre-authentication/status API during pre-authentication process, ASPSP Mock will respond back PreAuthenticationStatus = “Open”.

Step – 4 : Get the pre-authentication status :

Call the GET /pre-authentication/status API to get the pre-authentication status from ASPSP Mock.

If pre-authentication is authorised by customer (PSU), initiating party (user) will receive PreAuth status = “Authorised”.

If pre-authentication is deny by customer (PSU), initiating party (user) will receive PreAuth status = “Rejected” and payment cannot be initiated by initiating party (user).

Remark : Pre-Authentication status provided for this scenario is just to guide initiating party (user) for pre-authentication process. Actual pre-authentication status may vary based on scenario from actual ASPSP.

Step – 5 : Payment initiation and Authorisation steps :

• Initiate the payment : Once customer (PSU) authenticated successfully with ASPSP and PreAuthenticationStatus = “Authorised”, Call the POST /payments API with mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive list of available SCA methods with “SelectAuthenticationMethod” link (if multiple SCA methods available at ASPSP) for the customer (PSU) to choose.
• Authorisation method selection : Once appropriate SCA method chosen to authorise the payment by customer (PSU), initiating party (user) need to call the PUT /payments/authorisation API to inform ASPSP Mock. Based on selected SCA method by customer (PSU), ASPSP will response with Challenge Data for customer (PSU) to authorize the payment.
• Provide challenge data for selected SCA method : Once customer (PSU) respond with answer to Challenge Data, initiating party (user) need to call the PUT /payments/authorisation API to inform ASPSP Mock. ASPSP will verify the details and starts payment settlement process.

If GET /payments/status endpoint has been called before initiating party (user) provides his / her approval, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.

Step – 6 : Get the payment status :

Call the GET /payments/status API to get the latest payment status from ASPSP Mock.

If payment is authorised, initiating party (user) will receive payment status = “SettlementCompleted” as final payment status.

If during any step in Embedded authorisation process, if customer (PSU) has not provided appropriate response, payment will be marked as “Cancelled” at ASPSP Mock and initiating party (user) will receive payment status = “Cancelled” as final payment status.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Sequence Diagram :

For embedded authorisation approach, ASPSP process the payment authorisation through the PISP – ASPSP interface.

Generally there are three steps involve in embedded payment authorisation process.

• In first step, the PSU needs to authenticate himself / herself with the ASPSP.
• In second step, once the PSU is successfully authenticated by the ASPSP, the ASPSP provides a list of SCA methods. In case the ASPSP supports several SCA methods the PSU needs to choose the appropriate SCA method.
• In third step, based on chosen SCA method by the PSU, the ASPSP provides the challenge to the PSU to authorise the payment. The PSU needs to provide challenge response.

Once all these authorisation steps completed successfully, ASPSP starts payment settlement process.

Take the following steps to complete this scenario.

Step – 1 : Get the reach details :

Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment Embedded” and the ASPSP ID = “20105”, which has to be used to initiate the payment with embedded mode of authorisation and other further payment related requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

Step – 2 : Payment initiation and Authorisation steps :

Perform below steps to initiate payment.

• Initiate the payment : Call the POST /payments API with mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive “PostAuthorisationForEmbedded” API endpoint link customer (PSU) authentication.

• Perform customer (PSU) authentication : Call the POST /payments/authorisation API with customer’s (PSU) credential details. Once ASPSP Mock identifies customer (PSU) successfully, it will response with list of available SCA methods (if multiple SCA methods available at ASPSP) for the customer (PSU) to choose.

• Authorisation method selection : Once appropriate SCA method chosen to authorise the payment by customer (PSU), initiating party (user) need to call the PUT /payments/authorisation API to inform ASPSP Mock.

         Remark : Use currently we have populated request body with default selected "AuthenticationMethodId": "13"  for

         "PhotoOTP" SCA method in Put /authoirsations API.

         Request body:

        {
           "AuthenticationMethodId": "13"
        }

• Provide challenge data for selected SCA method : Based on selected SCA method by customer (PSU), ASPSP will response with Challenge Data for customer (PSU) to authorize the payment. Once customer (PSU) respond with answer to Challenge Data, initiating party (user) need to call the PUT /payments/authorisation API to inform ASPSP Mock. ASPSP will verify the details and starts payment settlement process.

         Remark : Use Put /authorisations API with below request body parameters to provide challenge data to complete

         Embedded authorisation flow.

         Request body:

         {
            "ScaAuthenticationData":"123456"
         }

If GET /payments/status endpoint has been called before initiating party (user) provides his / her approval, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.

Step – 3 : Get the payment status :

Call the GET /payments/status API to get the latest payment status from ASPSP Mock.

If payment is authorised, initiating party (user) will receive payment status = “SettlementCompleted” as final payment status.

If during any step in Embedded authorisation process, if customer (PSU) has not provided appropriate response, payment will be marked as “Cancelled” at ASPSP Mock and initiating party (user) will receive payment status = “Cancelled” as final payment status.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Sequence Diagram :

The transaction flow in the decoupled authorisation approach is similar to the Redirect authorisation approach. The difference is that the ASPSP is asking the customer (PSU) to authorise the payment e.g. via a dedicated mobile app, or any other application or device which is independent from the online banking frontend.

Since decoupled payment approval / rejection is out of scope, we have only considered happy flow for this scenario assuming user is going to provide his / her approval for initiated payment on decoupled application / device.

Take the following steps to complete this scenario.

Step – 1 : Get the reach details :

Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment decoupled (polling required)” and the ASPSP ID = “20200”, which has to be used to initiate the decoupled payment with redirect mode of authorisation and other further payment related requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

Step – 2 : Initiate the payment :

Call the POST /payments API with mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive POST /payments/identification API endpoint and GET /payments/status API endpoint links to get the status of the payment.

Initiating party (user) need to call POST /payments/identification API endpoint to provide “AspspPsuId”. This is PSU’s ID at ASPSP, which helps ASPSP to uniquely identify the bank’s customer (PSU) and ASPSP can initiate payment authorisation on decoupled application / device which is known to customer (PSU).

In response of POST /payments/identification API, customer (PSU) will be notify to use his / her decoupled application / device provided by ASPSP to authorise the initiated payment.

If GET /payments/status endpoint has been called before customer (PSU) provides his / her approval, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.

Step – 3 : Authorise or Cancel the payment :

Since payment approval / rejection on decoupled application / device is out of scope in this scenario, we have only considered happy flow and considering user is going to provide his / her approval for initiated payment on decoupled application / device.

Remark : During actual payment authorisation on decoupled application / device, PSU can approve / reject the payment based on functionality provided in decoupled application / device.

Step – 4 : Get the payment status :

Initiating party (user) need to do polling by calling GET /payments/status to get the latest payment status from ASPSP Mock.

Since the decoupled approval is out of scope of this scenario we have implemented an timed status change of the payment by the ASPSP mock.

If initiating party (user) call GET/payments/status after 8 seconds, in response initiating party (user) will receive payment status = “Authorised” from ASPSP Mock.

If initiating party (user) call GET/payments/status after 8 seconds, in response initiating party (user) will receive payment status = “SettlementCompleted” from ASPSP Mock as a final payment status.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Sequence Diagram :