Payment Initiation API

for iDEAL 2.0

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.

Information

During a prolonged period the Initiating Party is allowed to use the CommonPaymentData.DebtorInformation.Agent field to pass a BIC which identifies the ASPSP. This is done to facilitate a smooth migration from iDEAL to iDEAL 2.0.

When the CommonPaymentData.DebtorInformation.Agent field is filled the response will always have a RedirectUrl which redirects directly to the ASPSP.

This feature is only available if FlowType = standard and no iDEAL Debtor token is used.
This feature will be discontinued and is only meant to be used during the migration period.

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"
            }
        }
    }
}