EU IDENTITY WALLET

Workgroup:

EUDIW

FYI:

draft-payment-presentation-profile

Published:

28 February 2024

Intended Status:

Experimental

Expires:

31 August 2024

Author:

F. Andreae

DSGV

Payment Presentation Profile - draft 0

▲

Table of Contents

• 1.??Abstract
• 2.??Terminology
• 3.??Profile3.1.??Flow3.1.1.??Onboarding3.1.2.??Payment
• 4.??Open Standards Requirements
• 5.??Payment order data model
• 6.??Credentials6.1.??JWT VC6.1.1.??Payment Credential6.1.2.??Payment order credential
• 7.??Authorization Request7.1.??Invoking the Wallet7.2.??Authorization Request URI7.3.??Authorization request of the payee7.3.1.??Request parameters7.3.2.??Request Object7.3.3.??Presentation definition
• 8.??Authorisation response8.1.??VP Token8.2.??Optional enrichment
• 9.??Normative References
• Author's Address

1. Abstract

The Payment Presentation Profile defines a set of requirements against existing specifications to enable the interoperable presentation of payment data between a payment initiator, wallets and a bank.

This document is not a specification, but a profile. It outlines existing specifications required for implementations to interoperate among each other. It also clarifies mandatory to implement features for the optionalities mentioned in the referenced specifications.

The profile uses OpenID for Verifiable Presentations [OPENID4VP] as the base protocol for the request and verification of W3C JWT VCs as W3C Verifiable Presentations [VCDATA]. A full list of the open standards used in this profile can be found in Overview of the Open Standards Requirements.

2. Terminology

• Authorization Request: OAuth 2.0 Authorization Request extended by [OPENID4VP.xsr]
• Authorization Response: OAuth 2.0 Authorization Response extended by [OPENID4VP]
• Decentralized Identifier: An identifier with its core ability being enabling Clients to obtain key material and other metadata by reference, defined in [DID.CORE].
• Wallet: An entity that receives, stores, presents, and manages credentials and key material of the End User. A wallet is defined as a nativ mobile application.
• Payment credential : A verifiable credential issued by a bank to a customer. The credential must include the claim direct_post_uri and must be cryptographically bound to a private key residing in the wallet.
• Payment order: A data set holding relevant payment details.
• Payment order credential: A self-attested verifiable credential generated by the wallet containing a payment message. The credential must always be signed using the private key connected to the payment credential.

3. Profile

3.1. Flow

A brief description of a payment flow based on the mechanics defined in [OPENID4VP.xsr].

3.1.1. Onboarding

Onboarding is a one time process to exchange a cryptographic key-set between the bank and a customer wallet. The exchange is done by the bank issuing a payment credential using [OPENID4VC].

3.1.2. Payment

The payee creates an authorization request as defined in [OPENID4VP.xsr] which is presented to the wallet. This can be done either

• cross-device by presenting it as a QR code / NFC Tag or
• same-device-flow by activating a link with a custom URL scheme.

The wallet asks for the signer (aka payment credential) that should be used for making the payment and present the payment details to the payer and asks for consent. Once the payer selected a payment credential and consents to the payment, the wallet signs and presents the payment order credential back to the bank using the direct_post_uri endpoint configured in the selected payment credential.

The bank verifies the credential and executes the payment. Optionally the bank also communicates the status of the payment back to the payee using a callback URL that might be included in the payment details. In case the bank requires additional credentials or needs to modify the original payment order, it may request it using either [OPENID4VP] or [OPENID4VP.sr].

4. Open Standards Requirements

• VCs MUST adhere to the [VCDATA] and be encoded as JSON and signed as JWT as defined in Section 6.3.1 of [VCDATA]. VCs encoded as JSON-LD and signed using Linked Data Proofs are NOT supported.
• For transportation of VCs, [OPENID4VC] MUST be used.
• As the query language, [DIF.PresentationExchange] MUST be used and conform to the syntax defined in [OPENID4VP].
• Decentralized Identifiers (did), as defined in [DID.CORE], MUST be used as identifiers of the entities. Implementations MUST support did:jwk as a mandatory DID method as defined in [JWK.DID].

5. Payment order data model

A payment order is a JSON object based on the data model describend in [PAYMENTDATA] and extended by the following fields:

• $.creditor.additionalPartyInformation.merchantCallbackUrl: URI string pointing to an endpoint where the payee is accepting HTTPS POST request. The endpoint is used by the payers bank to communicate the status of the payment back to the payee.

