RFC 3867
Payment Application Programmers Interface (API) for v1.0 Internet Open Trading Protocol (IOTP)
RFC 3867 — Payment API for IOTP v1.0 🎀
Okay bestie, let's start with the basics ✨ This is RFC 3867, and it's called Payment Application Programmers Interface (API) for v1.0 Internet Open Trading Protocol (IOTP). It was written by Y. Kawatsura (Hitachi), M. Hiroya (Technoinfo Service), and H. Beykirch (Atos Origin). The category is Informational, and the date is November 2004. The header doesn't list anything it obsoletes or updates, so no drama there 💅
Status of this Memo 📋
This memo gives information to the Internet community. It is not a specification of an Internet standard of any kind, so nobody's gonna get in trouble for not following it 🙈 Distribution of this memo is unlimited, so share it with everyone 🌈
Copyright Notice ⚖️
Copyright (C) The Internet Society (2004).
Abstract 🦋
The Internet Open Trading Protocol (IOTP) gives you a data exchange format for trading, and it integrates existing pure payment protocols seamlessly. That's why the architecture is layered. There's at least some generic IOTP application core, plus multiple specific payment modules, all working together like a little squad 👑
This document covers a common interface between the IOTP application core and the payment modules, so those modules can actually interoperate with each other. Bonus: that interface lays the groundwork for a plug-in mechanism in real IOTP application cores 🔌
These interfaces show up at the Consumers', the Merchants' and the Payment Handlers' installations. They connect the IOTP application core to the payment software components and legacy systems 🫶
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. General payment phases . . . . . . . . . . . . . . . . . 5
1.2. Assumptions. . . . . . . . . . . . . . . . . . . . . . . 6
2. Message Flow . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1. Authentication Documentation Exchange. . . . . . . . . . 15
2.2. Brand Compilation. . . . . . . . . . . . . . . . . . . . 17
2.3. Brand Selection. . . . . . . . . . . . . . . . . . . . . 21
2.4. Successful Payment . . . . . . . . . . . . . . . . . . . 24
2.5. Payment Inquiry. . . . . . . . . . . . . . . . . . . . . 29
2.6. Abnormal Transaction Processing. . . . . . . . . . . . . 30
2.6.1. Failures and Cancellations . . . . . . . . . . . 30
2.6.2. Resumption . . . . . . . . . . . . . . . . . . . 32
2.7. IOTP Wallet Initialization . . . . . . . . . . . . . . . 33
2.8. Payment Software Management. . . . . . . . . . . . . . . 34
3. Mutuality. . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.1. Error Codes. . . . . . . . . . . . . . . . . . . . . . . 38
3.2. Attributes and Elements. . . . . . . . . . . . . . . . . 48
3.3. Process States . . . . . . . . . . . . . . . . . . . . . 61
3.3.1. Merchant . . . . . . . . . . . . . . . . . . . . 61
3.3.2. Consumer . . . . . . . . . . . . . . . . . . . . 63
3.3.3. Payment Handler. . . . . . . . . . . . . . . . . 65
4. Payment API Calls. . . . . . . . . . . . . . . . . . . . . . . 66
4.1. Brand Compilation Related API Calls. . . . . . . . . . . 66
4.1.1. Find Accepted Payment Brand. . . . . . . . . . . 66
4.1.2. Find Accepted Payment Protocol . . . . . . . . . 68
4.1.3. Get Payment Initialization Data. . . . . . . . . 70
4.1.4. Inquire Authentication Challenge . . . . . . . . 72
4.1.5. Authenticate . . . . . . . . . . . . . . . . . . 73
4.1.6. Check Authentication Response. . . . . . . . . . 74
4.2. Brand Selection Related API Calls. . . . . . . . . . . . 76
4.2.1. Find Payment Instrument. . . . . . . . . . . . . 76
4.2.2. Check Payment Possibility. . . . . . . . . . . . 78
4.3. Payment Transaction Related API calls. . . . . . . . . . 80
4.3.1. Start Payment Consumer . . . . . . . . . . . . . 80
4.3.2. Start Payment Payment Handler. . . . . . . . . . 82
4.3.3. Resume Payment Consumer. . . . . . . . . . . . . 84
4.3.4. Resume Payment Payment Handler . . . . . . . . . 85
4.3.5. Continue Process . . . . . . . . . . . . . . . . 86
4.3.6. Change Process State . . . . . . . . . . . . . . 88
4.4. General Inquiry API Calls. . . . . . . . . . . . . . . . 89
4.4.1. Remove Payment Log . . . . . . . . . . . . . . . 90
4.4.2. Payment Instrument Inquiry . . . . . . . . . . . 90
4.4.3. Inquire Pending Payment. . . . . . . . . . . . . 92
4.5. Payment Related Inquiry API Calls. . . . . . . . . . . . 93
4.5.1. Check Payment Receipt. . . . . . . . . . . . . . 93
4.5.2. Expand Payment Receipt . . . . . . . . . . . . . 94
4.5.3. Inquire Process State. . . . . . . . . . . . . . 96
4.5.4. Start Payment Inquiry. . . . . . . . . . . . . . 97
4.5.5. Inquire Payment Status . . . . . . . . . . . . . 98
4.6. Other API Calls. . . . . . . . . . . . . . . . . . . . . 99
4.6.1. Manage Payment Software. . . . . . . . . . . . . 99
5. Call Back Function . . . . . . . . . . . . . . . . . . . . . .101
6. Security Considerations. . . . . . . . . . . . . . . . . . . .103
7. References . . . . . . . . . . . . . . . . . . . . . . . . . .103
7.1. Normative References . . . . . . . . . . . . . . . . . .103
7.2. Informative References . . . . . . . . . . . . . . . . .104
Acknowledgement. . . . . . . . . . . . . . . . . . . . . . . . . .105
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . .105
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . .1061. Introduction 🌸
Common network technologies are built on standardized and established Internet technologies. Those Internet technologies give you mechanisms and tools for presentation, application development, network infrastructure, security, and basic data exchange 💻
Here's the thing: trading roles already have systems with their own interfaces, like Internet shops, order management, payment, billing, and delivery management systems, or a financial institute's legacy systems. So IOTP has been limited to the common external interface over the Internet. However, some of these internal interfaces might also be standardized, so IOTP-aware components integrate better with existing infrastructure and can be reused cost-effectively 🧚 For more information on IOTP, see [IOTP] and [IOTPBOOK].
The typical Payment Handlers (i.e., financial institutes or near-bank organizations) and Merchants both need an IOTP-aware application that easily fits into their existing financial infrastructure. A Payment Handler might even insist on reusing special in-house solutions for some subtasks of the IOTP-aware application, e.g., their cryptography modules, gateway interfaces, or physical environment. So their IOTP-aware implementation really requires clear internal interfaces 🔐
Consumers are a big deal here too, and they demand modularization and clear internal interfaces ✨ Their IOTP application aims to support multiple payment methods. Consumers prefer flexibly using different seamlessly integrating payment methods within one trading application, with nearly identical behavior and user interface. A well-defined interface lets payment software developers bolt their components onto other developers' general IOTP Application Core 🍓
So this consideration leads to a two-level layered view of the IOTP software for each role, consisting of:
- some generic IOTP system component, the so-called IOTP application core - providing IOTP based gateway services and generic business logic, and
- the trading roles' specific back-end systems implementing the specific trading transaction types' functionality.
To isolate the changes on the infrastructure, the IOTP trading application has been three-layered 🦋
- the IOTP Application Core processes the generic parts of the IOTP transaction and holds the connection to the Internet,
- the Existing Legacy System or Existing Payment Software processes the actual transaction type, and particular payment transaction, and
- the IOTP Middle-ware or IOTP Payment Bridge glues the other two possibly incompatible components together. It brokers between the specific interface of the Existing Legacy System and the standardized interfaces of the IOTP Application Core.
As IOTP extends payment schemes to a trading scheme, this document primarily focuses on payment modules, i.e., the interface between the IOTP Payment Bridge and the IOTP Application Core. It provides a standard method for exchanging payment protocol messages between the parties involved in a payment. But it does not specify any interface for order or delivery processing 🙅♀️
Such a Payment Application Programmers Interface (API) must suit a broad range of payment methods: (1) software based, like Credit Card SET or CyberCoin, (2) chip card based, like Mondex or GeldKarte, and (3) mimicries of typical and traditional payment methods, like money transfer, direct debit, deposit, withdrawal, money exchange, and value points. It should support both payments with explicit consumer acknowledgement and automatic repeated payments that have been consumer approved in advance. For more information on SET, see [SET] 💸
The following discussion focuses on the Consumer's point of view and uses the associated terminology. When switching to Merchants' or Delivery Handlers' IOTP-aware applications, the payment related components should be implicitly renamed by Existing Legacy Systems to the IOTP Middle-ware 🎀
The next two sub-sections describe the general payment scenario and several assumptions about the coarsely sketched software components.
Section 2 illustrates the payment transaction progress and message flow of different kinds of transaction behavior. Sections 3 to 4 provide the details of the API functions, and Section 5 elaborates the call back interface 🌈
1.1. General payment phases 💖
okay so this table is basically the four-step glow-up that a ton of payment schemes go through 🧚 It skips the stuff you already agreed on, like the goods, the payment method, the purchase amount, and the delivery rules 📦
Payment State Party Example Behavior
------------- ----- ----------------
Mutual Payment Handler Generation of identification
Authentication request, solvency request, or
and some nonce
Initialization Consumer Responses to the requests and
generation of own nonce
Authorization Payment Handler Generation of the authorization
request (for consumer)
Consumer Agreement to payment (by
reservation of the Consumer's
e-money)
Payment Handler Acceptance or rejection of the
agreement (consumer's
authorization response),
generation of the authorization
request (for issuer/acquirer),
and processing of its response
Capture Generation of the capture
request (for issuer/acquirer)
Consumer Is charged
Payment Handler Acceptance or rejection of the
e-money, close of the payment
transaction
Reversal On rejection (online/delayed):
generation of the reversal data
Consumer Receipt of the refundBut ngl, some payment schemes do things a little differently 🙈 They:
- limit themselves to one-sided authentication,
- perform off-line authorization without any referral to any issuer/acquirer,
- apply capture processing in batch mode, or
- do not distinguish between authorization and capture,
- lack an inbound mechanism for reversals or implement a limited variant.
And here's the kicker: this model isn't just for typical point-of-sale payments 💅 It stretches to refunds, deposits, withdrawals, electronic cheques, direct debits, and money transfers too ✨
1.2. Assumptions 🎀
In outline, the IOTP Payment Bridge handles some input sequence of payment protocol messages that the IOTP Application Core forwards to it 🦋 It (1) takes the messages apart, (2) maps them onto the formats of the Existing Payment Software, (3) puts its responses together, and (4) hands back another sequence of payment protocol messages, which the IOTP Application Core mostly just passes along transparently to some IOTP aware remote party. Normally this keeps going between the two parties until the Payment Handler's Payment API signals the payment termination. Every now and then, though, any system component might signal a failure 😭
The components are all connected in a flexible n-to-m-manner, and the figure below shows how they fit together 🌈
- One IOTP Application Core may manage multiple IOTP Payment Bridges, and the latter might be shared between multiple IOTP Application Cores.
- Each Payment Bridge may manage multiple Existing Payment Software modules, and the latter might be shared between multiple Payment Bridges.
- Each Existing Payment Software may manage multiple payment schemes (e.g., SET), and the latter might be supported by multiple Existing Payment Software modules. For more information on SET see [SET].
- Each payment scheme may support multiple payment instruments (e.g., particular card) or methods (e.g., Visa via SET), and the latter might be shared by multiple Existing Payment Software Components.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP client (consumer) <---------------> IOTP server (merchant)
( contains Internet ( contains
IOTP Application Core) IOTP Application Core)
^ ^
| IOTP Payment | IOTP Payment
| API | API
v v
IOTP Payment Bridge IOTP Payment Bridge
^ ^
| Existing Payment APIs, e.g., |
| SET, Mondex, etc. |
v v
Existing Payment Software Existing Payment Software
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 1: Relationship of the Components
The Payment API considers these transaction types of Baseline IOTP 👑:
- Baseline Purchase,
- Baseline Refund,
- Baseline Value Exchange,
- Baseline Withdrawal, and
- Baseline (Payment) Inquiry.
For more information on Baseline IOTP, see [IOTP] and [IOTPBOOK] 📚
First, let's clarify the authors' vision for the IOTP aware application and its main components 💜 On the one hand, the Payment API should be quite powerful and flexible so the generic and specific components can connect properly. On the other hand, the Payment API should not get overloaded with nice-to-haves that Existing Payment Software doesn't support. Protective of its space, it is 🙅♀️
Successful payments look super similar across schemes, but failure resolution and inquiry capabilities differ extremely between payment schemes 💀 These aspects may even vary between different payment instruments using the same payment scheme. On top of that, the specific requirements of Consumers, Merchants, and Payment Handlers add variance and complexity. So the plan is that the IOTP Application Core provides only very basic inquiry mechanisms, while complex and payment scheme specific inquiries, failure analysis, and failure resolution are fully deferred to the actual Existing Payment Software, including its user interface 🫶
The IOTP Application Core processes payments transparently. That means it forwards the wrapped payment scheme specific messages to the associated IOTP Payment Bridge and Existing Payment Software. The Existing Payment Software might even use these messages for inbound failure resolution. It reports only the final payment status to the IOTP Application Core, or some intermediate status (which might also be final) when the process gets abnormally interrupted 🌸
The IOTP Application Core handles the generic, payment scheme independent part of IOTP transaction processing and provides the suitable user interface ✨ When it comes to payment related tasks, it:
- manages the registered IOTP Payment Bridges and provides a mechanism for their registration; the latter is omitted by this document.
- assumes that any IOTP Payment Bridge is a passive component, i.e., it strictly awaits input data and generates one response to each request,
- supports the payment negotiation (Consumer: selection of the actual payment instrument or method; Merchant: selection of the payment methods being offered to the Consumer) preceding the payment request,
- requests additional payment specific support from the Existing Payment Software via the selected and registered the IOTP Payment Bridge,
- initializes and terminates the Existing Payment Software via the IOTP Payment Bridge,
- inquires authentication data (for subsequent request or response) from the Existing Payment Software, specific authentication component (omitted in this document), or Consumer (by a suitable user interface),
- supervises the online transaction process and traces its progress,
- stores the transaction data being exchanged over the IOTP wire; payment scheme specific data is handled transparently,
- relates each payment transaction with multiple payment parameters (IOTP Transaction Identifier, Trading Protocol Options, Payment Instrument/Method, Offer Response, IOTP Payment Bridge, and Wallet Identifier, associated remote Parties). The relation might be lowered to the party's Payment Identifier, IOTP Payment Bridge, Wallet Identifier, and the remote parties when the actual payment transaction has been successfully started.
- implements a payment transaction progress indicator,
- enables the inquiry of pending and completed payment transactions,
- implements generic dialogs, e.g., brand selection, payment acknowledge, payment suspension / cancellation, receipt visualization, basic transaction inquiry, balance inquiry, or receipt validation,
- defers payment specific processing, supervision, validation, and error resolution to the Existing Payment Software. It is expected that the Existing Payment Software will try to resolve many errors first by the extended exchange of Payment Exchange messages. The most significant and visible failures arise from sudden unavailability or lapses of the local or opposing payment component.
- supports the invocation of any Existing Payment Software in an interactive mode, which might be used (1) for the payment scheme specific post-processing of a (set of) payment transactions, (2) for the analysis of a payment instrument, (3) for the registration of a new payment instrument/scheme, or (4) for re-configuration of a payment instrument/scheme.
- exports call back functions for use by the IOTP Payment Bridge or Existing Payment Software for progress indication.
On top of all that, the IOTP Application Core also:
- manages the IOTP message components and IOTP message blocks exchanged during the transaction, which may be referenced and accessed during the processing of subsequent messages, e.g., for signature verification. In particular, it stores named Packaged Content elements exchanged during payments.
- manages several kinds of identifiers, i.e., transaction, message, component, and block identifiers,
- implements a message caching mechanism,
- detects time-outs at the protocol and API level, reflecting the communication with both the IOTP aware remote party and the Payment API aware local periphery; e.g., a chip card (reader) may raise time-outs.
However, the IOTP Payment Bridge and Existing Payment Software do not have to rely on all of these IOTP Application Core capabilities 🙌 E.g., some Consumer's Existing Payment Software may refuse the disclosure of specific payment instruments at brand selection time and may delay this selection to the "Check Payment Possibility" invocation using its own user interface.
The IOTP Payment Bridge's capabilities don't only cover actual payments between the Consumer and the Payment Handler. They also extend to the following:
- translation and (dis)assemblage of messages between the formats of the IOTP Payment API and those of the Existing Payment Software. Payment API requests and response are strictly 1-to-1 related. 🦋
Okay bestie, the Existing Payment Software is basically a whole sidekick with its own vibe 💅✨, and its capabilities are all over the place 🌈. So here's where we pick up, and yes, the sentence really does just trail off into a list 😭
- Consumer's payment instrument selection 🎀 happens through an unsecured/public export of how payment brands, payment protocols, and payment instruments (identifiers) relate to each other 🦋. Usually that covers not just the brand (Mondex, GeldKarte, etc.) but also which specific instance of the instrument and which currency to use. Like, which exact Mondex card, and which currency out of all the ones available 💖.
Some Existing Payment Software is more chill, though 🧚. It might push the instrument selection until the actual payment is being carried out, or it might not manage payment instruments at all. For example, chip card based payment methods can do a Point of Sale style implicit selection, where you just slide the chip card into the reader 💳. Or the reader checks the inserted card and asks you to acknowledge (or select) the instrument(s) it found 👑.
- Payment progress checks 🌸, like whether there's enough money for the purchase, or enough left over for a refund 💅.
- IOTP Payment Receipt checks 🧾, which might run over its Packaged Content or happen some other way ✨.
- Recoding of payment scheme specific receipts 🍓 into a format that can be shown to the user or printed 🖨️.
- Cancellation of a payment 🙈, even if it isn't finished yet 💀.
- Suspension and resumption of payment transactions ⏸️. There are two kinds of failure the Existing Payment Software might have to handle: (1) the network connection times out, and (2) there isn't enough money 😭. To sort these out, the IOTP Application Core might try suspending the payment so it can resume it later 🦋.
- Recording the payment progress and status in a database 📚. For instance, info about pending payments can help continue them when the next payment protocol message shows up 💜.
- Payment transaction status inquiry 🔍, so the inquirer (the IOTP Application Core or the User) can figure out the right next step 🫶.
- Balance inquiry or transaction history 💰. Consumers might check their chip card based payment instrument, or manage some account remotely, before acknowledging a payment transaction 🌈.
- Inquiry on abnormal interrupted payment transactions 🌩️. The IOTP Application Core can use this to clean up pending transactions at startup, like after a power failure ⚡.
- Payment progress indication ⭐. This can tell the end user what's happening with the payment 👀.
- Payment method specific authentication methods 🔐.
The Existing Payment Software might not fully support all of this 🥲. For example, some payment schemes might not support explicit transaction cancellation at every phase of the payment process, or might even block it 🚫. In that case, the IOTP Payment Bridge has to implement at least skeletons that signal the lack of support by using specific error codes (see below) 🙅♀️.
Existing Payment Software's capabilities vary extremely, so it:
- Supports payment scheme specific processing, supervision, validation, and error resolution 🧠. Many errors are expected to be resolved first by extending the exchange of Payment Exchange messages 💬.
- Provides hints for out-of-band failure resolution 🗺️ when inbound resolution fails. Inbound resolution is invisible to the IOTP Application Core 🫥.
- May implement arbitrary transaction data management and inquiry mechanisms 🗂️. These range from no transaction recording, to last transaction recording, to chip card deferred transaction recording, to a simple transaction history, all the way up to sophisticated persistent data management with flexible user inquiry capabilities 🤩. The latter is required by Payment Handlers for easy and cost effective failure resolution 💎.
- Implements the payment scheme specific dialog boxes 🪟.
Even the generic dialog boxes of the IOTP Application Core might be unsuitable 🙃. Particular (business or scheme) rules might require a dedicated appearance, structure, or content for the dialog boxes 🎨. They might prohibit the unsecured export of payment instruments 🔒, or they might prescribe the pass phrase input under their own control 🔑.
2. Message Flow ✨
The following lists all functions of the IOTP Payment API 📋:
- Brand Compilation Related API Functions 🏷️
"Find Accepted Payment Brand" identifies the accepted payment brands for any indicated currency amount 💸.
"Find Accepted Payment Protocol" identifies the accepted payment protocols for any indicated currency amount (and brand), and returns payment scheme specific packaged content for brand selection purposes 🎁.
This function might be used together with the aforementioned function, or called without any brand identifier 🤸.
"Get Payment Initialization Data" returns additional payment scheme specific packaged content for payment processing by the payment handler 📦.
"Inquire Authentication Challenge" returns the payment scheme specific authentication challenge value 🧩.
"Check Authentication Response" verifies the returned payment scheme specific authentication response value ✅.
"Change Process State" is used (here only) for abnormal termination (cf. Payment Processing Related API Functions) 🛑.
- Brand Selection Related API Functions 🎯
"Find Payment Instrument" identifies which instances of a payment instrument of a particular payment brand are available for use in a payment 💳.
"Check Payment Possibility" checks whether a specific payment instrument is able to perform a payment 🔍.
"Authenticate" forwards any payment scheme specific authentication data to the IOTP Payment Bridge for processing 🔐.
"Change Process State" is used (here only) for abnormal termination (cf. Payment Processing Related API Functions) 🛑.
- Payment Processing Related API Functions 🚀
"Start or Resume Payment Consumer/Payment Handler" initiate or resume a payment transaction. There are specific API functions for the two trading roles, Consumer and Payment Handler 🎬.
"Continue Process" forwards payment scheme specific data to the Existing Payment Software, and returns more payment scheme specific data for transmission to the counter party 🔁.
"Change Process State" changes the current status of payment transactions. Typically, this call is used for termination or suspension without success 🙅.
- General Inquiry API Functions 🔎
"Remove Payment Log" notifies the IOTP Payment Bridge that a particular entry has been removed from the Payment Log of the IOTP Application Core 🗑️.
"Payment Instrument Inquiry" retrieves the properties of Payment Instruments 📇.
"Inquire Pending Payment" reports any abnormal interrupted payment transaction known by the IOTP Payment Bridge 🕵️.
Payment Processing Related Inquiry API Functions 🧐
"Check Payment Receipt" checks the consistency and validity of IOTP Payment Receipts, received from the Payment Handler or returned by "Inquire Process State" API calls. Typically, the Consumer calls this function during the final processing of payment transactions. Still, this check might be helpful for both Consumers and Payment Handlers when resolving failures 🧾✨.
"Expand Payment Receipt" expands the Packaged Content of IOTP Payment Receipts, as well as payment scheme specific payment receipts, into a form that can be used for display or printing purposes 🖨️.
"Inquire Process State" responds with the payment state and the IOTP Payment Receipt Component. Normally, the Payment Handler calls this function for final processing of the payment transaction 🏁.
"Start Payment Inquiry" prepares the remote inquiry of the payment transaction status, and responds with payment scheme specific data that the Payment Handler might need for the Consumer initiated inquiry processing 📞.
"Inquire Payment Status" is called by the Payment Handler on Consumer initiated inquiry requests. This function returns the payment scheme specific content of the Inquiry Response Block 📬.
"Continue Process" and "Change Process State" (cf. Payment Processing Related API Calls) 🔄.
- Other API Functions 🧃
"Manage Payment Software" enables the immediate activation of the Existing Payment Software. Further user input is under control of the Existing Payment Software 🎛️.
"Call Back" provides a general interface for the visualization of transaction progress by the IOTP Application Core 📺.
The following table shows which API functions must (+), should (#), or might (?) be implemented by which Trading Roles 🗓️.
API function Consumer Payment Handler Merchant
------------ -------- --------------- --------
Find Accepted Payment Brand +
Find Accepted Payment Protocol #
Find Payment Instrument +
Get Payment Initialization Data +
Check Payment Possibility +
Start Payment Consumer +
Start Payment Payment Handler +
Resume Payment Consumer #
Resume Payment Payment Handler #
Continue Process + +
Inquire Process State + + ?
Change Process State + + ?
Check Payment Receipt + ?
Expand Payment Receipt # ?
Remove Payment Log ? ? ?
Inquire Authentication Challenge ?
Authenticate +
Check Authentication Response ?
Payment Instrument Inquiry ?
Inquire Pending Payment # #
Start Payment Inquiry ?
Inquire Payment Status ?
Manage Payment Software # ? ?
Call Back #
Table 1: Requirements on API Functions by the Trading RolesThe next sections sketch the relationships and dependencies between the API functions 🕸️. They give an informal description of the progress alternatives, and show how the general IOTP Application Core and the payment scheme specific modules communicate and stay in sync 🤝💕.
2.1. Authentication Documentation Exchange ✨
Okay bestie, this part is all about how the pieces of this spec team up to get authentication done 🫶. Here's the flow:
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Authenticator Inquire Authentication Challenge(Alg1*) -> IPB
Inq. Auth. Challenge Response(Alg1,Ch1) <- IPB
. . .
Inquire Authentication Challenge(Algn*) -> IPB
Inq. Auth. Challenge Response(Algn,Chn) <- IPB
Create and transmit Authentication Request Block
Authenticatee Authenticate(Alg1, Ch1) -> IPB
AuthenticateResponse(...) <- IPB
. . .
Authenticate(Algm, Chm) -> IPB
AuthenticateResponse(Res) <- IPB
Create and transmit Authentication Response Block
Authenticator Check Authentication Response(Algm,Chm,Res)->IPB
Check Auth. Response() <-IPB
Create and transmit Authentication Status Block
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 2. Authentication Message Flows 🦋
- (Authenticator Process) Zero, one, or several IOTP Payment Bridges (IPB) get asked for one or more authentication challenge values ("Inquire Authentication Challenge"). Each value gets wrapped up in an IOTP Authentication Request Component. The IOTP Application Core can also toss in payment scheme independent authentication methods 💅. All of that together becomes the final IOTP Authentication Request Block, which lays out the set of authentication methods the authenticator supports, and the Authenticatee has to pick one from it.
Quick note, bestie: the interface of the API function only lets you get the response for exactly one algorithm per call. If the IOTP Application Core hands over a choice of algorithms for input, that choice should get narrowed down successively by whichever algorithm gets returned ({Alg(i+1)*} is subset of {Algi*}) 🍓.
During the registration of new Payment Instruments, the IOTP Payment Bridge tells the IOTP Application Core which authentication algorithms it supports 🧚.
- When an IOTP Authentication Block shows up in the received IOTP message, the Authenticatee's IOTP Application Core checks whether the IOTP transaction type in the current phase actually supports the authentication process. It's giving gatekeeper energy 👑.
For each Authentication Request Component provided, the IOTP Application Core looks at the algorithms' names, the transaction context, and optionally user preferences. This helps it figure out which system components are capable of processing the authentication request items. Those might be the IOTP Application Core itself or any of the registered IOTP Payment Bridges 🌸.
Next, the IOTP Application Core requests the responses to the supplied challenges from the determined system components, in any order. The authentication trials stop with the first successful response, which gets included in the IOTP Authentication Response Block ✨.
Alternatively, the IOTP Application might ask for a user selection. This might be appropriate if two or more authentication algorithms come back that require explicit user interaction, like PIN or chip card insertion 🙈.
The Authenticatee's organizational data is requested by an IOTP Authentication Request Block without any content element. On failure, the authentication (sequence) might be retried, or the whole transaction might be suspended or cancelled 💀.
- (Authenticator Process) The IOTP Application Core checks for the presence of the IOTP Authentication Response Component in the Authentication Response Block. Then it forwards its content to the generator of the associated authentication challenge for verification ("Check Authentication Response") 🔥.
On a sole organizational data request, its presence is checked instead.
Any verification must succeed in order to proceed with the transaction. 🌈
2.2. Brand Compilation ✨
okay so this section is all about how the Merchant puts the payment goodies together 💅 It shows how the API functions work as a team so the Merchant can (1) compile the Brand List Component, (2) generate the Payment Component, and (3) adjust the Order Component with payment scheme specific packaged content. main character energy 🎀
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Merchant For each registered IOTP Payment Bridge
| Find Accepted Payment Brand() -> IPB
| Find Accepted Payment Brand Response (B*) <- IPB
| Find Accepted Payment Protocol(B1) -> IPB
| Find Accepted Payment Protocol Res.(P1*) <- IPB
| . . .
| Find Accepted Payment Protocol(Bn) -> IPB
| Find Accepted Payment Protocol Res.(Pn*) <- IPB
Create one Brand List Component, ideally sharing
common Brand, Protocol Amount, Currency Amount,
and Pay Protocol Elements
Create Trading Protocol Options Block
On brand independent transactions
| Create Brand Selection Component, implicitly
| Get Payment Initialization Data(B1,P1) -> IPB
| Get Payment Initialization Data Res.() <- IPB
| Optionally
| | Inquire Process State() -> IPB
| | Inquire Process State Response(State) <- IPB
| Create Offer Response Block
Transmit newly created Block(s)
Consumer Consumer selects Brand (Bi)/Currency/Protocol (Pj)
from those that will work and generates Brand
Selection Component - at least logically
On brand dependent transaction
| Transmit Brand Selection Component
Merchant On brand dependent transaction
| Get Payment Initialization Data(Bi,Pj) -> IPB
| Get Payment Initialization Data Res.() <- IPB
| Optionally
| | Inquire Process State() -> IPB
| | Inquire Process State Response(State) <- IPB
| Create Offer Response Block
| Transmit newly created Block
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 3. Brand Compilation Message Flows 🦋
- The Merchant's commerce server runs the shopping dialog with its own mechanisms until the Consumer checks out the shopping cart and shows their payment intention 🛒 The notion shopping covers any non-IOTP based visit of the Merchant Trading Role's (which covers Financial Institutes) web site, used to negotiate the content of the IOTP Order Component. Then the processing switches to the IOTP based form once the Merchant's IOTP aware application gets activated ✨
- The IOTP Application Core asks for the IOTP level trading parameters 🌸 (Consumer's shopping identifier, payment direction, initial currency amounts, discount rates, Merchant's and Delivery Handler's Net Locations, Non-Payment Handler's Organizational Data, initial order information, ....).
- The IOTP Application Core asks each registered IOTP Payment Bridge about the accepted payment brands ("Find Accepted Payment Brand"). Their answers give most of the attribute values for compiling the Brand List Component's Brand Elements. The IOTP Application Core might optionally match the returned payment brands with the Merchant's general preferences 🧚
The IOTP Application Core MUST provide any wallet identifiers, if the IOTP Payment Bridges need them. They signal that need with specific error codes (see below). Any signaled error that the IOTP Application Core couldn't immediately solve SHOULD be logged, and this also applies to the later API calls in this section 😭 When that happens, the IOTP Application Core creates an IOTP Error Block (hard error), sends it to the Consumer, and terminates the current transaction 💀
- The IOTP Application Core checks each IOTP Payment Bridge, for every accepted payment brand, about the payment protocols it supports ("Find Accepted Payment Protocol"). These answers fill in the rest of the Brand Elements' attribute values, plus all the attribute values for the Brand List Component's Protocol Amount and Pay Protocol Elements 💜
The organisational data about the Payment Handler comes back too. The IOTP Application Core might optionally match the returned payment brands with the Merchant's general preferences.
Or, plot twist 🙈 the IOTP Application Core can skip the "Find Accepted Payment Brands" calls (cf. Step 3) and make the "Find Accepted Payment Protocol" call without any Brand on the input parameter list. In that case, the IOTP Payment Bridge answers that call with the whole set of payment schemes supported, based on the other input parameters.
- Steps 3 and 4 get repeated during IOTP Value Exchange transactions. These steps are left out of the previous figure 🔁
- The IOTP Application Core compiles the Brand List Component(s) and the IOTP Trading Protocol Options Block. It is RECOMMENDED that the "equal" items returned by IOTP Payment Bridge function calls get shared, since the Brand List Component has extensive linking capabilities 🔗 However, the compilation MUST consider several aspects to prevent conflicts. Sharing detection might be textual matching (after normalization) 👑
- Packaged Content Elements contained in the Brand List Component (and the Payment and Order Components generated from it later) might be payment scheme specific and might depend on each other.
- Currently, IOTP lacks precise rules for the content of the Packaged Content Element. So transaction / brand / protocol / currency amount (in)dependent data might share the same Packaged Content Element, or might spread across multiple Packaged Content Elements 🌈
- The Consumer's IOTP Application Core passes the Packaged Content Elements along transparently to the IOTP Payment Bridges. Those bridges might not be able to handle payment scheme data of other payment schemes accurately 😬
The rules and mechanisms for how this could be done are out of the scope of this document. Also, this document doesn't define any further restriction to the IOTP specification 🫶
- The IOTP Application Core figures out whether the IOTP message can be enriched with an Offer Response Block. That's valid under these conditions:
- All payment alternatives share the attribute values and Packaged Content Elements of the Payment and Order Components generated afterwards.
- The data generated afterwards doesn't depend on any IOTP BrandSelInfo Elements that the consumer might report in the TPO Selection Block in the brand dependent variant.
If both conditions are met, the IOTP Application Core might ask the IOTP Payment Bridge for the remaining payment scheme specific payment initialization data ("Get Payment Initialization Data") and compile the IOTP Offer Response Block 🎀
Optionally, the IOTP Application Core might ask the IOTP Payment Bridge for the current process state and add the inferred order status to the IOTP Offer Response Block. Or the IOTP Application can work out the order status on its own 💅
Just like in step 6, the rules and mechanisms for how this could be done are out of the scope of this document.
- The IOTP Application Core compiles the IOTP TPO Message, including all compiled IOTP Blocks, and sends the message to the Consumer 📨 The IOTP Application Core terminates if an IOTP Offer Response Block has been created.
- The Consumer performs the Brand Selection Steps (cf. Section 2.3) and replies with a TPO Selection Block if no IOTP Offer Response Block has been received. Otherwise, the following step gets skipped 🦋
- On brand dependent transactions, the IOTP Application Core asks the IOTP Payment Bridge for the remaining payment scheme specific payment initialization data ("Get Payment Initialization Data"), compiles the IOTP Offer Response Block, sends it to the Consumer, and terminates 🌸 Like Step 7, the IOTP Application Core might access the current process state of the IOTP Payment Bridge to compile the order status.
Any error during this process raises an IOTP Error Block. 🚨 no cap, don't skip this one bestie
Okay that's the whole brand compilation glow-up! ✨
2.3. Brand Selection ✨
okay so this section is about what mostly happens after the Merchant's Brand Compilation, which is the brand independent part of the transaction 💅 BUT bestie, some of these steps can totally overlap with the previous process (the brand dependent transaction) 🫶
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Merchant Merchant generates Brand List(s) containing
Brands, Payment Protocols and Currency Amounts
On brand independent transactions
| Merchant generates Offer Response Block
Consumer Compile set(s) of Brands B/Protocols P
for each set
| Find Payment Instrument(B, P, C) -> IPB
| Find Payment Instrument Response (PI*) <- IPB
Consumer selects Brand/Currency/Payment Instrument
from those that will work and generates Brand
Selection Component
For the Selection
| Get Payment Initialization Data(B,C,PI,P) -> IPB
| Get Payment Initialization Data Response()<- IPB
On brand dependent transaction
| Generate and transmit TPO Selection Block
Merchant On brand dependent transaction
| Merchant checks Brand Selection and generates
| and transmits Offer Response Block
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 4. Brand Selection Message Flows 🎀
- okay first up, the Merchant's commerce server keeps running the shopping dialog with its own mechanisms until the Consumer checks out the shopping cart and says they want to pay 🛒 Then processing switches to the IOTP based form once the Merchant's IOTP aware application gets activated ✨
- the IOTP Application Core builds the IOTP Trading Protocol Options Block 🧚 It holds the IOTP Brand List Component(s), which list the Merchant's accepted payment brands and payment protocols, and then kicks off the Brand Selection process 🔥
- this first IOTP message wakes up the Consumer's IOTP aware application 💖 For example, the Web browser invokes a helper application (e.g., Java applet or external application). Its IOTP Application Core:
- infers the accepted payment brands, payment protocols, payment direction, currencies, payment amounts, any descriptions etc., and their relationships from the IOTP message,
- determines the registered IOTP Payment Bridges,
- compiles one or multiple sets of brand and protocol so that the join of all sets describes exactly the payment alternatives being offered by the Merchant,
- inquires payment (protocol) support and the known payment instruments from each registered IOTP Payment Bridge for each compiled set ("Find Payment Instrument"). Some IOTP Payment Bridges may refuse payment instrument distinction though 🙈
The payment protocol support may differ between payment instruments if the IOTP Payment Bridge supports payment instrument distinction 🦋
These API calls are used to infer the payment alternatives at the startup of any payment transaction, without user unfriendly explicit user interaction ✨
The IOTP Application Core must provide wallet identifiers if they are requested by the IOTP Payment Bridges, which signal their need through specific error codes (see below) 💅
It is recommended that the IOTP Application Core manages wallet identifiers. But for security reasons, it should store pass phrases in plain text only in runtime memory 🔐 Developers of IOTP Payment Bridges and payment software modules should provide a thin and fast implementation, without lengthy initialization processes, for this initial inquiry step 🌸
- the IOTP Application Core checks the Consumer's payment capabilities against the Merchant's accepted payment brands and currencies 👑 Then it:
- displays the valid payment instruments and payment instrument independent payment brands (brand and protocol) together with their purchase parameters (payment direction, currency, amount), and
- requests the Consumer's choice or derives it automatically from any configured preferences. Any selection ties one IOTP Payment Bridge with the following payment transaction 🎀
The handling and resolution of unavailable IOTP Payment Bridges during the inquiry in Step 3 is up to the IOTP Application Core. It may skip these IOTP Payment Bridges or may allow user supported resolution 🌈
Furthermore, it may offer the registration of new payment instruments when the Consumer is asked for payment instrument selection 💜
- the IOTP Application Core asks the fixed IOTP Payment Bridge whether the payment might complete with success ("Check Payment Possibility") 🙏 At this step, the IOTP Payment Bridge may issue several signals, e.g.:
- payment can proceed immediately,
- required peripheral inclusive of some required physical payment instrument (chip card) is unavailable,
- (non-IOTP) remote party (e.g., issuer, server wallet) is not available,
- wallet identifier or pass phrase is required,
- expired payment instrument (or certificate), insufficient funds, or
- physical payment instrument unreadable 💀
In any erroneous case, the user should be notified and offered accurate alternatives 🚨
Most probably, the user might be offered:
- to resolve the problem, e.g., to insert another payment instrument or to verify the periphery,
- to proceed (assuming its success),
- to cancel the whole transaction, or
- to suspend the transaction, e.g., initiating a nested transaction for uploading an electronic purse 🧁
If the payment software implements payment instrument selection on its own, it may request the Consumer's choice at this step 🫶
If the check succeeds, it returns several IOTP Brand Selection Info Elements ⭐
- Steps 2 to 5 are repeated and possibly interlaced for the selection of the second payment instrument during IOTP Value Exchange transactions. This is omitted in the figure above 🍓
- the IOTP Brand Selection Component is generated and enriched with the Brand Selection Info elements 🌟 This component is transmitted to the Merchant inside a TPO Selection Block if the received IOTP message lacks the IOTP Offer Response Block. The Merchant will then respond with an IOTP Offer Response Block, following the aforementioned compilation rules 💖
2.4. Successful Payment 💖
Okay so, here's the full story of how all these functions team up to pull off a successful payment 💅 Peep Figure 5 below. In it, PS0, PS1, ..., and PSn mean the nth PayScheme Packaged Content data, and [ ] means optional. (Technically, two payments happen during IOTP Value Exchange transactions 🙈)
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer Start Payment Consumer(Amount,[PS0]...) -> IPB
Start Payment Cons. Res.([PS1], CS=Cont.) <- IPB
Create and transmit Payment Request Block
Payment Handler Start Payment Pay. Handler(Amount, [PS1]) -> IPB
Start Payment PH Response(PS2, CS=Cont.) <- IPB
Create and transmit Payment Exchange Block
Consumer Continue Process(PS2) -> IPB
Continue Process Response(PS3, CS=Cont.) <- IPB
... CONTINUE SWAPPING PAYMENT EXCHANGES UNTIL ...
Payment Handler Continue Process Response([PSn], CS=End) <- IPB
Request any local payment receipt
| Inquire Process State() -> IPB
| Inquire Proc. State Resp.(State, [Rcp.])<- IPB
Create and transmit Payment Response Block
Terminate transaction, actively
| Change Process State(State) -> IPB
| Change PS Response(State=CompletedOK) <- IPB
Consumer On receipt of final payment scheme data
| Continue Process(PSn) -> IPB
| Continue Process Response(CS=End) <- IPB
Check Payment Receipt(Receipt) -> IPB
Check Payment Receipt Response() <- IPB
Request any local payment receipt
| Inquire Process State() -> IPB
| Inquire Proc. State Resp.(State, [Rcp.])<- IPB
Terminate transaction, actively
| Change Process State(State) -> IPB
| Change PS Response(State=CompletedOk) <- IPB
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Figure 5. Example Payment Message Flows- Once Brand Selection is done and the IOTP Offer Response Block arrives, the Consumer switches from chatting with the Merchant to chatting with the Payment Handler. Big moment! 🦋
This might be a milestone that needs the Consumer to say yes again about continuing the payment transaction. This is especially a good moment for payment suspension (and even cancellation) 🙌, which will most probably be supported by all payment schemes. Why? Simply because the actual payment legacy systems haven't been involved in the transaction yet ✨
That agreement might be explicit for each transaction, or automatic based on configured preferences, e.g., early acknowledgments for specific payment limits.
It is assumed that the transaction moves forward with minimal user (Consumer and Payment Handler) interaction, and that its progress is controlled by the IOTP Application Core and IOTP Payment Bridge. 💜
- To open the actual payment transaction, the IOTP Application Core sends the "Start Payment Consumer" request to the IOTP Payment Bridge. This request carries the whole initialization data of the payment transaction, which the IOTP Payment Bridge refers to for later consistency checks:
- payment brand and its description from the selected Brand Element of the IOTP Brand List Component,
- payment instrument from the preceding inquiry step,
- further payment parameters (currency, amount, direction, expiration) from the selected Currency Amount element, Brand List Component, and Payment Component of the IOTP Offer Response Block,
- payment protocol from the selected IOTP Pay Protocol Element,
- order details contained in the IOTP Order Component, which might be payment scheme specific,
- payment scheme specific data, including the payment protocol descriptions from the IOTP Protocol Amount Element and IOTP Pay Protocol Element, and
- payment scheme specific data, including the payment protocol descriptions in which the name attribute includes the prefix as "Payment:" from the Trading Role Data Component.
Generally, the called API function redoes most of the checks from the "Check Payment Possibility" call, since there aren't strong dependencies between the two requests: there might be a significant delay between them 🕰️
The called API function may return further payment scheme specific data, which is treated as payment specific initialization data for the Payment Handler's IOTP Payment Bridge.
If the fixed Existing Payment Software handles payment instrument selection on its own, it may ask the Consumer for their choice at this step 🤷♀️
The IOTP Payment Bridge reports a lack of capability in much the same way as the "Check Payment Possibility" request does, to the IOTP Application Core. The Consumer may decide to fix the problem, suspend, or cancel the transaction, but this function call must succeed in order to proceed with the transaction 🥺
Developers of payment modules may decide to skip payment instrument related checks, like expiration date or refunds sufficiency, if those checks are part of the specific payment protocol.
If the IOTP Payment Bridge asks for wallet identifiers or pass phrases at any point during the payment process, they should be requested by this API function too. It is recommended that the IOTP Application Core stores plain text pass phrases only in runtime memory 🔐
Finally, the IOTP Application Core generates the IOTP Payment Request Block, inserts any returned payment scheme data, and submits it to the Payment Handler's system. 🚀
- The Payment Handler's IOTP Application Core opens the payment transaction by calling the "Start Payment Payment Handler" API function. The payment brand, its description, payment protocol, payment specific data, payment direction, currency, and payment amount are determined much like they are on the Consumer's IOTP Application Core. On top of that, the content of the IOTP Payment Scheme Component and the IOTP Brand Selection Info Elements are passed to this function. 🧚
On success, the Payment Handler's IOTP Payment Bridge responds with payment scheme specific data. On failure, this non-interactive server application has to sort out any problems on its own or give up and abort the payment transaction. However, the Consumer may restart the whole payment transaction. Either way, the payment log file should reflect any payment attempts 📒
Eventually, the Payment Handler tells the Consumer about the current IOTP Process State using the IOTP Payment Response or IOTP Error Block.
Note that the "Start Payment Payment Handler" call might return the Continuation Status "End", in which case payment processing carries on with Step 7. 👀
- The IOTP Application Core checks that the Payment Exchange Block is present in the IOTP message and passes the contained payment scheme specific data to the fixed IOTP Payment Bridge ("Continue Process"), which returns the next IOTP Payment Scheme Component. 🔄
This Payment Scheme Component gets wrapped in an IOTP Payment Exchange Block and sent to the Payment Handler.
- The Payment Handler's IOTP Application Core checks for the Payment Exchange Block and passes the contained payment scheme specific data to the fixed IOTP Payment Bridge ("Continue Process"), which returns the next IOTP Payment Scheme Component for wrapping and sending on to the Consumer. 💌
- The payment keeps going with IOTP Payment Exchange Block swaps carrying the payment scheme specific data. Each party (1) passes the embedded payment scheme specific data, untouched, to the appropriate IOTP Payment Bridge by calling the "Continue Process" API function, (2) wraps the returned payment scheme specific data into an IOTP Payment Exchange Block, and (3) sends this block to the counter party. 🏓
Still, processing the payment scheme specific data can fail for several reasons 😬 These failures are signaled with specific error codes, which are turned into IOTP Payment Response Blocks (generated by the Payment Handler) or IOTP Error Blocks (either party may generate these), and sent to the counter party.
- Eventually, the Payment Handler's IOTP Payment Bridge notices the payment transaction has ended and reports this with the continuation status "End" in the output parameter of "Continue Process" (or "Start Payment Payment Handler"). Then the IOTP Application Core makes the "Inquire Process State" API call and checks whether an IOTP Payment Receipt Component has come back. The IOTP Application Core wraps the payment receipt, the status response, and the optional payment scheme specific data in an IOTP Payment Response Block and sends this block to the Consumer. 🧾
Any of these API calls might fail, or a response might be incomplete (e.g., no payment receipt). In that case, the Consumer has to be told about the failed processing with an IOTP Error Block. 😭
Finally, the Payment Handler ends the payment transaction with the "Change Process State" API call, without waiting for any further response from the Consumer. Further failures are not reported to the Consumer. 🫥
Note that the Consumer's IOTP Payment Bridge might already have returned the previous payment scheme specific data with the continuation status "End". Even if the Payment Handler doesn't know this (the status is not exchanged between the Consumer and the Payment Handler), the Payment Handler must not supply any further payment scheme specific data. Such data will be rejected by the Consumer's IOTP Payment Bridge. 🚫
- The Consumer passes the optional payment scheme specific data and the payment receipt to the fixed IOTP Payment Bridge using the "Continue Process" and "Check Payment Receipt" API calls. 🧾
After that, the IOTP Application Core makes the "Inquire Process State" API call and checks whether any extensions to the payment receipt have come back.
Finally, the transaction is closed by calling the "Change Process State" API function, which checks and syncs the reported payment status with the local one and flags any inconsistencies. Any inconsistency and returned status text should be shown to the Consumer. 👑
At this point, the Payment Handler has already closed the payment transaction. So any failure has to be resolved locally or out-of-band. 🌸
2.5. Payment Inquiry
okay so in Baseline IOTP, payment inquiries are started by the Consumer 🛍️ to check the current payment progress and process state over at the remote Payment Handler 🔍. In figure 6, PS1 and PS2 stand for the first and second PayScheme Packaged Content data, and [ ] means optional 🎀
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Consumer Start Payment Inquiry() -> IPB
Start Payment Inquiry Response([PS1]) <- IPB
Create and transmit Inquiry Request Trading Block
Payment Handler Inquire Payment Status([PS1]) -> IPB
Inquire Payment Status Res.(State, [PS2]) -> IPB
Create and transmit Inquiry Response Trading
Block
Consumer If Payment Scheme Data present
| Continue Process(PS2) -> IPB
| Continue Process Response(CS=End) <- IPB
Change Process State(State) -> IPB
Change Process State Response(State) <- IPB
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 6. Remote Process State Inquiry ✨
- The Consumer can kick off a payment inquiry once the IOTP Application Core has opened the payment transaction, so any time after the first submission of the IOTP Payment Request Block 🚀. The IOTP Application Core asks the IOTP Payment Bridge for any extra payment scheme data that got fixed during brand selection (cf. Section 2.3) using the
Start Payment InquiryAPI request.
Erroneous API responses should be reported to the Consumer, and the IOTP Application Core should present valid alternatives (typically retry and cancellation) 🙅♀️
This request might do the whole setup, like checking that periphery is available or taking a pass phrase supplement, and the IOTP Payment Bridge reports a lack of capability in much the same way it does for the Check Payment Possibility request to the IOTP Application Core 💜
If the IOTP Payment Bridge asks for wallet identifiers or pass phrases at any point during the payment process, they should be requested through this API function too. It is recommended that the IOTP Application Core store plain text pass phrases only in runtime memory 🔐
The IOTP Application Core wraps any Payment Scheme Component in an IOTP Inquiry Request Block and submits that block to the Payment Handler 📦
- The Payment Handler analyses the IOTP Inquire Request Block, maps the Transaction Identifier to payment related attributes (brand, consumer and payment identifiers), works out the right IOTP Payment Bridge, and forwards the request to this IOTP Payment Bridge (
Inquire Payment Status) 🧠. The IOTP Application Core turns the response into an IOTP Inquiry Response Block and sends it to the Consumer 💌 - Once the Consumer gets the matching IOTP Inquiry Response Block, the Consumer's IOTP Application Core hands any encapsulated payment scheme specific data to the IOTP Payment Bridge for verification (
Continue Process) ✅ - The IOTP Application Core passes the reported payment status (except textual descriptions) to the IOTP Payment Bridge (
Change Process State) for verification and payment status change 🔄. The IOTP Payment Bridge reports any inconsistencies, along with the final payment status, back to the IOTP Application Core 👀
Any extra information the Consumer might care about has to be shown by the IOTP Payment Bridge or Existing Payment Software on their own 💅
2.6. Abnormal Transaction Processing
2.6.1. Failures and Cancellations
okay so IOTP splits failures up into a few different classes 🧩:
- Business and technical errors
- Error depths of transport, message and block level
- Transient errors, warnings, and hard errors.
Every IOTP Payment API has to handle failure notifications and failure responses 📬. This proposal borrowed the basic error reporting mechanisms between the IOTP Application Core and the IOTP Payment Bridge straight from the actual protocol 🫶. Business errors get reported by Status Components inside IOTP Response Blocks, while technical errors get signaled by Error Components inside IOTP Error Blocks ✨.
Cancellations are basically pretend business errors, and either trading party can start one 🙃.
Because this IOTP Payment API is all about slim interfaces 💅, it adds just one extra Error Code value for business error indication. Errors can show up on every API call 😭. When that value shows up, the IOTP Application Core has to figure out the details by calling Inquire Process State 🔍.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Any Party Issue some API request -> IPB
Error Response(Error Code) <- IPB
On "Business Error" response
| Inquire Process State() -> IPB
| Inquire P.S. Resp.(State, Receipt) <- IPB
Analyze local process state and try to resolve
with optional user interaction
If Process State Change needed
| Change Process State (State) -> IPB
| Change Process State Response(State) <- IPB
If counter party's notification required
| Create Error or Cancel Block (, add to next
| message, ) and transmit it to counter party
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 7. Error Response from IPB 🎀
The special Completion Codes ConsCancelled, MerchCancelled, and PaymCancelled (returned by Inquire Process State) are what decide that an IOTP Cancel Block gets made instead of an IOTP Error Block 🚫.
The rules for how the IOTP Application Core should behave are spelled out in the IOTP specification 📖.
Heads up, though: any payment termination (intermediate or not), whether that's a failure, a cancellation, or even a success, always gets reported to the IOTP Payment Bridge through the Change Process State API function ⚠️. That one function handles both the status changes and the consistency checking and synchronization 🔄. Any suspicion of inconsistency should be reported by the IOTP Payment Bridge so the IOTP Application Core can display it 👑.
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Any Party Error Block or Cancel Block Received
If Change Process State required
| Change Process State (State) -> IPB
| Change Process State Response(State) <- IPB
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 8. Error Notification from counter party 🌸
Not every failure is going to be visible at the IOTP layer 👀. For example, the processing of payment transactions might be temporarily held up by intermediate failures at the payment scheme or protocol transport layer, and the actual components might be able to fix those on their own 🛠️.
Final failures or cancellations, though, have to be reported at the IOTP layer 😤. For instance, communication time-outs and heavily faulty communication channels may kill the transaction 💀.
Any system component may implement time-out recognition and use the API mechanisms mentioned above to notify process state changes 📣. But time-outs can happen while talking to the counter party and also to local system components, like chip card readers or IOTP Payment Bridges 🙈. Either way, the Consumer's IOTP Application Core should tell the Consumer about the resolution options, which are retry, suspension, and cancellation 💖.
2.6.2. Resumption
Resuming a payment transaction can happen at different steps of the payment transaction 🦋:
- The Consumer's and Payment Handler's view of the transaction might not be in sync. Because the two sides use different time-out values, the counter party may not have suspended the payment transaction 😵💫
Any Resume Payment ... API function responds with an Error Code on a non-suspended payment transaction, and that signals a business error. After that, the IOTP Application Core has to issue the Inquire Process State API call for further analysis of the process state 🔍
- One IOTP message sent by one party might not get processed successfully, or might not even be received by the counter party. This needs to be handled by the actual payment scheme. It is expected that the IOTP Application Core will not recognize anything 🤷♀️
- IOTP doesn't provide any specific signal for payment resumption 🙅. When every IOTP Payment Exchange Block arrives, the IOTP Application Core has to decide whether that Block belongs to a pending transaction or to a suspended transaction that should be resumed 🧐. The IOTP Application Core might call the
Inquire Process StateAPI function to fill in any gaps in its knowledge 💡
Any Resume Payment API function responds with an Error Code on a non-suspended payment transaction, and that signals a business error. Similarly, the Continue Process API function should report business errors on non-pending payment transactions 🚨
- The payment transaction may not have been created at the Payment Handler (early suspension and failed data transmission) 🥺. In that case, the IOTP Application Core should respond with a business error that signals that the Consumer needs to repeat the payment transaction 🔁
Any Resume Payment, Continue Process or Inquire Process State API function should return an Error Code AttValIllegal on a non-existent payment transaction, and the further Error Attribute Names denotes the payment identifier 🪪
- The IOTP Application Core should always request fresh payment scheme specific data on resumption 🌈, so it stays in sync with the Existing Payment Software. Old data in the cache that has not been sent to the counter party should not be accessed 🚫
If the Consumer doesn't reconnect within an acceptable amount of time, the Payment Handler's system may do local failure resolution to close the transaction and free up resources for other transactions (Change Process State) ⏳. If the Consumer reconnects afterwards, an IOTP Payment Response or IOTP Error Block could be generated 💜
2.7. IOTP Wallet Initialization 💖
Okay so, at startup (or whenever the user asks, bestie) the IOTP Application Core SHOULD go check on its IOTP Payment Bridges' internal status by hunting for pending payment transactions 🔍✨
- The IOTP Application Core asks every registered IOTP Payment Bridge about pending payment transactions. The IOTP Application Core MAY store indicators for pending transactions and use them to drive any later inquiry ("Inquire Pending Payment") 🦋
- If one or more IOTP Payment Bridges report pending transactions, the IOTP Application Core MAY try to suspend (
Change Process State) or resume (only for the Consumer:Resume Payment Consumer) those transactions, but only when the user asks for it 💅
The IOTP Payment Bridge MAY deny the processing of any new payment transactions until the pending ones have been processed. Such denials are signaled with the error code Business Error. Not the vibe, but it's the rule 🙈
2.8. Payment Software Management 🌸
The IOTP Application Core gives you only a simple, generic interface for registering new payment methods and instruments (Manage Payment Software). It takes the initial user request and hands the actual registration off to the matching IOTP Payment Bridge. Delegation era 👑
The IOTP Application Core MAY also activate the Existing Payment Software for further payment instrument and wallet administration 🧚
3. Mutuality ✨
The Payment API is formalized using the eXtensible Markup Language (XML). It defines wrapper elements for both the input parameters and the API function's response, and the response wrapper gives you common spots for Error Codes and Error Descriptions. Organized, bestie 🎀
It is anticipated that this description reflects the logical structure of the API parameter and might be used to derive implementation language specific API definitions. So it's basically a blueprint for making language-specific versions 💜
XML definition:
<!ELEMENT IotpPaymentApiRequest (
FindAcceptedPaymentBrand |
FindAcceptedPaymentProtocol |
GetPaymentInitializationData |
FindPaymentInstrument |
CheckPaymentPossiblity |
StartPaymentConsumer |
StartPaymentPaymentHandler |
ResumePaymentConsumer |
ResumePaymentPaymentHandler |
ContinueProcess |
InquireProcessState |
ChangeProcessState |
InquireAuthChallenge |
Authenticate |
CheckAuthResponse |
CheckPaymentReceipt |
ExpandPaymentReceipt |
RemovePaymentLog |
PaymentInstrumentInquiry |
InquirePendingPayment |
ManagePaymentSoftware |
StartPaymentInquiry |
InquirePaymentStatus |
CallBack )>
<!ATTLIST IotpPaymentApi
xml:lang NMTOKEN #IMPLIED
ContentSoftwareID CDATA #IMPLIED
xmlns CDATA #FIXED
"http://www.iotp.org/2000/08/PaymentAPI" >
<!ELEMENT IotpPaymentApiResponse (ErrorResponse?, (
FindAcceptedPaymentBrandResponse |
FindAcceptedPaymentProtocolResponse |
GetPaymentInitializationDataResponse |
FindPaymentInstrumentResponse |
CheckPaymentPossiblityResponse |
StartPaymentConsumerResponse |
StartPaymentPaymentHandlerResponse |
ResumePaymentConsumerResponse |
ResumePaymentPaymentHandlerResponse |
ContinueProcessResponse |
InquireProcessStateResponse |
ChangeProcessStateResponse |
InquireAuthChallengeResponse |
AuthenticateResponse |
CheckAuthResponseResponse |
CheckPaymentReceiptResponse |
ExpandPaymentReceiptResponse |
RemovePaymentLogResponse |
PaymentInstrumentInquiryResponse |
InquirePendingPaymentResponse |
ManagePaymentSoftwareResponse |
StartPaymentInquiryResponse |
InquirePaymentStatusResponse |
CallBackResponse )?)>
<!ATTLIST IotpPaymentApiResponse
xml:lang NMTOKEN #IMPLIED
ContentSoftwareID CDATA #IMPLIED
xmlns CDATA #FIXED
"http://www.iotp.org/2000/08/PaymentAPI" >
<!ELEMENT ErrorResponse (ErrorLocation+,PaySchemePackagedContent*) >
<!ATTLIST ErrorResponse
xml:lang NMTOKEN #IMPLIED
ErrorCode NMTOKEN #REQUIRED
ErrorDesc CDATA #REQUIRED
Severity(Warning |
TransientError |
HardError) #REQUIRED
MinRetrySecs CDATA #IMPLIED
SwVendorErrorRef CDATA #IMPLIED >Most of the attribute items are meant to be dropped straight into the IOTP Error Block. The attribute values of the Error Location elements have to be enriched and transformed into Error Location Elements of the Error Component (see the IOTP Specification) ✨
Attributes (cf. IOTP Specification):
xml:lang: Sets the language used by attributes or child elements within this component, unless a child element overrides it with its ownxml:langattribute 🌈ContentSoftwareId: Identifies the software that generated the content of the element. Its job is to help sort out interoperability problems caused by incompatibilities between messages from different software. It is a single text string in the language defined byxml:lang. It must contain, as a minimum:- the name of the software manufacturer,
- the name of the software,
- the version of the software, and
- the build of the software.
ErrorCode: Holds an error code that shows the nature of the error in the message in error. Valid values are listed in the following section. This mnemonic lets the IOTP Application Core automatically resolve failures: it reads the error code value to work out what it can do next 🔥ErrorDesc: Holds a description of the error, in the language defined byxml:lang. The vendor or developer of the software that generated the Error Response Element defines what goes in here. It's meant for user display and gives detailed explanations of the failure and its (out-of-band) resolution options 💬Severity: Shows how severe the error is. Valid values are:Warning: There's a message in error, but the IOTP Transaction can still continue.TransientError: The error in the message in error may be recovered if the message referred to by the "Names" attribute is resent.HardError: There's an unrecoverable error in the message in error, and the IOTP Transaction must stop. Yikes 💀
MinRetrySecs: This attribute SHOULD be present ifSeverityis set toTransientError. It is the minimum number of whole seconds that the IOTP aware application which received the message reporting the error should wait before resending the message in error identified by the "ErrorLocation" attribute ⏳
If Severity is not set to TransientError, then the value of this attribute is ignored.
SwVendorErrorRef: A reference whose value is set by the vendor or developer of the software that generated the Error Element. It SHOULD contain data that lets the vendor pinpoint the exact spot in their software, and the set of circumstances, that caused it to generate the error message 🕵️♀️
Content:
ErrorLocation: Identifies, where possible, the element and attribute in the message in error that caused the Error Element to be generated. If theSeverityof the error is notTransientError, more than oneErrorLocationMAY be specified, depending on the nature of the error and at the discretion of the vendor or developer of the IOTP Payment Bridge.
Its definition lines up with the IOTP specification, in that the attributes "IotpMsgRef", "BlkRef" and "CompRef" are left blank, on purpose 🧩
PaySchemePackagedContent: cf. Table 5 🎁
3.1. Error Codes 🚨
The following table lists the valid values for the ErrorCode attribute of the Error Response Element. The first sentence of each error description is the default text you can use when the error is displayed or otherwise reported. Individual implementations MAY translate it into other languages at their discretion. However, not every error code will apply to every API call. An Error Code MUST NOT be more than 14 characters long. The Error Codes come from the IOTP Specification and have been extended with some extra codes, which are highlighted with a preceding asterisk ⭐
Generally, if the corrupt values were user supplied, the IOTP Application Core might prompt for their correction. If the renewal fails, or if the IOTP Application Core skips any renewals and some notification has to be sent to the counter-party, the error code gets wrapped inside an IOTP Error Block 📦
However, the IOTP server application reports business errors (the ones visible at the IOTP layer) in the Status Component of the respective Response Block 💼
The IOTP Application Core MAY add the attributes (and values) within the ErrorLocation elements that the IOTP Payment Bridge left out.
The following table notes any changes from this general processing for particular error values. It also has hints for IOTP Application Core developers about how to process error codes. And IOTP Payment Bridge developers get a feel for what the IOTP Application Core is expecting 🦋
The IOTP Payment API assumes that the IOTP Application Core implements the dialog boxes needed for error resolution. But it does not assume that the IOTP Payment Bridge actually relies on them. Instead, the IOTP Payment Bridge MAY try resolution on its own, MAY implement specific dialog boxes, and MAY signal only final failures 🫶
Note: This abstract document assumes that the API parameters are exchanged XML encoded. So several error values might disappear in lower-level, language-specific derivations 👀
Error Value Error Description
----------- -----------------Okay bestie, the first one is Reserved 🎀. This error is reserved by the vendor or developer of the software, so if you see it, reach out to them for more info. You can find their details in the SoftwareId attribute of the Message Id element in the Transaction Reference Block [IOTP] 🔍
XmlNotWellFrmd🌸 means the XML document isn't well formed. For what "well formed" actually means, check [XML] ✨XmlNotValid💅 is one step further: the XML is well formed, but it's still not valid. Again, [XML] explains "valid". Specifically, it's giving:- the XML doesn't follow the constraints in the IOTP document type declaration, and
- the XML doesn't follow the constraints in the document type declaration of any extra [XML-NS] that got declared.
The Names attribute might point at some attributes and elements from the input parameter list 🧚
(*)ElNotValid🦋 means an element is invalid in terms of its prescribed syntax. The ElementRef attributes of ErrorLocation elements might point to the matching elements (if they have ID attributes). Also, the IOTP Application Core has to swap this code forXmlNotValidbefore sending it to the counterparty, no exceptions 🙅♀️ElUnexpected👀 means the XML is well formed and valid, but there's an element showing up where it doesn't belong, according to the rules and constraints in this spec. ElementRef attributes might refer to the matching elements (if they have ID attributes).ElNotSupp🌈 means the document is well formed and valid, and the element is totally consistent with the rules, but the IOTP Aware Application processing the message just doesn't support it 😭 ElementRef attributes might refer to the matching elements (if they have ID attributes).ElMissing🥺 means the document is well formed and valid, but an element is absent when it should've been there if you followed the rules and constraints in this spec. ElementRef attributes might refer to the matching elements (if they have ID attributes).ElContIllegal🍓 means the document is well formed and valid, but the element's values don't conform to the rules and constraints in this spec. ElementRef attributes might refer to the matching element (if it has an ID attribute). Here's the tea: the IOTP Application Core has to replace the Error Code withElNotSuppbefore sending it to the counter party, but only if the ErrorLocation elements refer to a non-PackagedContent element ✨EncapProtErr💜 means the document is well formed and valid, but the Packaged Content of an element has data from an encapsulated protocol that contains errors. ElementRef attributes might refer to the matching element (if it has an ID attribute).AttUnexpected🙈 means the XML is well formed and valid, but this attribute just isn't expected in this context, according to the rules and constraints in this spec. AttName attributes of ErrorLocation elements might refer to the matching attribute tags.(*)AttNotValid💀 means the attribute value is invalid in terms of its prescribed syntax. AttName attributes of ErrorLocation elements might refer to the matching attribute tags. Same deal as before: the IOTP Application Core has to swap this forXmlNotValidbefore sending it to the counter party 🫶AttNotSupp🦋 means the XML is well formed and valid, and the attribute is totally fine in that element according to the rules, but the IOTP Aware Application processing the message doesn't support it.AttMissing🌸 means the document is well formed and valid, but an attribute is missing when it should've been there. AttName attributes of ErrorLocation elements might refer to the matching attribute tags. Quick heads up: if the attribute is required by the IOTP Document Type Declaration (#REQUIRED), the hints for non-valid attributes should be adopted. Otherwise, the hints for illegal attribute values should be used instead 🎀AttValIllegal🔥 means the attribute holds a value that doesn't conform to the rules and constraints in this spec. AttName attributes of ErrorLocation elements might refer to the matching attribute tags. Here are the valid values, bestie 👑:BrandId: this is an illegal or unknown Brand Identifier. If no IOTP Payment Bridge recognizes or knows the brand, the IOTP Application Core may offer to register a new Payment Instrument ✨PaymentInstrumentId: this is an illegal or unknown Payment Instrument Identifier. If the same "wallet" already reported this value on a previous inquiry request, that's a serious communication problem 😬 The IOTP Application Core has to replace the error code withUnknownErrorbefore sending it to the counter party.WalletId: this is an illegal or unknown Wallet Identifier. It's assumed the wallet identifier gets checked before the pass phrase. For invalid wallet identifiers, the IOTP Application Core may open a dialog to ask for the correct one. Any pass phrase may also be supplied by the user, and the dialog should show the respective payment brand(s) 💖 The IOTP Application Core has to replace the error code withUnknownErrorbefore sending it to the counter party.Passphrase: this is an illegal or unknown Pass Phrase. The IOTP Application Core may open a dialog to request the correct pass phrase. If the pass phrase is specific to a wallet identifier, the dialog should display that wallet identifier. The IOTP Application Core has to replace the error code withTransportErrorbefore sending it to the counter party 🧚Action: this is an illegal, unknown, or unsupported Action 💅PropertyTypeList: this list contains illegal, unknown, or unsupported Property Types. The IOTP Application Core tries only local resolution and never transmits any IOTP Error Block to the counter party. Totally private drama 🙈CurrCode: this is an illegal, unknown, or unsupported Currency Code 💜CurrCodeType: this is an illegal, unknown, or unsupported Currency Code Type 💜Amount: this is an illegal, unknown, or unsupported Payment Amount 🍓PayDirection: this is an illegal, unknown, or unsupported Payment Direction 🌈ProtocolId: this is an illegal, unknown, or unsupported Protocol Identifier 🦋OkFrom: this is an illegal, unknown, or unsupported OkFrom Timestamp ⭐OkTo: this is an illegal, unknown, or unsupported OkTo Timestamp ⭐ConsumerPayId: this is an illegal or unknown Consumer Payment Identifier 🎀PaymentHandlerPayId: this is an illegal or unknown Payment Handler Payment Identifier 🎀PayId: this is an illegal or unknown Payment Identifier 🎀
AttValNotRecog🤔 means the attribute holds a value that the IOTP Aware Application generating the error message couldn't recognize. AttName attributes of ErrorLocation elements might refer to the matching attribute tags.MsgTooLarge🐘 means the message is too big to be processed by the IOTP Payment Bridge (or the IOTP Application Core).ElTooLarge🐘 means the element is too big to be processed by the IOTP Payment Bridge (or the IOTP Application Core). ElementRef attributes of ErrorLocation elements might refer to the matching elements.
That's the whole error code lineup, periodt! 🌈👑
3.1. Error Codes 🚨
Okay so these are the error codes, bestie, and they're giving very organized energy 💅
ValueTooSmall🌸: Value too small or early. The value of all or part of an element content or an attribute is too small, even though it's valid. TheErrorLocationelements might point to the matching attribute tags or elements.ValueTooLarge🎈: Value too large or in the future. The value of all or part of an element content or an attribute is too large, even though it's valid. TheErrorLocationelements might point to the matching attribute tags or elements.ElInconsistent🧩: Element Inconsistent. The document is well formed and valid under the rules and constraints in this specification, but:- the content of an element doesn't match the content of other elements or their attributes, or
- the value of an attribute doesn't match the value of one or more other attributes.
The Error Description may have more explanations. The ErrorLocation elements might point to the attribute tags or elements that don't match 🙈
TransportError🚌: Transport Error. This one means there's a problem with the transport mechanism, and it's stopping the message from arriving. It's usually paired with a "Transient Error" 😭 The connection to some periphery or the counter party couldn't be set up, is broken, or got lost.
The Error Description can include more narrative details, like "chip card does not respond", "remote account manager unreachable", "Internet connection to xyz lost", "no Internet connection available", "no modem connected", or "serial port to modem used by another application". This text should be shown to the end user. If a timeout happens at the Consumer, this text should be shown, and the Consumer gets to decide what to do next. The options are retry, payment transaction suspension, and cancellation ✨
MsgBeingProc⏳: Message Being Processed. This error code is only used with a Severity of Transient Error. It means the previous message (an exchange message or a request message) is still being processed. If no response shows up by the time set in theMinRetrySecsattribute, the original message should be resent.SystemBusy🥵: System Busy. This is also only used with a Severity of Transient Error. It means the IOTP Payment Bridge or Existing Payment Software that got the API request is too busy to handle it right now. If no response arrives by the time set in theMinRetrySecsattribute, the original message should be resent.
The Error Description can give more details, like "wallet / chip card reader is unavailable or locked by another payment transaction", "payment gateway is overloaded", "unknown chip card reader", or "unrecognized chip card inserted, change chip card".
The Consumer's IOTP Application Core may show the error description and ask the Consumer what to do. The options are retry, payment transaction suspension, and cancellation 💖
UnknownError❓: Unknown Error. This means the transaction can't finish for a reason that none of the other errors cover. The Error description attribute should be used to explain what the problem is.
The ErrorLocation elements might point to the attribute tags or elements that don't match.
(*)SyntaxError📝: Syntax Error. An (unknown) syntax error happened.
The ErrorLocation elements might point to the attribute tags or elements that don't match.
The IOTP Application Core has to swap this error code for "XmlNotValid" or "UnknownError" before sending it to the counter party. Okay, that's a must!! 🫶
(*)ReqRefused🙅: Request refused. The API request is (currently) refused by the IOTP Payment Bridge. The error description might explain more, like "wallet / chip card reader is unavailable or locked by another payment transaction", "payment gateway is overloaded", "unknown chip card reader", or "unrecognized chip card inserted, change chip card".
The Consumer's IOTP Application Core may show the error description and ask the Consumer what to do next. The options are retry, payment transaction suspension, and cancellation. Denials caused by invalid Process States should be signaled by "BusinessError". This kind of error usually doesn't get passed to the counter party's IOTP Application Core. Otherwise, it maps to "TransportError" or "UnknownError" 🧃
(*)ReqNotSupp🚫: Request not supported. The API function(ality) hasn't been implemented in the IOTP Payment Bridge. This kind of error usually doesn't get passed to the counter party's IOTP Application Core. Otherwise, it maps to "TransportError" or "UnknownError".(*)BusError💼: Business Error. The API request got rejected because some payment transaction has an illegal payment status. This error code is especially used to signal any payment business layer failures.
The ErrorLocation elements may point to payment transactions using the party's Payment Identifier. That defaults to the current transaction, or it might hold the current payment transaction party's Payment Identifier, which is picked out by the ElementRef attribute while the AttName attribute is fixed as "PayId".
The IOTP Application Core must ask the IOTP Payment Bridge about the actual Process State, since that's what really encodes the business error ("Inquire Process State"). This error code must not be passed to the counter party's IOTP Application Core. Hard no 🙅♀️
Table 2: Common Error Codes 📋
The IOTP Payment Bridge may also use the error description to tell the Consumer what to do next so the failure can get fixed, for example: "Sorry, your payment transaction failed. Unfortunately, you have been charged, please contact your issuer." 💀
3.2. Attributes and Elements 🎀
Here's the attribute list in alphabetical order. Any number in parentheses after an attribute name is the recommended maximum length of its value, in characters 🍓
Amount(11),AmountFrom(11),AmountTo(11) 💰: This tells you the payment amount to be paid, in whole and fractional units of the currency. For example, $245.35 would be written as245.35. Values smaller than the smallest denomination are allowed, so one tenth of a cent would be0.001✨AuthenticationId🔑: An identifier set by the authenticator. If the organization that gets the authentication request sends it back, the authenticator can use it to figure out which authentication is being talked about 🧚BrandId(128) 🏷️: This holds a unique identifier for the brand (or promotional brand). It gets matched against a list of Payment Instruments the Consumer has, to decide whether the Consumer can pay with that Brand.
Values of BrandId are managed under a procedure described in the IOTP protocol specification 📚
BrandLogoNetLocn🖼️: The net location where the logo for the organization can be downloaded (cf. IOTP Specification).
The content of this attribute must conform to [URL].
BrandName🪪: This holds the name of the brand, for example "MasterCard Credit". It's the description of the Brand that gets shown to the Consumer, in the Consumer's language set by "xml:lang". For example, it might be "American Airlines Advantage Visa". Heads up: this attribute isn't used for matching against the payment instruments the Consumer holds 🙈BrandNarrative🎁: This optional attribute is used by the Merchant to point out special conditions or benefits that would apply if the Consumer picks that brand. For example "5% discount", "free shipping and handling", "free breakage insurance for 1 year", "double air miles apply", etc. 🛍️CallBackFunction🔔: A function that gets called whenever there's a change in Process State or payment progress, e.g., to update the display. However, the IOTP Payment Bridge may use its own mechanisms and dialog boxes instead 🌈
Okay, so this next batch is all about the attributes that keep the payment conversation moving. Let's go 💅
CallBackLanguageList🌍 is a list of language codes, in order of preference, for the languages the text passed to the Call Back function will be encoded in.CompletionCode(14) 🏁 tells everyone how the process wrapped up. It's required ifProcessStateis set to "Failed", and it's ignored otherwise. The valid values and recovery options live in the IOTP specification, so go check there. 🔍 The IOTP Payment Bridge can also use the Status Description to tell the Consumer what to do next when a business failure happens. Some lowkey iconic examples:
o "sorry, your payment transaction failed.
Unfortunately, you have been charged,
please contact your issuer."
o "insufficient capacity left (on your
stored value card) for refund",
o "payment failed/chip card error/internal
error, please contact your payment
instrument's issuer"ConsumerDesc🧍♀️ is a narrative description of the Consumer. Literally just the vibe check.ConsumerPayId(14) 🆔 is a unique identifier the Consumer picks. If it comes back from the Payment Handler in another Payment Scheme Component, or by some other route, the Consumer can tell which payment is being talked about. The IOTP Application Core generates it and sends it to the IOTP Payment Bridge on every API call. It can match the Payment Handler Payment Identifiers, but it doesn't have to. Uniqueness is a big deal here: it extends across multiple payment instruments, payment brands, payment protocols, wallet identifiers, and even multiple IOTP Payment Bridges. Main character uniqueness energy 👑ContStatus🔁 tells you whether a payment still needs more IOTP Payment Scheme Component exchanges with the remote party while it's in progress. "End" means the payment scheme data being reported is the last data to be exchanged with the counter party. That's the final text, bestie 🫶ContentSoftwareId🛠️ identifies the software that generated the element's content. Its whole job is to help solve interoperability problems caused by messages from different software not getting along. It's a single text string in the language defined byxml:lang, and it must contain, as a minimum:- the name of the software manufacturer,
- the name of the software,
- the version of the software, and
- the build of the software.
CurrCodeType(14) 💱 shows the domain of theCurrCode. This is there so the currency code can support nonstandard currencies like frequent flyer points, trading stamps, and so on. Its values can be:ISO-4217-A, the default, which means the currency code is the three-letter alphabetic code that conforms to ISO-4217 [ISO4217].IOTP, which means the values ofCurrCodeare managed under the procedure described in [IOTP].
CurrCode(14) 💰 is a code that identifies the currency used in the payment. The domain of valid currency codes is defined byCurrCodeType.MerchantPayId(14) 🔒 is a private identifier the Merchant picks so they can tell which payment is being referred to. It's a pure private item and is never sent to any other party. The IOTP Payment Bridge provides it during payment preparation, in brand compilation. For the uniqueness note, seeConsumerPayId. Secret and iconic 🤫MerchantOrgId(64) 🏬 is a local item that might point to a specific shop in a multi-shop environment. It's optional, and it can enrich the Wallet Identifier, which can be used for the same purpose.Name🏷️ tells apart multiple occurrences of Packaged Content Elements at the same point in IOTP. For example:
<ABCD>
<PackagedContent Name='FirstPiece'>
snroasdfnas934k
</PackagedContent>
<PackagedContent Name='SecondPiece'>
dvdsjnl5poidsdsflkjnw45
</PackagedContent>
</ABCD>The Name attribute may be omitted, for example if there's only one Packaged Content element. 🧚
OkFrom(30) andOkTo(30) 🗓️ are the date and time range, in UTC Format, that the merchant sets for when the Payment Handler may accept the payment. For more, see [UTC].Passphrase(32) 🗝️ is for payment wallets that use pass phrase protection on transaction data and payment instruments' data. It's assumed, though, that there's a public and customizable payment instrument identifier. Those identifiers, together with how they relate to payment brands, payment protocols, payment directions, and currency amounts, can be queried by the IOTP application without knowing any pass phrase. Good design, no cap ✨PayDirection➡️ shows which way the payment for which a Brand is being selected is going. Its values can be:- Debit: the sender of the Payment Request Block (for example, the Consumer) that this Brand List relates to will pay the Payment Handler, or
- Credit: the sender of the Payment Request Block that this Brand List relates to will receive a payment from the Payment Handler.
PayId(14) 🪪 was introduced to simplify the API:- The Consumer has to identify
PayIdandConsumerPayId. - The Merchant has to identify
PayIdandMerchantPayId. - The Payment Handler has to identify
PayIdand Payment Handler Pay Id.
- The Consumer has to identify
PayInstId🔑 contains the unique identifier the IOTP Payment Bridge or Existing Payment Software uses internally.PayInstName🏦 contains the user-defined name of the payment instrument. There are no (technical) constraints like uniqueness, so go wild. Thexml:langattribute says what language the value is encoded in. 🌈PaymentHandlerDesc🏪 is a narrative description of the Payment Handler.PaymentHandlerPayId(14) 🧾 is a unique identifier the Payment Handler picks. If the Consumer returns it in another Payment Scheme Component, or by other means, the Payment Handler can tell which payment is being referred to. It's required whenever it's known. For the uniqueness note, seeConsumerPayId.PaymentInstrumentId(32) 💳 identifies a specific payment instrument, like "credit card" or "Mondex card for English Pounds". It's fully customizable, and it's assumed not to contain confidential information or even hint at it. The payment instrument identifier is unique within each payment brand, and it's displayed to the Consumer during brand selection.PayReceiptNameRefs(32) 🧾✨ optionally contains element references to other elements (with payment-scheme-specific data) that together make up the receipt. Each payment scheme defines in its supplement which elements must be referenced. The IOTP Application Core should save all the referenced components so the payment receipt can be rebuilt when needed. Receipts for days 💖PayReqNetLocn📮 is the Net Location showing where an unsecured Payment Request message should be sent, if this protocol choice is used. Its content must conform to [URL] and depends on the Transport Mechanism.PercentComplete(3) 📊 is a number from 0 to 100 showing how far along the payment transaction is. For pending and suspended transactions, the values range from 0 to 99. Almost there, never fully done 🙈ProcessState🚦 contains a Process State Code showing the current state of the process being carried out. Valid values are:- NotYetStarted. The Payment Request Block has been received, but processing of the Payment Request hasn't started yet.
- InProgress. The payment transaction is pending. Processing of the (Payment) Request Block has started but isn't finished yet.
- (*)Suspended: The payment transaction has been suspended and can be resumed. 🌸
If this process state gets passed to the counter party's IOTP Application Core, it gets mapped to "InProgress". That's the mapping, bestie 🦋
CompletedOk: the (Payment) Request Block and any Payment Exchange Blocks after it have finished processing successfully ✨Failed: payment processing has finally failed for a Business Error 💀ProcessError: this one is only used when the Status Component is being used with an Inquiry Request Trading Block 🙈 It means there's a Technical Error in the Request Block being processed, or some internal processing error. Each party's IOTP Payment Bridge uses it to tell the IOTP Application Core about technical errors 🔥
Okay bestie, now the attributes. These are the property types, descriptions, and the rest, so they stay exactly as written 🎀
PropertyType (14) The property type defines codes used for
interrogation of specific properties about a
payment instrument. They are unique for each
payment brand. The predefined property "all"
is used on general inquiries. However, these
property types are not used during normal
payment processing. E.g., they may apply to
payment brand specific transactions or
out-of-band failure resolution.
PropertyDesc The property description carries the
respective human readable property (value)'s
description.
PropertyValue The actual property value intends automatic
post processing.
ProtocolBrandId (64)This is an identifier to be used with a
particular payment protocol. For example,
SET and EMV have their own well defined, yet
different, values for the Brand identifier
to be used with each protocol. The valid values
of this attribute are defined in the
supplement for the payment protocol
identified by "ProtocolId" that describes
how the payment protocol works with IOTP.
Identifier maps to at most one Protocol
Brand Identifier.
ProtocolId (64) An identifier for a specific payment
protocol and version, e.g., "SETv1.0",
"ecash". Valid values are defined by
supplements to the IOTP specification and
they are unique within each payment brand.
ProtocolIds A sequence of Protocol Identifiers
ProtocolName A narrative description of the payment
protocol and its version in the language
identified by "xml:lang". For example
"Secure Electronic Transaction Version 1.0".
Its purpose is to help provide information
on the payment protocol being used if
problems arise.
SecPayReqNetLocn The Net Location indicating where a secured
Payment Request message should be sent if
this protocol choice is used.
A secured payment involves the use of a
secure channel such as [TLS] in order
to communicate with the Payment Handler.
The content of this attribute must conform
to [URL].
ReceiverOrgId The Organization Identification which
receives the payment bridge processing
Trading Role Data PackagedContent.
StatusDesc (256) An optional textual description of the
current process state in the language
identified by "xml:lang" that should be
displayed to the Consumer. The usage of this
attribute is defined in the payment
supplement for the payment method being
used. Particularly, it provides hints for
out-of-band failure resolution. Its length
is limited to 256 characters.
StyleSheetNetLocn This contains the net location to a style
sheet with visualisation rules for XML
encoded data.
TimeStamp (30) The date and time in UTC Format when the
payment transaction has been started.
For more information on UTC, see [UTC].
WalletId (32) Many existing payment wallet software are
multiple wallet capable. The Wallet
Identifier selects the actual wallet. It is
assumed, that the wallet identifier is a
public item, that might be stored by the
IOTP Application Core.
xml:lang Defines the language used by the Process
State Description attribute (cf. IOTP
Specification)Table 3: Attributes 🦋
Next up, the XML elements, in alphabetical order 💜
Element Description
------- -----------
Algorithm This contains information which describes
an Algorithm that may be used to generate
the Authentication response.
The algorithm that may be used is
identified by the Name attribute (cf. IOTP
Specification).
AuthReqPackagedContent The Authentication Request Packaged
Content originates from a Authentication
(Data/Response) Component's content
whereby the outermost element tags are
prefixed with "AuthReq". Its declaration
coincides with the Packaged Content's
declaration (cf. IOTP Specification). It
encapsulates the authentication challenge
value. The content of this information is
defined in the supplement for a payment
protocol.
AuthResPackagedContent The Authentication Response Packaged
Content originates from a Authentication
Response Component's content whereby the
outermost element tags are prefixed with
"AuthRes".
Its declaration coincides with the
Packaged Content's declaration (cf. IOTP
Specification). It encapsulates the
authentication response value. The
content of this information is defined in
the supplement for a payment protocol.
BrandPackagedContent Container for further payment brand
description. Its content originates from
a Brand Element content whose outermost
element tags are prefixed with "Brand".
Its declaration coincides with the Packaged
Content's declaration (cf. IOTP Specification).
BrandSelBrandInfoPackagedContent
This contains any additional data that
may be required by a particular payment
brand. It forms the content of the Brand
Selection Brand Info Element.
BrandSelProtocolAmountInfoPackagedContent
This contains any additional data that
may be required by a particular payment
brand in the format. It forms the content
of the Brand Selection Protocol Amount
Info Element.
BrandSelCurrencyAmountInfoPackagedContent
This contains any additional data that is
payment brand and currency specific in
the format. It forms the content of the
Brand Selection Currency Amount Info
Element.
MerchantData Any merchant related data that might be
used by the IOTP Payment Bridge for
different purposes, e.g., it might
contain IDs to access some mall data,
but not cryptographic keys. Its Packaged
declaration coincides with the Content's
declaration (cf. IOTP Specification).
PackagedContent Generic Container for non-IOTP data (cf.
IOTP Specification).
PayProtocolPackagedContent
The Pay Protocol Packaged Content
originates from a Pay Protocol
Element's content whereby the outermost
element tags are prefixed with
"PayProtocol". It contains information
about the protocol which is used by
the payment protocol. The content of
this information is defined in the
supplement for a payment protocol. Its
declaration coincides with the Packaged
Content's declaration (cf. IOTP
Specification).
PaySchemePackagedContent
The PayScheme Packaged Content originates
from a Payment Scheme Component's content
whereby the outermost element tags are
prefixed with "PayScheme". Its
declaration coincides with the Packaged
Content's declaration (cf. IOTP
Specification). It carries the payment
specific data. The content of this
information is defined in the supplement
for a payment protocol.
ProtocolAmountPackagedContent
The Protocol Amount Packaged Content
originates from a Protocol Amount
Element's content whereby the outermost
element tags are prefixed with "Amount".
Its declaration coincides with the
Packaged Content's declaration (cf. IOTP
Specification). It contains information
about the protocol which is used by the
payment protocol. The content of this
information is defined in the supplement
for a payment protocol.
ProtocolBrandPackagedContent
The Protocol Brand Packaged Content
originates from a Protocol Brand
Element's content whereby the outermost
element tags are prefixed with
"ProtocolBrand". Its declaration
coincides with the Packaged Content's
declaration (cf. IOTP Specification). It
contains information about the brand
which might be used by the payment
protocol. The content of this information
is defined in the supplement for a
payment protocol.ResponsePackagedContent
Container for authentication response
data. Its content originates from a
Authentication Response Component's
Packaged Content whose outermost element
tags are prefixed with "Response". Its
declaration coincides with the Packaged
Content's declaration (cf. IOTP
Specification).
TradingRoleDataPackagedContent
The TradingRoleData Packaged Content
originates from a TradingRoleData
Component's content whereby the outermost
element tags are prefixed with
"TradingRoleData". Its declaration
coincides with the Packaged Content's
declaration (cf. IOTP Specification). It
contains information from Merchant to
Payment Handler via Consumer about the
protocol which is used by the payment.
The content of this information is
defined in the supplement for a payment
protocol. The Name attribute in this
packaged contents must include prefix as
"Payment:" to indicate that the payment
bridge processes this, for example
"Payment:SET-OD". See [SET/IOTP] for
more information.
The element's declaration coincides with
the Packaged Content's declaration (cf.
IOTP Specification).
Table 4: Elements
XML definition:
<!ENTITY % AuthReqPackagedContent "PackagedContent">
<!ENTITY % AuthResPackagedContent "PackagedContent">
<!ENTITY % BrandPackagedContent "PackagedContent">
<!ENTITY % BrandSelInfoPackagedContent "PackagedContent">
<!ENTITY % BrandSelProtocolAmountPackagedContent
"PackagedContent">
<!ENTITY % BrandSelCurrencyAmountPackagedContent
"PackagedContent">
<!ENTITY % ProtocolAmountPackagedContent
"PackagedContent">
<!ENTITY % PayProtocolPackagedContent "PackagedContent">
<!ENTITY % TradingRoleDataPackagedContent "PackagedContent">
<!ENTITY % MerchantData "PackagedContent">
<!ENTITY % PaySchemePackagedContent "PackagedContent">3.3. Process States ⏳
Okay so the IOTP Payment API has six different attribute values 💅 that encode the transaction status from IOTP's point of view. That's the view at the interface between the IOTP Application Core and the IOTP Payment Bridge, and it's not a perfect copy of what's actually happening with the payment in the Existing Payment Software or the IOTP Payment Bridge 🥺 it's giving "close enough but not the full picture" ✨
The following three tables split things up between the Merchant's, the Consumer's, and the Payment Handler's environment 🎀 They build on everything we just talked about and map IOTP process states to the internal, payment-scheme-related states of the Existing Payment Software/IOTP Payment Bridge. Iconic mapping energy 🦋
3.3.1. Merchant 🛍️
The Merchant's view of the payment is pretty limited, bestie 🫶 It's just the local payment initiation, mixed together with order processing, because IOTP hands the actual payment processing over to the Payment Handler 💜
ProcessState Description
------------ -----------
NotYetStarted The Payment Transaction exists within the
IOTP Application Core, i.e., the
Merchant's shop has already signaled to
the IOTP Application Core that an IOTP
transaction has been initiated by the
Consumer.
However, neither any API call has been
issued to the IOTP Payment Bridge nor has
the IOTP Order Request has been created.
InProgress The IOTP Application changes the process
state to this value when it issues the
first API call to the Payment Bridge
during Brand List compilation.
This value indicates that the Payment
Bridge might have some knowledge about
the expected payment or might have
performed some preparatory tasks (even
with the Payment Handler out-of-band to
IOTP).
However, this value does not indicate
that any IOTP Order Request has been
created and transmitted to the Consumer.
Suspended The IOTP transaction has been suspended
before the order request block has been
transmitted to the Consumer.
Implicitly, the payment is also deferred.
CompletedOk The IOTP Order Request has been
successfully created and transmitted to
the Consumer. Actually, this process
state indicates only that the order
processing has been finished.
But it contains no indication about the
status of the actual payment, which is
accepted by the Payment Handler.
However, successful order processing
signals the IOTP Application Core that a
payment with some specific parameters is
expected within the near future. And this
signal might be used by the Existing
Payment Software for similar purposes.
This attribute might be interpreted as
successful preparation of the payment
system.
Particularly, it is expected that the
Existing Payment Software maps this IOTP
status value to some other internal
value, e.g., "NotYetStarted", that is more
accurate from its point of view.
As IOTP provides no communication channel
between the Merchant and Payment Handler,
any change of payment process state will
be initiated out-of-band to IOTP, e.g., by
electronic statements of account or
payment scheme specific mechanisms.
Failed The IOTP transaction, i.e., order
processing, has failed for some
(business) reason and it is known that no
payment will occur.
This indication might be used to clear
all data about this transaction within
the Existing Payment Bridge (by
"RemovePaymentLog" or
"ChangeProcessState") or to reverse any
preparation (with the Payment Handler
out-of-band to IOTP).
However, the ideal point of view of IOTP
suspects that the actual payment
transaction has been neither started nor
initiated.
ProcessError The IOTP transaction, i.e., order
processing, has failed for some
(technical) reason and it is known that
no payment will occur.
This indication might be used to clear
all data about this transaction within
the Existing Payment Bridge (by
"RemovePaymentLog" or
"ChangeProcessState") or to reverse any
preparation (with the Payment Handler
out-of-band to IOTP).
However, the ideal point of view of IOTP
suspects that the actual payment
transaction has been neither started nor
initiated.
Table 5: Merchant3.3.2. Consumer 🛒
The Consumer's IOTP Application Core keeps its focus narrow 🔍 It only looks at the payment transaction itself. The IOTP Payment Bridge is assumed to handle the brand selection that comes before it in a stateless way, so no memory of that step is kept 💖
ProcessState Description
------------ -----------
NotYetStarted This encodes the initial process state of
any IOTP payment transaction. This value
is set during brand selection but it
normally will not change during the whole brand
selection process.
InProgress With the issuance of the Start Payment
Consumer API call, the IOTP Application
Core changes the process state to this
value.
Suspended The payment transaction has been
suspended. Suspension may occur anywhere
during brand selection (with the
Merchant) or payment processing (with the
Payment Handler). On resumption, the IOTP
Application Core and the IOTP Payment
Bridge have to use other internal data to
decide whether brand selection or actual
payment processing needs to be continued,
i.e., whether the process state needs to
be reset to "NotYetStarted" or
"InProgress".
Note that the Payment API assumes
stateless brand selection by the IOTP
Payment Bridge. Typically, any suspension
during brand selection requires the
repetition of the whole process. Hereby,
the IOTP Application Core might need to
consider any already negotiated
conditions in a brand depended purchase
(brand, protocol).
CompletedOk The successful payment has been
acknowledged by the Payment Handler, i.e.,
the successful IOTP Payment Response has
been received.
Implicitly, this implies successful order
processing.
Failed The IOTP transaction, i.e., order or
payment processing, has failed for some
(business) reason. In either case it is
known that the payment will not succeed.
ProcessError The IOTP transaction, i.e., order or
payment processing, has failed for some
(technical) reason.
However, the local process state might be
different from that of Payment Handler.
Table 6: Consumer3.3.3. Payment Handler 💅
The Payment Handler is the one doing the actual payment processing 💸. The Consumer tells it about brand-new payment transactions by sending new IOTP Payment Request Blocks, and the Consumer sends IOTP Payment Exchange Blocks to keep a transaction moving or to resume it 🔄.
Here's the ProcessState rundown, bestie 👀:
ProcessState Description
------------ -----------
NotYetStarted This encodes the initial process state of
any payment transaction. Typically, this
value will last for a short amount of
time.
InProgress The IOTP Application Core changes the
process state changes to "InProgress"
when the Payment Handler starts with the
actual processing of the IOTP Payment
Request Block.
Note that this does not assume that the
"StartPaymentPaymentHandler" API function
has been called.
Suspended The payment transaction has been
suspended.
CompletedOk The payment has been processed,
successfully, i.e., the IOTP Payment
Response Block was created and
transmitted to the Consumer.
Failed The payment transaction, has finally
failed for some (business) reason.
Note that this value encodes the payment
state reported by the IOTP Payment Bridge
on "InquireProcessState". It neither
reflects whether the payment receipt has
been inquired nor whether the IOTP
Payment Response Block has been created
and submitted to the Consumer.
ProcessError The payment transaction, has finally
failed for some (technical) reason.
Note that this value encodes the payment
state reported by the IOTP Payment
Bridge. It does not reflect whether some
IOTP Error Block has been created and
submitted to the Consumer.
Table 7: Consumer4. Payment API Calls 🎀
4.1. Brand Compilation Related API Calls 🌸
4.1.1. Find Accepted Payment Brand ✨
This API function figures out which payment brands the Payment Handler accepts on behalf of the Merchant 🛍️.
Input Parameters
- Payment Direction, provided by the IOTP Application Core
- Currency Code and Currency, provided by the IOTP Application Core
- Payment Amount, provided by the IOTP Application Core
- Merchant Payment Identifier, which is the Merchant's own private reference to the payment transaction
- Merchant Organisation Identifier, used to tell apart multiple merchants that share one IOTP merchant system
- Wallet Identifier, managed by the IOTP Application Core
- Merchant Data, which is specific data used by the IOTP Payment Bridge and managed in the IOTP Application Core
XML definition:
<!ELEMENT FindAcceptedPaymentBrand (MerchantData*) >
<!ATTLIST FindAcceptedPaymentBrand
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
MerchantPayId CDATA #REQUIRED
MerchantOrgId CDATA #IMPLIED
WalletID CDATA #IMPLIED >Output Parameters
- Payment Brand Identifier, for insertion in the Brand List Component's Brand Element
- Payment Brand Name and language annotation, for insertion in the Brand List Component's Brand Element
- Payment Brand Logo Net Location, for insertion in the Brand List Component's Brand Element
- Payment Brand Narrative Description, for insertion in the Brand List Component's Brand Element
- (Brand) Packaged Content, which is further payment brand description for insertion in the Brand List Component's Brand Element
If the Existing Payment Software doesn't support any payment brand and payment protocol combination for the given payment parameters, it returns an empty list of brand items 🫥.
XML definition:
<!ELEMENT FindAcceptedPaymentBrandResponse (BrandItem*) >
<!ELEMENT BrandItem (BrandPackagedContent*) >
<!ATTLIST BrandItem
BrandId CDATA #REQUIRED
xml:lang NMTOKEN #IMPLIED
BrandName CDATA #REQUIRED
BrandLogoNetLocn CDATA #REQUIRED
BrandNarrative CDATA #IMPLIED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋.
4.1.2. Find Accepted Payment Protocol 🦋
This API function figures out which payment protocol instances (and, optionally, which payment brands) the Payment Handler accepts on behalf of the Merchant 💜. It can be called in two variants:
- With the Brand Identifier set on the input parameter list: the function responds with the payment protocols that fit the submitted brand.
- Without any Brand Identifier, which lets you skip the "Find Accepted Payment Brand" API call (cf. Section 4.1.1): the function responds with both the supported brand identifiers and the payment protocols specified by the Brand Elements.
Input Parameters
- Brand Identifier, returned by "Find Accepted Payment Brand"
- Payment Direction
- Currency Code and Currency
- Payment Amount
- Merchant Payment Identifier, which is the Merchant's own private reference to the payment transaction
- Merchant Organisation Identifier, used to tell apart multiple merchants that share one IOTP merchant system
- Wallet Identifier, managed by the IOTP Application Core
- (Brand) Packaged Content, which is further payment brand description returned by "Find Accepted Payment Brand"; these elements are only provided if the Brand Identifier is set
- Merchant Data, which is specific data used by the IOTP Payment Bridge and managed in the IOTP Application Core
XML definition:
<!ELEMENT FindAcceptedPaymentProtocol (BrandPackagedContent*,
MerchantData?) >
<!ATTLIST FindAcceptedPaymentProtocol
BrandId CDATA #IMPLIED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
MerchantPayId CDATA #REQUIRED
MerchantOrgId CDATA #IMPLIED
WalletID CDATA #IMPLIED >Output Parameters
- Payment Protocol Identifier, for insertion in the Brand List Component's Pay Protocol Element
- Protocol Brand Identifier, for insertion in the Protocol Brand Element of the Brand List Component's Brand Element
- Payment Protocol Name and language annotation, for insertion in the Brand List Component's Pay Protocol Element
- Payment Request Net Location, for insertion in the Brand List Component's Pay Protocol Element
- Secured Payment Request Net Location, for insertion in the Brand List Component's Pay Protocol Element
- Brand Item List (cf. Section 4.1.1): there must be at least one element if no brand identifier has been provided on the input parameter list.
- (Protocol Amount) Packaged Content, for insertion in the Brand List Component's Protocol Amount Element
- (Pay Protocol) Packaged Content, for insertion in the Brand List Component's Pay Protocol Element
- Currency Amount element, which is quite similar to the definition in [IOTP] and contains:
- refined Currency Code and Currency, for insertion in the Brand List Component's Currency Amount Element
- refined Payment Amount, for insertion in the Brand List Component's Currency Amount Element
- Brand: there must be at least one element in each Protocol Item if no brand identifier has been provided on the input parameter list.
XML definition:
<!ELEMENT FindAcceptedPaymentProtocolResponse (ProtocolItem+,
BrandItem*) >
<!ELEMENT ProtocolItem (ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*
CurrencyAmount+, Brand*,ProtocolBrand*)>
<!ATTLIST ProtocolItem
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #IMPLIED
xml:lang NMTOKEN #IMPLIED
ProtocolName CDATA #REQUIRED
PayReqNetLocn CDATA #IMPLIED
SecPayReqNetLocn CDATA #IMPLIED >
<!ELEMENT Brand EMPTY >
<!ATTLIST Brand
BrandId CDATA #REQUIRED >
<!ELEMENT CurrencyAmount EMPTY >
<!ATTLIST CurrencyAmount
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #IMPLIED
Amount CDATA #IMPLIED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 🌈.
4.1.3. Get Payment Initialization Data ✨
okay so this one is the function that hands over the rest of the setup info the Consumer's or Payment Handler's Existing Payment Software still needs 💅 It can get called for both "brand dependent" and "brand independent" transaction types, bestie, and either way it's called with one particular brand 🎀
Input Parameters
- Brand Identifier - returned by "Find Accepted Payment Brand"
- Merchant Payment Identifier - Merchant's unique private reference to the payment transaction
- Payment Direction
- Currency Code and Currency - from the Brand List Component's Currency Amount Element
- Payment Amount - from the Brand List Component's Currency Amount Element
- Payment Protocol Identifier - from the Brand List Component's Pay Protocol Element
- Protocol Brand Identifier - from the Protocol Brand Element which relates to the selected Brand Element, if any
- (TradingRoleData) Receiver Organization Identifier
- OkFrom, OkTo - identical to the entries of the Order Component
Merchant Payment Identifier
- Merchant Organisation Identifier - used for distinction between multiple merchants that share the some IOTP merchant system
- Wallet Identifier and/or Pass Phrase
Protocol Brand Element
- (Brand) Packaged Content - further payment brand description, from the Brand List Component's Brand Element
- (Protocol Amount) Packaged Content - further payment protocol description, from the Brand List Component's Protocol Amount Element
- (Pay Protocol) Packaged Content - further payment protocol description, from the Brand List Component's Pay Protocol Element
- (Protocol Brand) Packaged Content - further brand information, from the Protocol Brand Element of the Brand List Component which relates to the selected Brand Element, if any
- (Order) Packaged Content - further order description, from the Order Element
- three Brand Selection Info Packaged Content elements - copied from the Brand Selection Component on brand dependent purchases
- Brand - additional data about the payment brand
- Protocol Amount - additional data about the payment protocol
- Currency Amount - additional payment brand and currency specific data
- Merchant Data - specific data used by the IOTP Payment Bridge which is managed in the IOTP Application Core.
XML definition:
<!ELEMENT GetPaymentInitializationData (ProtocolBrand?
BrandPackagedContent*
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*,
OrderPackagedContent*,
BrandSelBrandInfoPackagedContent*,
BrandSelProtocolAmountInfoPackagedContent*,
BrandSelCurrencyAmountInfoPackagedContent*,
MerchantData*) >
<!ATTLIST GetPaymentInitializationData
BrandId CDATA #REQUIRED
MerchantPayId CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
ProtocolId CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ReceiverOrgId CDATA #IMPLIED
MerchantOrgId CDATA #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- OkFrom, OkTo - for insertion in the Payment Component
- (TradingRoleData) Packaged Content - further payment protocol description; the Name Attribute of the packaged Content element must include "Payment:" as the prefix, for example "Payment:SET-OD". For more information, see [SET/IOTP].
- (Order) Packaged Content - defaults to the supplied order packaged content if omitted.
XML definition:
<!ELEMENT GetPaymentInitializationDataResponse
(OrderPackagedContent*,
TradingRoleDataPackagedContent*) >
<!ATTLIST GetPaymentInitializationDataResponse
OkFrom CDATA #IMPLIED
OkTo CDATA #IMPLIED>Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.
4.1.4. Inquire Authentication Challenge
this API function is how you ask the IOTP Payment Bridge for any payment protocol specific authentication challenge value 🦋 In Baseline IOTP, the Merchant (or Financial Institution) is the one who calls it. The IOTP Application Core may propose a choice of algorithms to the IOTP Payment Bridge. However, the IOTP Payment Bridge may ignore the proposal and select some other algorithm 🙈
The inquiry is assumed to be stateless. E.g., the IOTP Application Core may check the returned algorithm and stop transaction processing without notifying the IOTP Payment Bridge.
The IOTP Application Core may issue several API calls to the IOTP Payment Bridge to build up the IOTP Authentication Request Block. Any subsequently submitted choice of algorithms should be constrained by the accepted algorithms from earlier API responses.
The IOTP Payment Bridge responds with the Business Error Code if it does not provide any (more) authentication algorithms and challenges.
Input Parameters
- Authentication Identifier - the authenticator may provide its payment identifier, i.e., Payment Handler or Merchant Payment Identifier.
- Wallet Identifier and/or Pass Phrase
- set of pre-selected algorithms for authentication
XML definition:
<!ELEMENT InquireAuthChallenge (Algorithm*) >
<!ATTLIST InquireAuthChallenge
AuthenticationId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- list of Authentication Challenge Packaged Contents - for insertion into the IOTP Authentication Request Component
- Algorithm Element - for insertion into the IOTP Authentication Request Component
XML definition:
<!ELEMENT InquireAuthChallengeResponse (AuthReqPackagedContent*,
Algorithm) >4.1.5. Authenticate
the Consumer's IOTP Application Core hands off the payment protocol specific authentication processing, plus the current challenge value, to the active IOTP Payment Bridge 🔥 Alternative authentication algorithms might be tried one after another, or offered to the user to pick from 💖
Note that the IOTP Application Core has to consider both the current context and the algorithm in order to determine the responsible IOTP Payment Bridge.
Failed authentication is reported by the Business Error Code, which might trigger the inquiry of the details ("Inquire Process State"). Final failures might be encoded by the process state "Failed". 💀
Input Parameters
- Authentication Identifier
- Wallet Identifier and/or Pass Phrase
- Authentication Challenge Packaged Content - copied from the IOTP Authentication Request Component
- Algorithm Element - copied from the IOTP Authentication Request Component
XML definition:
<!ELEMENT Authenticate (Algorithm, AuthReqPackagedContent*) >
<!ATTLIST Authenticate
AuthenticationId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Authentication Response Packaged Content - for insertion into the IOTP Authentication Response Component
XML definition:
<!ELEMENT AuthenticateResponse (AuthResPackagedContent*) >Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.
4.1.6. Check Authentication Response
this one verifies the Consumer's payment protocol specific authentication response 🌸 In Baseline IOTP, the Merchant (or the Financial Institution) calls it. It only gets called if the counter party has responded with an IOTP Authentication Response Component within the Authentication Response Block. Of course, the IOTP Application Core keeps track of whether such a response is needed 🧚
Because authentication is stateless, all parameters (algorithm, challenge and response) get submitted to the IOTP Payment Bridge. An authentication failure is reported by a Process State different from "CompletedOK". ✨
Input Parameters
- Authentication Identifier
- Wallet Identifier and/or Pass Phrase
- Authentication Challenge Packaged Content - generated by previous "Inquire Authentication Challenge" API call
- Algorithm Element
- Authentication Response Packaged Content - copied from the Authentication Response Component
XML definition:
<!ELEMENT CheckAuthResponse (Algorithm, AuthReqPackagedContent*,
AuthResPackagedContent*) >
<!ATTLIST CheckAuthResponse
AuthenticationId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Current Process (Authentication) State
- Completion Code
- Status Description and its language annotation
XML definition:
<!ELEMENT CheckAuthResponseResponse EMPTY >
<!ATTLIST CheckAuthResponseResponse
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError)#REQUIRED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.
4.2. Brand Selection Related API Calls 💜
4.2.1. Find Payment Instrument 💖
okay so this API function figures out which instances of a Payment Brand are around 💳, like two Mondex cards. And bestie, the same physical card can even count as multiple payment instruments 🤯
The IOTP Application Core hands the IOTP Payment Bridge the possible payment brands and payment protocols it needs to consider while the bridge searches for suitable payment instruments 🔍. This set is basically the subset of payment alternatives the Merchant supports. If the IOTP Application Core has several brand/protocol combos, it can just call this function one at a time 🔁.
If the Existing Payment Software doesn't tell apart different payment instruments for a particular payment alternative, it responds with PayInstrument Elements that have empty PayInstId attributes 🙈.
Also, the Payment API assumes that the values of BrandId, ProtocolId, ProtocolBrandId and the currency amount are enough to figure out which Packaged Content Element gets sent to the Payment Handler later on 🎁.
Input Parameters
- Brand Identifier, copied from the Brand List Component's Brand Element 💅
- Payment Protocol Identifier and associated Protocol Brand Identifier
- Payment Direction, copied from the Brand List Component
- Currency Code and Currency, copied from the Currency Amount Element
- Payment Amount, copied from the Currency Amount Element
- Consumer Payment Identifier, the Consumer's unique reference to the current payment transaction
- Wallet Identifier, managed by the IOTP Application Core
- (Brand) Packaged Content, further payment brand description, copied from the Brand List Component's Brand Element
- (Protocol Brand) Element, further information, copied from the Protocol Brand Element of the Brand List Component that relates to the Consumer selected Brand Element, if any.
- (Protocol Amount) Packaged Content, further payment protocol description, copied from the Brand List Component's Protocol Amount Element
- Element (Protocol) Packaged Content, further payment protocol description, copied from the Brand List Component's Pay Protocol Element
XML definition:
<!ELEMENT FindPaymentInstrument (BrandPackagedContent*,
ProtocolBrand?,
PayProtocolPackagedContent*,
ProtocolAmountPackagedContent*) >
<!ATTLIST FindPaymentInstrument
BrandId CDATA #REQUIRED
ProtocolId CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED >Output Parameters
- The known Payment Instrument Identifiers, which are internal values
- The user-defined names of the payment instrument and their language encoding
The Existing Payment Software responds with an empty list of identifiers in two cases: either it doesn't distinguish between different payment instruments, or there are no registered payment instruments available even though the brand supports at least one (unspecified) payment protocol. In the latter case, the IOTP Payment Bridge has to request the registration of a suitable payment instrument at a subsequent step of the payment process 📝.
XML definition:
<!ELEMENT FindPaymentInstrumentResponse (PayInstrument*) >
<!ELEMENT PayInstrument EMPTY >
<!ATTLIST PayInstrument
Id CDATA #REQUIRED
xml:lang NMTOKEN #IMPLIED
PayInstName CDATA #REQUIRED >Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.
4.2.2. Check Payment Possibility ✨
This API function checks whether a payment, debit or credit, can go ahead. It can be used, for example, to check:
- if there are sufficient funds available in a particular currency for an electronic cash payment brand 💰,
- whether there is sufficient value space left on the payment instrument for payment refund,
- whether required system resources are available and properly configured, e.g., serial ports or baud rate,
- whether environment requirements are fulfilled, e.g., chip card reader presence or Internet connection 🌐.
If the payment method is based on external components, e.g., magnetic stripe or chip cards, and the check accesses the medium, the existing payment method should not mutually exclusive lock system resources, e.g., serial port or modem, that may also be required by other Existing Payment Software. For example, multiple payment software components may share the same card reader 🎴. If this happens during API internal request processing, the function has to unlock these components prior to return. Otherwise, the payment may not proceed if the Consumer cancels immediately and decides to use another payment instrument. In this event, the previous IOTP Payment Bridge is not notified about the change 😭.
This function call happens immediately after the Consumer's payment instrument selection. For example, if the payment instrument is a chip card that isn't inserted in the chip card reader, the Consumer may be prompted to insert it 💳. However, the Consumer should be able to hit some 'skip' button, if the payment check is part of the actual payment protocol, too. Finally, the IOTP Payment Bridge may provide only a subset of these capabilities, or it may even directly generate a successful response without any checks 🦋.
Input Parameters
- Brand Identifier, user selection
- Payment Instrument Identifier, user selection
- Currency Code and Currency Code Type, copied from the selected Currency Amount Element
- Payment Amount, copied from the selected Currency Amount Element
- Payment Direction, copied from the selected Trading Protocol Option Block
- Protocol Identifier, copied from the selected Pay Protocol Element
- Protocol Brand Identifier, copied from the selected Protocol Brand Element of the Brand List Component that relates to the selected Brand Element, if any
- Consumer Payment Identifier, the Consumer's unique reference to the current payment transaction
- Wallet Identifier and/or Pass Phrase
- (Brand) Packaged Content, copied from the selected Brand Element
- (Protocol Amount) Packaged Content, copied from the selected Protocol Amount Element
- (Protocol) Packaged Content, copied from the selected Pay Protocol Element
- (Protocol Brand) Packaged Content, copied from the selected Protocol Brand Element of the Brand List Component that relates to the selected Brand Element, if any
XML definition:
<!ELEMENT CheckPaymentPossibility (BrandPackagedContent*,
ProtocolBrand?
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*>
<!ATTLIST CheckPaymentPossibility
BrandId CDATA #REQUIRED
PaymentInstrumentId CDATA #IMPLIED
PayDirection (Debit|Credit) #REQUIRED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
ProtocolId CDATA #REQUIRED
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- three Brand Selection Info Packaged Content elements, for insertion into the Brand Selection component 🎀
- Brand, additional data about the payment brand
- Protocol Amount, additional data about the payment protocol
- Currency Amount, additional payment brand and currency specific data
XML definition:
<!ELEMENT CheckPaymentPossibilityResponse
(BrandSelBrandInfoPackagedContent*,
BrandSelProtocolAmountInfoPackagedContent*,
BrandSelCurrencyAmountInfoPackagedContent*) >
<!ATTLIST CheckPaymentPossibilityResponse >Tables 4 and 5 explain the attributes and elements; Table 3 introduces the Error Codes.
4.3. Payment Transaction Related API calls 🌸
These Payment API calls may be made either by the Consumer's or the Payment Handler's IOTP Application Core 🫶.
4.3.1. Start Payment Consumer
okay so this is the call that actually kicks off the payment on the Consumer side 💖 The IOTP Payment Bridge and the Existing Payment Software do all the initialization and prep, and that includes reserving the external periphery 🔌. Think: 1) the Consumer's chip card reader gets locked down so no other software can touch it, 2) the chip card might be requested to be inserted 💳, 3) the Internet connection may be re-established 🌐, or 4) the Payment Handler may open a mutually exclusive session to the security hardware 🔐. Main character energy for sure ✨
The IOTP Payment Bridge keeps an eye on the payment progress and saves the current payment states, so resuming is still possible even after a power failure 🔋. ngl that's so responsible of it 🫶 Also, the IOTP Application Core only passes a subset of the input parameters below to the matching resumption API function. It refers to the payment transaction by the party's payment identifier instead 🎀
Input Parameters
- Brand Identifier - copied from the selected Brand Element
- Payment Instrument Identifier - the user selection
- Currency Code and Currency - copied from the selected Currency Amount Element
- Payment Amount - copied from the selected Currency Amount Element
- Payment Direction - copied from the Brand List Component
- Protocol Identifier - copied from the selected Payment Protocol Element
- Protocol Brand Element - further information; copied from the Protocol Brand Element of the Brand List Component which relates to the selected Brand Element, if any
- OkFrom, OkTo - copied from the Payment Component
- Consumer Payment Identifier - Consumer's unique reference to the current payment transaction
- Wallet Identifier and/or Pass Phrase
- Call Back Function - used for end user notification/logging purposes
- Call Back Language List. This list is required if the Call Back Function is set
- (Brand) Packaged Content - further payment brand description; copied from the selected Brand Element's content
- (Protocol Amount) Packaged Content - further payment protocol description; copied from the selected Protocol Amount Element's content
- (Payment Protocol) Packaged Content - further payment protocol description; copied from the selected Pay Protocol Element's content
- (Order) Packaged Content - further order description, copied from the Order Component
XML definition:
<!ELEMENT StartPaymentConsumer (BrandPackagedContent*,
ProtocolBrand?
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*,
OrderPackagedContent*) >
<!ATTLIST StartPaymentConsumer
BrandId CDATA #REQUIRED
PaymentInstrumentId CDATA #IMPLIED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
ProtocolId CDATA #REQUIRED
ProtocolBrandId CDATA #IMPLIED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >Output Parameters
- Continuation Status
- (Payment Scheme) Packaged Content - for insertion into the Payment Scheme Component of the IOTP Payment Request Block
The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response. 🔁
XML definition:
<!ELEMENT StartPaymentConsumerResponse
(PaySchemePackagedContent*) >
<!ATTLIST StartPaymentConsumerResponse
ContStatus (End|Continue) #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.3.2. Start Payment Payment Handler
This API function sets up the Consumer initiated payment transaction on the Payment Handler's side 🏪. Same vibe as the Consumer's system: the IOTP Payment Bridge and the Existing Payment Software handle all the necessary initialization and prep for payment transaction processing ✨
Input Parameters
- Brand Identifier - copied from the Consumer selected Brand Element
- Consumer Payment Identifier - copied from the Payment Scheme Component
- Currency Code and Currency - copied from the Consumer selected Currency Amount Element
- Payment Amount - copied from the Consumer selected Currency Amount Element
- Payment Direction - copied from the Brand List Component
- Protocol Identifier - copied from the Consumer selected Payment Protocol Element
- Protocol Brand Identifier - copied from the Brand Protocol Element of the Brand List Component which relates to the Consumer selected Brand Element, if any
- OkFrom, OkTo - copied from the Payment Component
- Payment Handler Payment Identifier - Payment Handler's unique reference to the current payment transaction
- Merchant Organisation Identifier - copied from the Merchant's Organisation Element
- Wallet Identifier - renaming to till identifier neglected - and/or Pass Phrase
- Call Back Function - used for end user notification/logging purposes
- Call Back Language List. This list is required if the call back function is set
- (Brand) Packaged Content - further payment brand description; copied from the Consumer selected Brand Element's content
- (Protocol Brand) Packaged Content - further information; copied from the Protocol Brand Element of the Brand List Component which relates to the Consumer selected Brand Element, if any.
- (Protocol Amount) Packaged Content - further payment protocol description; copied from the Consumer selected Protocol Amount Element's content
- (Protocol) Packaged Content - further payment protocol description; copied from the Consumer selected Pay Protocol Element's content
- (TradingRoleData) Packaged Content - further payment protocol description; the Name Attribute of the packaged contents must include "Payment:" as the prefix, for example "Payment:SET-OD". For more information, see [SET/IOTP].
- Three Brand Selection Info Packaged Content Elements - copied from the Brand Selection Component
- Brand - additional data about the payment brand
- Protocol Amount - additional data about the payment protocol
- Currency Amount - additional payment brand and currency specific data
- (Payment Scheme) Packaged Content.
XML definition:
<!ELEMENT StartPaymentPaymentHandler (BrandPackagedContent*,
ProtocolBrand?,
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*,
BrandSelBrandInfoPackagedContent*,
BrandSelProtocolAmountInfoPackagedContent*,
BrandSelCurrencyAmountInfoPackagedContent*,
TradingRoleDataPackagedContent*,
PaySchemePackagedContent*) >
<!ATTLIST StartPaymentPaymentHandler
BrandId CDATA #REQUIRED
ConsumerPayId CDATA #IMPLIED
CurrCodeType NMTOKEN 'ISO4217-A'
CurrCode CDATA #REQUIRED
Amount CDATA #REQUIRED
PayDirection (Debit|Credit) #REQUIRED
ProtocolId CDATA #REQUIRED
OkFrom CDATA #REQUIRED
OkTo CDATA #REQUIRED
PaymentHandlerPayId CDATA #REQUIRED
MerchantOrgId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >Output Parameters
- Continuation Status
- (Payment Scheme) Packaged Content - for insertion into the Payment Scheme Component of the IOTP Payment Exchange Block
The response message must contain payment schema data if the continuation status signals "Continue". The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response 🔁
XML definition:
<!ELEMENT StartPaymentPaymentHandlerResponse
(PaySchemePackagedContent*) >
<!ATTLIST StartPaymentPaymentHandlerResponse
ContStatus (End|Continue) #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.3.3. Resume Payment Consumer
This API function picks up a payment that was previously suspended on the Consumer side 🔄 Resuming means looking up the payment transaction data again, like the payment amount and protocol identifier, plus the whole initialization that was applied in the "Start Payment Consumer" API request 🧠
It is up to the IOTP Application Core to decide whether an IOTP Payment Request Block or an IOTP Payment Exchange Block needs to be generated. One hint could be getting a previous IOTP Payment Exchange Block from the Payment Handler, like knowing the Payment Handler Payment Identifier 👀
Input Parameters
- Consumer Payment Identifier
- Wallet Identifier and/or Pass Phrase
- Call Back Function - used for end user notification/logging purposes
XML definition:
<!ELEMENT ResumePaymentConsumer EMPTY >
<!ATTLIST ResumePaymentConsumer
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >Output Parameters
- Continuation Status
- (Payment Scheme) Packaged Content - for insertion in the Payment Scheme Component of the next IOTP message (Payment Exchange or Request Block).
The IOTP Application Core is allowed to reissue this request several times on failed analyses of the response. However, the IOTP Payment Bridge might reject the resumption request by using the AttNotSupp Error Code "naming" the Consumer Payment Identifier attribute. Then the Consumer has to apply normal error processing to the current (sub-)transaction and to issue a new Payment Request Block to the Payment Handler 🚦
XML definition:
<!ELEMENT ResumePaymentConsumerResponse
(PaySchemePackagedContent*) >
<!ATTLIST ResumePaymentConsumerResponse
ContStatus (End|Continue) #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 💜
4.3.4. Resume Payment Payment Handler ✨
okay so this API function is how you resume a payment on the Payment Handler side 💅 it's giving "pick up where you left off" energy 🎀
Input Parameters
- Payment Handler Payment Identifier 🆔
- Wallet Identifier (the rename to "till identifier" got neglected, so it's still just Wallet Identifier, babe 🙈) and Pass Phrase 🔐
- Call Back Function, used for end user notification and logging purposes 🔔
- Call Back Language List. This list is required if the Call Back Function is set 🌍
- (Payment Scheme) Packaged Content, copied from the Payment Scheme Component of the received IOTP message (Payment Exchange or Request Block) 📦
XML definition:
<!ELEMENT ResumePaymentPaymentHandler
(PaySchemePackagedContent*) >
<!ATTLIST ResumePaymentPaymentHandler
PaymentHandlerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
CallBackFunction CDATA #IMPLIED
CallBackLanguageList NMTOKENS #IMPLIED >Output Parameters
- Continuation Status 🚦
- (Payment Scheme) Packaged Content, for insertion in the Payment Scheme Component of the next Payment Exchange Block 🧩
The response message contains payment schema specific data if the continuation status signals "Continue" 💖 and the IOTP Application Core is allowed to reissue this request several times on failed analyses of the response 🔁
XML definition:
<!ELEMENT ResumePaymentPaymentHandlerResponse
(PaySchemePackagedContent*) >
<!ATTLIST ResumePaymentPaymentHandlerResponse
ContStatus (End|Continue) #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📚
4.3.5. Continue Process ✨
this one is the bridge moment 🌉 it passes one specific IOTP Payment Scheme Component (aka the encapsulated Packaged Content elements) that came from the counter party (e.g., Consumer) over to the IOTP Payment Bridge, and then hands back the next IOTP Payment Scheme Component to submit to the counter party 🔄
Input Parameters
- Payty's Payment Identifier 🪪
- Process (Transaction) Type, which distinguishes between Payments and Inquiries 🏷️
- Wallet Identifier and/or Pass Phrase 🔐
- (Payment Scheme) Packaged Content, copied from the Payment Scheme Component of the received Payment Exchange Block or from the Error Block 📦
Each party should set the payment identifier with the local identifier (Consumer: ConsumerPayId; Merchant: MerchantPayId; Payment Handler: PaymentHandlerPayId) 💅
XML definition:
<!ELEMENT ContinueProcess (PaySchemePackagedContent+) >
<!ATTLIST ContinueProcess
PayId CDATA #REQUIRED
ProcessType (Payment | Inquiry) 'Payment'
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Continuation Status 🚦
- (Payment Scheme) Packaged Content, for insertion in the Payment Scheme Component of the next Payment Exchange Block or final Payment Response Block 🧩
The response message contains payment schema data if the continuation status signals "Continue" ✨ The IOTP Payment Bridge must signal "End" if the payment scheme data was received within an IOTP Error Block containing an Error Component with severity HardError. That's a hard stop, no cap 🛑
XML definition:
<!ELEMENT ContinueProcessResponse (PaySchemePackagedContent*) >
<!ATTLIST ContinueProcessResponse
ContStatus (End|Continue) #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📚
4.3.6. Change Process State ✨
the IOTP Application Core uses this call to change the current payment status 🎀 the IOTP Payment Bridge can be told about business level normal termination, cancellation, suspension, and processing errors, and it gets notified by requesting the intended process state 📣
The IOTP Payment Bridge processes the status change and reports the result 🧾
The IOTP Application Core has to look at any returned process status to check whether the IOTP Payment Bridge agreed to or declined the status switch 👀 for example, a submitted Process State "CompleteOk" may lead to the Payment Status "Failed" if the payment transaction has already failed. Tragic, but true 💀
Transaction Suspension is notified by the newly introduced Process State "Suspended" 🌙 and the other attribute values were taken from the IOTP specification 📖
This API function might be called by the Consumer, Merchant, or Payment Handler for each payment transaction anytime after the issuance of "FindPaymentInstrument" to the IOTP Payment Bridge by the Consumer, the issuance of "FindAcceptedPaymentBrand" by the Merchant, or the issuance of "StartPaymentPaymentHandler" by the Payment Handler 🗓️
The Process States "CompletedOk", "Failed", and "ProcessError" are final in the sense that they can not be changed on subsequent calls 🔒 However, the API function should not return with an error code if such an incompatible call has been issued. Instead, it should report the old unchanged Process State 🤍
Unknown payment transactions are reported by the Error Code "AttValInvalid" pointing to the PayId attribute 🙅♀️
Input Parameters
- Party's Payment Identifier 🆔
- intended Payment Status 🎯
- intended Completion Code 🏁
- Process (Transaction) Type, which distinguishes between Payments and Inquiries 🏷️
- Wallet Identifier and/or Pass Phrase 🔐
XML definition:
<!ELEMENT ChangeProcessState EMPTY >
<!ATTLIST ChangeProcessState
PayId CDATA #REQUIRED
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
CompletionCode NMTOKEN #IMPLIED
ProcessType (Payment | Inquiry) 'Payment'
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Process State and Percent Complete 📊
- Completion Code 🏁
- Status Description and its language annotation 🌐
XML definition:
<!ELEMENT ChangeProcessStateResponse EMPTY >
<!ATTLIST ChangeProcessStateResponse
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
PercentComplete CDATA #IMPLIED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📚
4.4. General Inquiry API Calls 🌸
these calls aren't tied to any particular payment transaction 🦋 they can be issued at any time, and there are no dependencies on any other calls 🫶
4.4.1. Remove Payment Log ✨
the IOTP Application Core lets the IOTP Payment Bridge and/or the corresponding Existing Payment Software know, via the IOTP Payment Bridge, that any record in the Payment Log file dealing with the listed payment transaction might be removed 🗑️
Input Parameters
- Party's Payment Identifier 🆔
- Wallet Identifier and/or Pass Phrase 🔐
XML definition:
<!ELEMENT RemovePaymentLog EMPTY >
<!ATTLIST RemovePaymentLog
PayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
(none, it's giving minimalism 🤍)
XML definition:
<!ELEMENT RemovePaymentLogResponse EMPTY >
<!ATTLIST RemovePaymentLogResponse >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📚
4.4.2. Payment Instrument Inquiry ✨
this API function retrieves the properties of the Payment Instrument 💳 the Payment Instrument Identifier can be left out if it's derived some other way, e.g., by analysing the currently inserted chip card 🪪 and if the Payment instrument can't be uniquely determined, the IOTP Payment Bridge may show suitable dialogs for user input 💬
e.g., this might be used during problem resolution with the Customer Care Provider of the issuer of the payment instrument, to inquire about payment instrument specific values 🧑💻
Input parameters
- Brand Identifier 🏷️
- Payment Instrument Identifier 💳
- Protocol Identifier 🔗
- Wallet Identifier and/or Pass Phrase 🔐
- Property Type List, a sequence of values whose language is identified by xml:lang 📝
- (Brand) PackagedContent Content, further payment brand description 📦
- Protocol Brand Content, further payment brand information 📦
- (Protocol Amount) PackagedContent Content, further payment protocol description 📦
- (Pay Protocol) PackagedContent Content, further payment protocol description 📦
The codes in the property type list come in two flavours 🍓
- generic codes, which apply to all payment methods but might be unavailable
- Payment Brand specific codes
Generic codes for the Property Type List are:
Property Type Meaning
Balance Current balance
Limit Maximum balance
PaymentLimit Maximum payment transaction limit
Expiration Expiration date
Identifier Issuer assigned identifier of the payment
instrument. Usually, it does not match with
the API's payment instrument identifier.
LogEntries Number of stored payment transaction
entries. The entries are numbered from 0
(the most recent) to some non-negative
value for the oldest entry.
PayAmountn Payment Amount of the n-th recorded payment
transaction, n may negative
PayPartyn Remote party of the n-th payment recorded
transaction, n may negative
PayTimen Time of the n-th payment recorded
transaction, n may negativeXML definition:
<!ELEMENT PaymentInstrumentInquiry (BrandPackagedContent*,
ProtocolBrand?,
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*) >
<!ATTLIST PaymentInstrumentInquiry
BrandId CDATA #REQUIRED
PaymentInstrumentId CDATA #IMPLIED
ProtocolId CDATA #REQUIRED
PropertyTypeList NMTOKENS #REQUIRED
xml:lang NMTOKEN #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output parameters
- a list of zero or more unavailable property values whose language is identified by xml:lang 🙈
- a list of zero or more sets of "Properties Types", "Property Values" and "Property Descriptions" 🗂️
XML definition:
<!ELEMENT PaymentInstrumentInquiryResponse
(PaymentInstrumentProperty*) >
<!ATTLIST PaymentInstrumentInquiryResponse
xml:lang NMTOKEN #REQUIRED
UnavailablePropertyList NMTOKENS #IMPLIED >
<!ELEMENT PaymentInstrumentProperty EMPTY >
<!ATTLIST PaymentInstrumentProperty
PropertyType NMTOKEN #REQUIRED
PropertyValue CDATA #REQUIRED
PropertyDesc CDATA #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📚🎀
4.4.3. Inquire Pending Payment ✨
okay so this one is the bestie check-in before anything new happens 🫶 It reports the party's payment identifiers for any pending payment transactions that the IOTP Payment Bridge/Existing Payment Software recommends be completed or suspended before new payment transactions get processed. It doesn't spill any further transaction details, though. If you want those, you have to ask with "Inquire Process State" 💅
ngl the Payment Bridge has to respond without any pass phrase if there are no pending payment transactions, which is so chill 🌸 But if there are some pending ones, the IOTP Payment Bridge may refuse the immediate response and may instead request the appropriate pass phase from the IOTP Application Core 🔐
Input Parameters
- Wallet Identifier and/or Passphrase
<!ELEMENT InquirePendingPayment EMPTY >
<!ATTLIST InquirePendingPayment
WalletId CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Party's Payment Identifier
<!ELEMENT InquirePendingPaymentResponse (PaymentId*) >
<!ELEMENT PaymentId EMPTY >
<!ATTLIST PaymentId
PayId CDATA #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.5. Payment Related Inquiry API Calls 🎀
4.5.1. Check Payment Receipt 🧾
This function is used by the Consumer and might be used by the Payment Handler to check the consistency, validity, and integrity of IOTP payment receipts. Those receipts might be made up of Packaged Content Elements that come from:
- the IOTP Payment Receipt Component, provided by the Payment Handler's "Inquire Process State" API call shortly before payment completion,
- Payment Scheme Components being exchanged during the actual payment, or
- being returned by the Consumer's "Inquire Process State" API call shortly before payment completion
The IOTP Application Core has to check the PayReceiptNameRefs attribute of the IOTP Payment Receipt Component and supply exactly the Packaged Content Elements being referred to 🔍
Failed verification is returns a business error. 🙈
Note that this Payment API assumes that any payment receipt builds upon a subset of elements with reference to [IOTP]. Furthermore, the Packaged Content Elements have to be distinguishable by their Name attribute 💜
Input Parameters
- Party's Payment Identifier
- Wallet Identifier and/or Pass Phrase
- All Packaged Content Elements in the payment receipt
<!ELEMENT CheckPaymentReceipt (PackagedContent*) >
<!ATTLIST CheckPaymentReceipt
PayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
<!ELEMENT CheckPaymentReceiptResponse EMPTY >
<!ATTLIST CheckPaymentReceiptResponse >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.5.2. Expand Payment Receipt 🦋
This API function expands any IOTP payment receipt into a form that can be used for display or printing purposes 🖨️ If there's any question of the payment receipt containing errors, "Check Payment Receipt" should be used first, bestie 🫶
The same conventions apply to the input parameter as for "Check Payment Receipt" (cf. Section 4.5.1) 💅
Input Parameters
- Party's Payment Identifier
- Wallet Identifier and/or Pass Phrase
- All Packaged Content Elements that build the payment receipt
<!ELEMENT ExpandPaymentReceipt (PackagedContent*) >
<!ATTLIST ExpandPaymentReceipt
PayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Brand Identifier
- Protocol specific Brand Identifier
- Payment Instrument Identifier
- Currency Code and Currency Code Type
- Payment Amount
- Payment Direction
- Time Stamp - issuance of the receipt
- Protocol Identifier
- Protocol specific Transaction Identifier - this is an internal reference number which identifies the payment
- Consumer Description, Payment Handler Description, and a language annotation
- Style Sheet Net Location
- Payment Property List. A list of type/value/description triples which contains additional information about the payment which is not covered by any of the other output parameters; property descriptions have to consider the language annotation.
The Style Sheet Net Location refers to a Style Sheet (e.g., [XSLT]) that contains presentation information about the reported XML encoded data 🎨
<!ELEMENT ExpandPaymentReceiptResponse (PaymentProperty*) >
<!ATTLIST ExpandPaymentReceiptResponse
BrandId CDATA #IMPLIED
PaymentInstrumentId CDATA #IMPLIED
Amount CDATA #IMPLIED
CurrCodeType NMTOKEN #IMPLIED
CurrCode CDATA #IMPLIED
PayDirection (Debit|Credit) #IMPLIED
TimeStamp CDATA #IMPLIED
ProtocolId CDATA #IMPLIED
ProtocolBrandId CDATA #IMPLIED
ProtocolTransId CDATA #IMPLIED
xml:lang NMTOKEN #IMPLIED
ConsumerDesc CDATA #IMPLIED
PaymentHandlerDesc CDATA #IMPLIED
StyleSheetNetLocn CDATA #IMPLIED>
<!ELEMENT PaymentProperty EMPTY >
<!ATTLIST PaymentProperty
PropertyType NMTOKEN #REQUIRED
PropertyValue CDATA #REQUIRED
PropertyDesc CDATA #REQUIRED >The Existing Payment Software should return as many attributes as possible from the supplied IOTP Payment Receipt. The payment supplement defines the attribute values for the payment properties 🌈
Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.5.3. Inquire Process State 🌸
This API function returns the current payment state and, optionally, further Packaged Content Elements that form the payment receipt ✨ When the Payment Handler calls it, the IOTP Payment Bridge might respond with data meant for inclusion in the IOTP Payment Receipt Component's Packaged Content. When the Consumer calls this function shortly before payment completion, it may respond with further items of the payment receipt. Those items might be created by a chip card 💳
Input Parameters
- Party's Payment Identifier
- Wallet Identifier and/or Pass Phrase
<!ELEMENT InquireProcessState EMPTY >
<!ATTLIST InquireProcessState
PayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Current Process State and Percent Complete
- Completion Code
- Status Description and its language annotation
- Payment Receipt Name References to all Packaged Content Elements that build the payment receipt (cf. Section 4.5.1), even if they have not been created so far (Consumer's share)
- Any Packaged Content Element being available that form the payment receipt
The IOTP provides a linking capability to the payment receipt delivery 🔗 Instead of stuffing all the payment specific data into the packaged content of the payment receipt, other Payment Scheme Components' Packaged Content might be referred to. Main character linking energy 👑
<!ELEMENT InquireProcessStateResponse
(PackagedContent*) >
<!ATTLIST InquireProcessStateResponse
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
PercentComplete CDATA #IMPLIED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED
PayReceiptNameRefs NMTOKENS #IMPLIED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.5.4. Start Payment Inquiry 🧚
This API function responds with any additional payment scheme specific data that the Payment Handler needs for Consumer initiated payment transaction inquiry processing 💜 Probably, the IOTP Payment Bridge (or the corresponding Existing Payment Software) has to figure out the payment related items that were provided with the "Start Payment Consumer" API function call 🔎
Input Parameters
- Consumer Payment Identifier
- Wallet Identifier and/or Pass Phrase
<!ELEMENT StartPaymentInquiry EMPTY >
<!ATTLIST StartPaymentInquiry
ConsumerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- (Payment Scheme) Packaged Content - intended for insertion in the Payment Scheme Component of the Inquiry Request Block
<!ELEMENT StartPaymentInquiryResponse
(PaySchemePackagedContent*) >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.5.5. Inquire Payment Status 🍓
The Payment Handler calls this API function for Consumer initiated inquiry processing. It's basically the previous "Inquire Process State" API function, but with the optional inclusion of payment scheme specific data 💅 The response may encapsulate further details about the payment transaction 🫧
Input Parameters
- Payment Handler Payment Identifier
- Wallet Identifier and/or Pass Phrase
- (Payment Scheme) Packaged Content - copied from the Inquiry Request Block's Payment Scheme Component
<!ELEMENT InquirePaymentStatus (PaySchemePackagedContent*) >
<!ATTLIST InquirePaymentStatus
PaymentHandlerPayId CDATA #REQUIRED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- Current Process State
- Completion Code
- Status Description and its language annotation
- (Payment Scheme) Packaged Content - intended for insertion in the Payment Scheme Component of the Inquiry Response Block
<!ELEMENT InquirePaymentStatusResponse
(PaySchemePackagedContent*) >
<!ATTLIST InquirePaymentStatusResponse
PaymentHandlerPayId CDATA #REQUIRED
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #REQUIRED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 📋
4.6. Other API Calls 🌟
4.6.1. Manage Payment Software ✨
okay so this is the API call you use to tell the IOTP Payment Bridge that you want to register, update, or delete a payment instrument 💅 what the Bridge actually does with that info is up to the Bridge, no cap.
This API request can also be used to activate the IOTP Payment Bridge (and the Existing Payment Software it goes with) for general admin stuff 🌸
Input Parameters
- Brand Identifier
- Protocol Identifier
- Any action code:
- New - add new payment method / instrument
- Update - change the payment method's / instrument's data
- Delete - delete a payment method / instrument
- Wallet Identifier and/or Pass Phrase
- (Brand) Packaged Content - further payment brand description
- (Pay Protocol) Packaged Content - further payment protocol description
- (Protocol Amount) Packaged Content - further payment protocol description
Okay so if the Action attribute is set, the Brand and Protocol Identifier have to also be set 🎀 The IOTP Payment Bridge has to bring up the required user dialogs and selection mechanisms. For example, updates and deletions may require picking the payment instrument first. A new wallet might be silently generated when you supply a new Wallet Identifier, or after an extra end user acknowledgement 🫶 The IOTP Application Core should not provide any pass phrases for new wallets. Instead, the IOTP Payment Bridge has to request and verify them, and it may hand their value back to the IOTP Application Core in plain text 😭 Also, the IOTP Payment Bridge returns the supported authentication algorithms when a new brand and protocol pair has been registered. ✨
If the "Action" attribute is omitted, the IOTP Payment Bridge that's responsible for the Existing Payment Software pops up in a general interactive mode 🦋
XML definition:
<!ELEMENT ManagePaymentSoftware (BrandPackagedContent*,
ProtocolAmountPackagedContent*,
PayProtocolPackagedContent*) >
<!ATTLIST ManagePaymentSoftware
BrandId CDATA #IMPLIED
ProtocolId CDATA #IMPLIED
Action (New |
Update |
Delete) #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED >Output Parameters
- An action code:
- New - added new wallet
- Update - changed wallet's configuration
- Delete - removed a wallet
- Wallet Identifier and/or Pass Phrase
Here's the tea 🍓 The IOTP Payment Bridge doesn't return any info about the set of registered payment instruments, because those get dynamically inferred during the brand selection process at the start of each IOTP transaction. BUT the IOTP Application Core has to be notified about new wallets, and should be notified about updated and removed wallets (identifier) 💜 Alternatively, removed wallets can be implicitly detected during the next brand selection phase. Updated wallets do not affect the processing of the IOTP Application Core. The IOTP Payment Bridge should only support the addition of at most one wallet, because it isn't able to report multiple additions at once back to the IOTP Application Core 💅
XML definition:
<!ELEMENT ManagePaymentSoftwareResponse EMPTY >
<!ATTLIST ManagePaymentSoftwareResponse
Action (New |
Update |
Delete) #IMPLIED
WalletID CDATA #IMPLIED
Passphrase CDATA #IMPLIED
AuthNames NMTOKENS #REQUIRED >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 🧚
5. Call Back Function 🌈
This API function is called by the IOTP Payment Bridge, and it passes along info so the Consumer or Payment Handler can be notified about how the payment transaction is progressing 📣
Here's how it fits together:
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
IOTP Application ----calls----
| Core | |
display | | v
to <---------- Call Back <--calls--- Payment
user | | Software
----------------
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*Figure 9. Call Back Function
Whenever this function gets called, the status description content should be made available to the user 👑 Think a status bar, a pop-up window, that kind of thing.
A reference to the Call Back function is passed as an input parameter to the "Start Payment X" and "Resume Payment X" API functions. After that, this function might be called whenever the status changes or progress needs reporting ✨
Input Parameters
- the software identifier of the caller
- Party's Payment Identifier
- Process State and Percent Complete
- Completion Code
- Status Description and its language annotation, text which provides information about the progress of the call. It should be displayed or made available to, for example, the Consumer.
Examples of Status Description could be:
- "Paying 12.30 USD to XYZ Inc"
- "Payment completed"
- "Payment aborted"
The valid languages are announced in the Call Back Language List attribute in "Start Payment X" and "Resume Payment X" API function calls 🌸
XML definition:
<!ELEMENT CallBack EMPTY >
<!ATTLIST CallBack
ContentSoftwareID CDATA #IMPLIED
PayId CDATA #REQUIRED
ProcessState (NotYetStarted |
InProgress |
Suspended |
CompletedOk |
Failed |
ProcessError) #IMPLIED
PercentComplete CDATA #IMPLIED
CompletionCode NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED
StatusDesc CDATA #IMPLIED >Output Parameters
XML definition:
<!ELEMENT CallBackResponse EMPTY >
<!ATTLIST CallBackResponse <!-- see below --> >Tables 4 and 5 explain the attributes and elements, and Table 3 introduces the Error Codes 🎀
Basically, the call back function accepts all input arguments or rejects the whole request. It may even accept malformed requests 🙈
Some payment schemes may support or require that the Consumer can cancel the payment at any time 💀 The Call Back function can facilitate this by returning the cancellation request on the next call (using the Business Error Code and Completion Code "ConsCancelled").
Vice versa, the Payment Handler's Application Core might use a similar mechanism to signal its IOTP Payment Bridges about any exceptional need for a fast shutdown. These IOTP Payment Bridges may initiate the appropriate steps for terminating or cancelling all pending payment transactions 🔥
Note that the "Change Process State" API function provides the second mechanism for this kind of notification. Therefore, the IOTP Payment Bridge or Existing Payment Software may ignore the details of the "Call Back" response 🫶
6. Security Consideration 🔐
Okay, this part is serious bestie 😭 The IOTP Payment APIs only support security using a pass phrase to access the payment Wallet. That can be protected over TLS, which gives stronger security at the transport layer, but implementations are out of the scope of this document. 💀
See also the security consideration section of [IOTP].
7. References 📚
7.1. Normative References
- [IOTP] Burdett, D., "Internet Open Trading Protocol - IOTP version 1.0", RFC 2801, April 2000.
- [ISO4217] ISO 4217: Codes for the Representation of Currencies. Available from ANSI or ISO.
- [URL] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994.
- [UTC] Universal Time Coordinated. A method of defining time absolutely relative to Greenwich Mean Time (GMT). Typically of the form: "CCYY-MM- DDTHH:MM:SS.sssZ+n" where the "+n" defines the number of hours from GMT. See ISO DIS8601.
- [XML] Extensible Mark Up Language (XML) 1.0 (Third Edition). A W3C recommendation. See http://www.w3.org/TR/REC-xml
- [XML-NS] Namespaces in XML Recommendation. T. Bray, D. Hollander, A. Layman. Janaury 1999. http://www.w3.org/TR/REC-xml-names
- [XSLT] Extensible Style Language Transformations 1.0, November 1999, See http://www.w3.org/TR/xslt
7.2. Informative References
- [IOTPBOOK] D. Burdett, D.E. Eastlake III, and M. Goncalves, Internet Open Trading Protocol, McGraw-Hill, 2000. ISBN 0-07-135501-4.
- [SET] SET Secure Electronic Transaction(TM), Version 1.0, May 31, 1997
- Book 1: Business Description
- Book 2: Programmer's Guide
- Book 3: Formal Protocol Definition
- [SET/IOTP] Kawatsura, Y., "Secure Electronic Transaction (SET) Supplement for the v1.0 Internet Open Trading Protocol (IOTP)", RFC 3538, June 2003.
- [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999.
Acknowledgement 🫶
The contributions of Werner Hans of Atos Origin are gratefully acknowledged.
Authors' Addresses 🌷
Hans-Bernhard Beykirch
EMail: hbbeykirch@web.de
Yoshiaki Kawatsura
Hitachi, Ltd.
890 Kashimada Saiwai-ku Kawasaki-shi
Kanagawa, Japan 212-8567
EMail: ykawatsu@itg.hitachi.co.jp
Masaaki Hiroya
Technoinfo Service, Inc.
333-2-718 Uchikoshi-machi
Hachioji-shi
Tokyo 192-0911 JAPAN
EMail: hiroya@st.rim.or.jpFull Copyright Statement ⚖️
Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property 💜
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document, or the extent to which any license under such rights might or might not be available. Nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification, can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.
Acknowledgement 🌈
Funding for the RFC Editor function is currently provided by the Internet Society. 🦋
📦 where this page comes from
- ietf: rfc3867 2004-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms