Copyright Notice: this document is furnished under an MIT license.
.
Compared to EMV, Saturn introduces several enhancements:
Saturn builds on the idea that different payment networks should not need unique user authorizations solutions; only identifiers related to accounts and payment networks need to be adapted. This data is provided in the associated payment credentials (virtual payment cards), potentially making the wallet software universal.
Saturn is also intended to serve as a candidate for the payment authorization part of the EU Identity Wallet [EUIDW].
The Saturn protocol is based on CBOR [RFC8949] which is a binary interchange format.
However, for documentation purposes, messages are shown in diagnostic notation.
map objects,
Saturn relies on an IETF standard currently in development [CDE],
which defines deterministic encoding of CBOR.
.
Payer hits a "Pay"
button on the Web or scans a QR-code, returning a Wallet activation URL.
The Wallet should then use the received URL for performing an HTTP GET
(step #1 in the Sequence Diagram) to the Payee service.
This operation should return an Authorization Request object
(step #2 in the Sequence Diagram) like the following:
Payee service must set the
HTTP Content-Type header parameter
to application/cbor.
Wallet should display a UI like the following:
Payee
request, the Payer needs
to select (step #3 in the Sequence Diagram) a suitable
credential, unless the default (or last used) credential already meets
the preferences of the Payer.
If there are no matching payment credentials, the Wallet
must provide the Payer with
a suitable error message and a cancel button.
If the requested currency differs from the default (as defined by the
locale settings of the operating system), it is recommended displaying
ISO three-letter abbreviations (USD, EUR, SEK, etc.) rather than short-hand
versions like '$' and '€'.
See also Payment Request.
Payer accepts and subsequently authorizes
the request (step #4 in the Sequence Diagram) using a biometric operation or PIN,
the Wallet should perform an HTTP POST
(step #5 in the Sequence Diagram)
to the Payee service containing an
Authorization Response
object like the following:
Content-Type
header parameter must be set to application/cbor.
Payee
includes this object in a payment-network-specific request to the designated
Payment Network
(provided by the selected payment credential).
Note that this phase may constitute of multiple request-response pairs.
Wallet termination
message (step #6 in the Sequence Diagram).
This message depends on how the payment process was initiated,
and is currently TBD.
map objects.
| Name | Label | Type | Description |
|---|---|---|---|
| paymentRequest | 1 | map | The core object, Payment Request. |
| supportedNetworks | 2 | array | Non-empty list of payment network/method identifiers that the Payee supports. Network identifiers are expressed as CBOR strings (tstr).See also networkId in the Credential Database. |
| receiptUrl | 3 | tstr | Optional: URL to a Payee receipt service.See also RECEIPTS . |
Payee to Wallet message. In same-device Web contexts this message is also associated with the invocation of the Wallet.
| Name | Label | Type | Description |
|---|---|---|---|
| commonName | 1 | tstr | Payee common name to be shown in the Wallet Request UINote that common and legal names often differ. |
| referenceId | 2 | tstr | Payee reference Id. Reference Ids must be unique with respect to the Payee. |
| amount | 3 | tstr | Monetary amount compatible with the regular expression: ^(0|[1-9][0-9]*)(\.[0-9]+)?$. Amounts must not use more decimals than is custom for prices for the specific currency. |
| currency | 4 | tstr | Currency expressed in the ISO4217 alphabetical format. |
| nonDirect | 5 | map | Optional: Also see Non-direct Payments. |
object, where the outermost element is a COTX wrapper as follows:1010(["https://saturn.standard/v4", {
}])map keys are as follows:| Name | Label | Type | Description |
|---|---|---|---|
| customData | 0 | map | CEF custom (unencrypted) data in the form of a copy of the "Pass Through" Data object fetched from the Signed Authorization object. |
| algorithm | 1 | int | Copy of the encContentAlg attribute of the selected payment credential in the Credential Database. |
| keyEncryption | 2 | map | Holds the CEF Key Encryption object. |
| tag | 8 | bstr | Encryption algorithm tag. |
| iv | 9 | bstr | Encryption algorithm initialization vector (IV). |
| cipherText | 10 | bstr | Encrypted data containing a version of the Signed Authorization object where the "Pass Through" Data object has been removed after the completed authorization signature process. Note that the modified Signed Authorization map object must be updated (before being encrypted), to reflect the removal of the "Pass Through" Data object. |
| Name | Label | Type | Description |
|---|---|---|---|
| algorithm | 1 | int | Copy of the encKeyAlg attribute of the selected payment credential in the Credential Database. |
| keyId | 3 | "Any" | Optional: Copy of the encKeyId attribute of the selected payment credential in the Credential Database. |
| publicKey | 4 | map | Optional: Copy of the encPublicKey object of the selected payment credential in the Credential Database. Note that keyId and publicKey are mutually exclusive. |
| ephemeralKey | 7 | map | Ephemeral ECDH public key. |
| cipherText | 10 | bstr | Optional: Encrypted key for key wrapping algorithms. |
| Name | Label | Type | Description |
|---|---|---|---|
| paymentRequest | 1 | map | Through the inclusion of a copy of the Payment Request in the Payer authorization, this object remains authoritative throughout the payment process (except for interbank operations). |
| providerData | 2 | map | Holds the Provider Data required by the Payee for deriving which payment network to use and how to initiate a compatible payment transaction request. |
| Name | Label | Type | Description |
|---|---|---|---|
| networkId | 1 | tstr | Copy of the same attribute of the selected payment credential. Also see Credential Database. |
| serviceLocator | 2 | tstr | Copy of the same attribute of the selected payment credential. Also see Credential Database. |
| Name | Label | Type | Description |
|---|---|---|---|
| passThroughData | 1 | map | Holds the "Pass Through" Data object. |
| payeeHost | 2 | tstr | Host name or IP address of the invoking Payee, derived from step #1 in the sequence diagram. |
| accountId | 3 | tstr | Copy of the same attribute of the selected payment credential. Also see Credential Database. |
| serialNumber | 4 | tstr | Copy of the same attribute of the selected payment credential. Also see Credential Database. |
| platformData | 5 | array | Array holding the name and version of the operating system in [0] and [1] respectively, expressed as CBOR strings (tstr). |
| walletData | 6 | array | Array holding the name and version of the Wallet software in [0] and [1] respectively, expressed as CBOR strings (tstr). |
| location | 7 | array | Optional: Array holding the current latitude [0] and longitude [1] of the Wallet device, expressed as CBOR floating point values.This option depends on Payer privacy settings. |
| timeStamp | 8 | tstr | ISO date-time string [RFC3339] using UTC (T) or local time (Z) format. |
| authzSignature | -1 | map | Authorization signature using a CSF object. |
Wallet is a local database holding
enrolled payment credentials.
Note that although credential data types listed here are mainly expressed as CBOR,
other representations may be used.
The only requirement is that credential data types can be securely
mapped back and forth to CBOR.
The data type "ps" denotes a platform-specific solution.
Each entry in the database contains a payment credential according to the following definition:
| Name | Type | Description |
|---|---|---|
| version | tstr | Since credential data may evolve over time, versioning is necessary. This specification covers version: https://saturn.standard/cr/v1. |
| networkId | tstr | Payment network/method identifier. Since payment networks are likely to continue having unique message solutions, the Payee needs to identify the specific network before making a transaction request.Payment network identifiers may be expressed as URLs or as simple names like "VISA". Note that this concept does not make a distinction between payment methods or "schemes". Also see Provider Data. |
| serviceLocator | tstr | Payment service URL or host name. This attribute enables the Payee to find the end-point of the specific payment service (like a bank), associated with the payment credential.How to interpret this attribute is dictated by the networkId identifier. If serviceLocator is expressed as a host-name only, a ".well-known" [RFC8615] extension would typically be used.Also see Provider Data. |
| accountId | tstr | Account identifier associated with the payment credential. Also see Signed Authorization. |
| serialNumber | tstr | Serial number of the payment credential. Also see Signed Authorization. |
| cardImage | bstr | Card image associated with the payment credential. Card images are used for aiding Payer administration of payment credentials as well as being featured in the Wallet Request UI. Card images must be in SVG format and tentatively having a size of 300×180 pixels. |
| authzAlg | int | COSE signature algorithm to use for creating Signed Authorization objects. |
| authzKeyHandle | "ps" | Local handle to the private key to use for creating Signed Authorization objects. |
| authzPublicKey | "ps" | Authorization public key for inclusion in Signed Authorization objects. |
| encContentAlg | int | COSE content encryption algorithm to use for creating Authorization Response objects. |
| encKeyAlg | int | COSE key encryption algorithm to use for creating Authorization Response objects. |
| encPublicKey | "ps" | Encryption public key to use for creating Authorization Response objects. Note that encPublicKey objects are provided by credential issuers. In order to serve their primary purpose, preserving privacy, encPublicKey objects must be shared by multiple clients. |
| encKeyId | "Any" | Optional: If the encKeyId attribute is defined, it must be featured in Key Encryption objects instead of encPublicKey. |
publicKey or keyId attribute.
In the sample, a publicKey attribute was used.
Note that enclosing COTX object must be included in
the decryption process.
1 of the second object.
Note that the length of the resulting map object
must be updated to reflect the addition of an item.
This operation effectively recreates the Signed Authorization object:
publicKey
attribute, it can be validated using "as is".
Note that the authenticity of received public keys must be verified before authorization objects are acted upon!
Unsurprisingly, authorization objects must also be checked for alignment with the specification. Missing, additional, or malformed elements must be rejected.
Payer
authorization is followed by one
or more operations performed by the Payee,
usually without further intervention by the Payer.
Here we find gas-station payments,
subscriptions, BNPL (Buy Now Pay Later), and deposits.
Non-direct payments typically involve
reservation of funds. Subscriptions and BNPL may also be subject
to Payer credit considerations.
Although this specification only defines a single non-direct payment scenario, this is intended to serve as a model for additional variants as well.
Payer for the actual cost of the fill-up.
Note that a valid receipt (step #7 in the Sequence Diagram) can only
be made available after the second phase has been executed.
All non-direct payment profiles must feature a nonDirPayId entry (label 1) holding a unique identifier in the form of a URL. This entry may be followed by other, profile-specific elements required for describing the operation at hand. Below is the gas station payment profile:
| Name | Label | Type | Description |
|---|---|---|---|
| nonDirPayId | 1 | tstr | Unique Id: https://saturn.standard/ndp/gs1 |
| timeOut | 2 | int | Number of hours (1-24) the reservation will remain valid before being automatically revoked by the account-holding entity. It is recommended to have a margin of at least 15 minutes. |
Wallet UI should also reflect such requests in
a meaningful way.
For gas station payments, the following appears like a suitable solution:
/CSF support, the Payer Authorization sample
should be possible to decrypt and validate, using the following sample keys.
anders.rundgren.net@gmail.com)