6. Credentials

6.1. JWT VC

Payment credential and the self-attested payment order credential MUST be issued as W3C Verifiable Credentials and presented as JWT as defined in Section 6.3.1 of [VCDATA].

For the purpose of this profile, registered JWT claims exp, iss, nbf, jti, sub and aud MUST be used in a JWT VC instead of their respective counterparts defined in [VCDATA].

6.1.1. Payment Credential

A payment credential MUST be of the type PaymentKey.

The credentialSubject includes the following properties:

• aspsp_name: RECOMMENDED. Name of the issuing bank.
• account: REQUIRED. An account alias this PaymentKey relates to.
• scheme: REQUIRED. Name of an connected payment scheme.
• direct_post_uri: REQUIRED. As defined in [OPENID4VP.xsr], it must hold an URI string the wallet can use to initiate the [OPENID4VP] flow.
• presentation_definition_uri: REQUIRED. As defined in [OPENID4VP.xsr], it must hold an URI string referencing a presentation definition used for the authorization response to the bank.

Example of an issued PaymentKey.

{
  "iss": "did:jwk:eyJjcnYiOiJQLi...,
  "jti": "dc961165-fb13-4d19-98f0-37c9bb06be",
  "nbf": 1707232027,
  "aud": "EUDIW",
  "nonce": "a2bcc3e0-623d-441d-aa80-31d82aa665d1",
  "sub": "did:jwk:eyJrdHkiOiJFi...",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "type": [
      "VerifiableCredential",
      "PaymentKey"
    ],
    "credentialSubject": {
      "aspsp_name": "Super Bank",
      "account": "My Payment Account",
      "direct_post_uri": "https://bank.com/init_auth/ebfeb1f7",
      "presentation_definition_uri": "https://bank.com/pd/ebfeb1f7"
    }
  }
}

        

Example of a referenced presentation definition requesting a payment order issued by did:example:sd5sde:

{
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_descriptors": [
      {
        "id": "request2sign_input",
        "constraints": {
          "subject_is_issuer": "required",
          "fields": [
            {
              "id": "request2sign_payload",
              "path": [
                "$.credentialSubject.request2sign_payload"
              ],
              "filter": {
                "$schema": "https://json-schema.org/draft-04/schema#",
                "type": "object",
                "properties": {
                  "instructedAmount": {
                    "type": "object",
                    "properties": {
                      "currency": {
                        "type": "string"
                      },
                      "amount": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "currency",
                      "amount"
                    ]
                  },
                  "creditorName": {
                    "type": "string"
                  },
                  "creditorAccount": {
                    "type": "object",
                    "properties": {
                      "iban": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "iban"
                    ]
                  },
                  "remittanceInformationUnstructured": {
                    "type": "string"
                  }
                },
                "required": [
                  "instructedAmount",
                  "creditorName",
                  "creditorAccount",
                  "remittanceInformationUnstructured"
                ]
              }
            },
            {
              "id": "issuer",
              "path": [
                "$.iss"
              ],
              "filter": {
                "type": "string",
                "const": "did:example:sd5sde"
              }
            },
            {
              "id": "subject",
              "path": [
                "$.sub"
              ],
              "filter": {
                "type": "string",
                "const": "did:example:sd5sde"
              }
            }
          ]
        }
      }
    ]
  }
}

        

6.1.1.1. Issuing

The bank is the issuer of the payment credential and MUST be identified by a did:jwk according to [JWK.DID]. The JWK of the bank SHOULD include or reference a certificate, which allows the wallet to verify that the credential was issued by a trustworthy source.

The iss value of the payment credential must be set to the did:jwk of the bank. The payment credential MUST be signed using the private key belonging to the did:jwk of the bank.

The payment credential MUST be cryptographically bound to a dedicated private key created by the wallet. The private key is used for

• signing a proof while requesting the issuing of a payment credential as described in Section 7.2 of [OPENID4VC]. The proof parameter is therefor REQUIRED by this profile.
• signing the presentation of self-attested payment order credentials

6.1.2. Payment order credential

A payment order credential MUST be of type Request2Sign and PaymentOrder.

The credentialSubject MUST include the property request2sign_payload which holds the payment order.

Example of an self-attested payment order credential:

