HTTP messages
It has been suggested that for the purposes of testing, we should have at least one normative representation of messages in JSON Schema format.
PaymentRequest
A PaymentRequest expresses a payment that is requested
by a payee.
type-
A set of one or more type identifiers associated with the object, typically
set to
"PaymentRequest".The set of available types MAY be extended in the future to, for example, add things like"SubscriptionRequest"to identify payment requests that may have some recurring quality to them. description-
A human-readable description of the reason the payment request was initiated.
This text MAY be displayed to the payer in a payment interface.
For example,
"Payment for widgets from Acme Anvil Emporium". paymentTerms- One or more PaymentTerms that the payee will accept as payment.
paymentDetails- An optional set of information concerning the details of why the payment was requested, such as a list of items being purchased.
paymentOptions- An optional set of requests that are intended for the payment mediator or the payment application. For example, a payee may request that a payment mediator return the shipping address and the email address selected by the payer.
The format for the paymentDetails and paymentOptions
objects are still being actively discussed. They are expected to take the
form of the
PaymentDetails
and the
PaymentOptions
objects in the
Web Payments Browser API.
{
"type": "PaymentRequest",
"description": "Payment to ExampleMerch for widgets",
"paymentTerms": {
"paymentMethod": "https://example.org/cards#VisaLegacy",
"paymentAmount": {
"amount": "4.35",
"currency": "USD"
}
}
};
Whether or not values that may contain one or more items, such as
paymentTerms above should throw an error during validation
if they are not an array is under discussion. That is, should we say that
values that could contain more than one item MUST always be wrapped in an array?
PaymentResponse
A PaymentResponse expresses the result of processing
a payment request.
type-
An type identifier associated with the object, typically set to
"PaymentResponse".The set of available types MAY be extended in the future to add things likeReceiptto identify acknowledgements that contain receipt information. description-
Human readable text that will be used to identify what the payment was for.
This text MAY be displayed to the payer. For example,
"Payment to ExampleMerch for widgets". paymentTerms- Information such as the payment method used and the payment amount. Payment method specific information, such as the status of the payment, MAY also be included. The presence and meaning of this extra information is dependent on the payment method. The payment information MAY be used by the payee or their associated payment service provider to, for example, finalize a payment or display information to the payer.
paymentOptions- Any payment options that were requested by the payee, such as email address, phone number, or billing address.
{
"type": "PaymentResponse",
"description": "Payment to ExampleMerch for widgets",
"payment": {
"paymentMethod": "https://example.org/cards#VisaLegacy",
"paymentAmount": {
"amount": "4.35",
"currency": "USD"
},
... // payment method specific response details here
},
"paymentOptions": {
"email": "jdoe@example.org"
}
};
Supporting Datatypes
FinancialAmount
A FinancialAmount is used to express a scalar financial
value.
currency-
currencyis a string containing a three-character alphaneumeric code for the currency as defined by [[!ISO4217]] or a URL for a currency identifier. For example,"USD"for US Dollars or"https://example.com/currencies/experimental-XYZ"for a new experimental currency. amount-
A string containing the decimal monetary value. The string MUST use a single
U+002E FULL STOP character as the decimal separator. All other characters
must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
The string should match the regular expression
^[0-9]+(\.[0-9]+)?$.
The following example shows how to represent $55.00 US Dollars.
{
"amount": "55.00",
"currency": "USD"
}
PaymentTerms
PaymentTerms express the type of payment method,
amount, and other information under which a transaction may be fulfilled.
paymentMethod-
One or more payment method identifiers (as defined in
an associated payment method specification). For example,
"https://example.org/cards#VisaLegacy"or"https://newnetwork.example.com/methods/SuperCard" paymentAmount- The FinancialAmount requested by the payee. The value may also be a set of FinancialAmounts that express the desired amount in different currencies.
{
"paymentMethod": [
"https://example.org/cards#VisaLegacy",
"https://example.org/cards#MasterCardLegacy"
],
"paymentAmount": {
"amount": "4.35",
"currency": "USD"
}
}