{
  "iss": "did:jwk:eyJrdHkiOiJFi...",
  "jti": "dc961165-fb13-4d19-98f0-37c9bb06be",
  "nbf": 1707232027,
  "aud": "EUDIW",
  "nonce": "a2bcc3e0-623d-441d-aa80-31d82aa665d1",
  "sub": "did:jwk:eyJrdHkiOiJFi...",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "type": [
      "VerifiableCredential",
      "Request2Sign",
      "PaymentOrder"
    ],
    "credentialSubject": {
        "request2sign_payload" : {
          "instructedAmount": {
             "currency": "EUR",
             "amount": "123.50"
          },
          "creditorName": "Merchant A",
          "creditorAccount": {
             "iban": "DE02100100109307118603"
          },
          "remittanceInformationUnstructured": "Ref Number Merchant"
       }
    }
  }
}

        

6.1.2.1. Issuing

The issuer of the payment order credential is the wallet using the key-set generated during the issuing of the payment credential.

7. Authorization Request

7.1. Invoking the Wallet

Custom URL Scheme eudiw:// MUST be used to invoke the wallet.

7.2. Authorization Request URI

Request object MUST be passed by reference, rather than by value using the request_uri parameter defined in Section 5.2 of [RFC9101]. The request object MUST be a signed JWT as defined in Section 6.2 of [RFC9101].

Example of an authorization request:

eudiw://auth?client_id=did:jwk:eyJrdHkiO...&
    request_uri=https://bank.com/ar/FitypIiut
        

Example of a JWT request object:

{
  "aud": "EUDIW",
  "authorization_details": [
    {
      "type": "request2sign",
      "payload": {
        "instructedAmount": {
          "amount": "5.59",
          "currency": "EUR"
        },
        "paymentIdentification": {
          "endToEndIdentification": "CDF834F4-5CF4-4A27-9C04-9EEB347BF"
        },
        "remittanceInformationUnstructured": [
          "Shopping at Merchant A"
        ],
        "creditor": {
          "additionalPartyInformation": {
            "merchantCallbackUrl": "https://merchant.com/callback"
          },
          "name": "Merchant A"
        },
        "creditorAccount": {
          "iban": "DE88940594210020801890"
        }
      }
    }
  ],
  "client_id": "did:jwk:eyJrdHkiOiJFQ...",
  "client_id_scheme": "did",
  "iss": "did:jwk:eyJrdHkiOiJFQ...",
  "nonce": "CPxpkYdz2ECNwYAx",
  "presentation_definition_uri": "https://bank.com/pd",
  "response_mode": "direct_post",
  "response_type": "vp_token",
  "response_uri": "https://bank.com/verifier/present",
  "state": "DUcDuyi8efXwAsB6"
}

        

7.3. Authorization request of the payee

The authorization request created by the payee must be done as described in Section 4 of [OPENID4VP.xsr]. The payload of the request2signobject MUST contain the payment order.

eudiw://auth?
    client_id==did:jwk:eyJreFkiO...&
    request_uri=https://merchanta.com/payment/d6g4f5

Displayed as QR Code:

  █?????█ ▄▄ █? ██?  ?█ ▄█▄ █▄  █?????█
  █ ███ █ ?▄ ▄  ?  ██▄? ▄█  ▄██ █ ███ █
  █ ??? █ █?▄? ?▄██▄█▄?▄█?▄▄?█▄ █ ??? █
  ??????? █ █▄█ ? ?▄? ?▄█▄█ █▄? ???????
  █?▄█▄▄?█ ▄ ? ▄??█▄?▄▄ ▄?▄█? ?▄██? ?█▄
  ▄ █?█ ? ??▄▄▄▄▄ ? ▄?▄██  █ ▄▄█?█?█ ▄█
  █?▄ ???███▄ █?▄ ?██▄ █  ▄?▄ ? █▄ █▄?█
  █▄  ? ??? ▄?█▄  █▄?▄█▄▄█▄█ ▄ ?█  ?  ?
  █▄?   ??█?█▄ ▄▄?   ?███▄█▄▄?▄?? ▄▄  ▄
  ▄? █??? ██ ▄█ █▄▄█ ▄ ██ ??█  ███?███?
    ▄▄?????█??█?█ █   █? ?▄??█▄▄█??  ▄█
  █▄▄▄▄??██▄▄▄██?▄▄ ▄██▄▄▄███▄▄▄█▄██ █?
    ?█  ?█  ?▄██   █ ▄▄██  ?   ██▄ █▄?█
  ?▄ ▄▄▄?  ?█??▄█ ██▄▄▄▄▄??▄▄ █▄  ?   ?
  ?? ? ???▄▄█▄ ▄▄?▄?▄? █▄▄  ▄██???█  ?█
  █?????█ ?█▄▄▄ ▄▄▄█? ██?▄▄? ?█ ? █▄▄??
  █ ███ █ ▄?????? █▄  █▄ ??██ ???█?  █▄
  █ ??? █ ▄▄? █▄▄▄ ?███▄?  █▄█▄ ▄▄?█ ??
  ??????? ? ?  ? ??? ???  ?? ???? ?? ??
        

7.3.1. Request parameters

• response_mode: MUST be set to none.
• client_id: MUST be the DID of the payee.

7.3.2. Request Object

The request object must be signed by the payee. The JWS SHOULD include or reference a certificate, which allows the wallet to verify that the request was issued by a trustworthy source.

7.3.3. Presentation definition

The presentation_definition of the authorization request is used by the payee to communicate to the wallet which payment credentials and thereby which means of payments it supports.

Example of the presentation_definition. Thereby the merchant requests the wallet to display all credentials of the type PaymentKey as viable options to sign the request. In a more complex scenario the presentation_definiton might be used to filter for more specific payment credentials which might only support a certain scheme e.g..

{
  "presentation_definition": {
    "id": "32f54163-7166-48f1-93d8-ff217bdb0653",
    "input_descriptors": [
      {
        "id": "payment_keys",
        "constraints": {
          "fields": [
            {
              "path": [
                "$.type"
              ],
              "filter": {
                "type": "string",
                "pattern": "PaymentKey"
              }
            }
          ]
        }
      }
    ]
  }
}

        

8. Authorisation response

The authorization response must be a POST request as defined in Section 7 of [OPENID4VP.xsr]

8.1. VP Token

The authorization response returned from the wallet to the bank MUST include a verifiable presentation encoded as JWT as defined in Section 6.3.1 of [VCDATA] in the vp_token. The proof of the verifiable presentation MUST be signed using the same key the payment order was signed with. The verfiable presentation MUST include the requested payment order credential and MAY contain additional credentials if requested by the bank in the presentation_definition given in the payment credential.

8.2. Optional enrichment

In a case where the bank might need to modify the payment order (to include additional fees for example), the response to the direct POST might be a redirect to another authorization request initializing the flow described in [OPENID4VP.sr]

9. Normative References

[DID.CORE]

Sporny, M., Longley, D., Sabadello, M., Reed, D., Steele, O., and C. Allen, "Decentralized Identifiers (DIDs) v1.0", <https://www.w3.org/TR/did-core/>.

[DIF.PresentationExchange]

Buchner, D., Zundel, B., Riedel, M., and K.H. Duffy, "Presentation Exchange 2.0.0", <https://identity.foundation/presentation-exchange/spec/v2.0.0/>.

[JWK.DID]

Miller, J., "DID JWK Method Specification", <https://github.com/quartzjer/did-jwk>.

[OPENID4VC]

Lodderstedt, T., Yasuda, K., and T. Looker, "OpenID for Verifiable Credential Issuance", 3 February 2023, <https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html>.

[OPENID4VP]

Lodderstedt, T., Terbu, O., Yasuda, K., Lemmon, A., and T. Looker, "OpenID for Verifiable Presentations", 20 June 2022, <https://openid.net/specs/openid-4-verifiable-presentations-1_0.html>.

[OPENID4VP.sr]

Andreae, F., Khan, R., and A. Schubert, "Request to sign based on OpenID4VP", <https://digitallabor.berlin/draft-openid4vp-r2s.html>.

[OPENID4VP.xsr]

Andreae, F., Khan, R., and A. Schubert, "Extended Request to sign based on OpenID4VP", <https://digitallabor.berlin/draft-openid4vp-xr2s.html>.

[PAYMENTDATA]

Berlin Group, "Payment Data Model Version 2", 24 September 2021, <https://www.berlin-group.org/_files/ugd/c2914b_f8cab18ec71e476a9685c9a5f5260fda.pdf>.

[RFC9101]

Sakimura, N., Bradley, J., and M. Jones, "The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR)", RFC 9101, DOI 10.17487/RFC9101, August 2021, <https://www.rfc-editor.org/info/rfc9101>.

[VCDATA]

W3C, "Verifiable Credentials Data Model 1.1", 20 June 2022, <https://www.w3.org/TR/2022/REC-vc-data-model-20220303>.

Author's Address

Florian Andreae

DSGV