4.1 Payment app Registration

1. The payer's HTTP client navigates to a payment service provider website and authenticates itself to fetch a payment app to register:
   Example 1: Authenticated GET of payment app

   GET /apps/visa HTTP/1.1
   Host: mybank.example.org
   Date: Tue, 07 Jun 2017 20:51:35 GMT
   Accept: application/json
   Authorization: Digest username="jdoe", realm="jane@mybank.example.org", ...

   Issue 10: What other authentication schemes should be supported for Payment App registration?

   While digest authentication is used above, more advanced authentication schemes may also be employed. For example, the mechanism below uses HTTP Signatures and public/private key cryptography to authenticate the client with the server:

   Example 2: Authenticated GET of payment app using HTTP Signatures

   GET /apps/visa HTTP/1.1
   Host: mybank.example.org
   Date: Tue, 07 Jun 2017 20:51:35 GMT
   Accept: application/json
   Authorization: Signature keyId="https://mybank.example.org/people/jane/keys/42",
      algorithm="rsa-sha256",headers="(request-target) host date",
      signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7qnVrGR+30bmB
                 gtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0jOyn9sXOtcN7
                 uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w="

2. The payment service provider MUST respond with the payment app or an HTTP error code. If successful, something like the following will be returned:
   Example 3: Successful retrieval of payment app

   HTTP/1.1 200 OK
   Date: Tue, 07 Jun 2017 20:51:36 GMT
   Content-Type: application/json
   Content-Length: 412
   
   {
     "type": "PaymentApp",
     "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
     "label": "ExampleBank Visa Card",
     "paymentRequestService": "https://mybank.example.org/services/cards/2745023475"
   }

4.2 Initiating a Payment Request

1. The payer's HTTP client accesses a resource that requires payment:
   Example 4: Payer requests a resource that requires a payment

   GET /movies/dr-strangelove HTTP/1.1
   Host: videos.example.com
   Date: Tue, 07 Jun 2017 21:31:35 GMT

2. The payee's HTTP server responds with a 402 Payment Required response and the URL where the payment request may be fetched via the Location header:
   Example 5: Payee responds with 402 Payment Required

   HTTP/1.1 402 Payment Required
   Date: Tue, 07 Jun 2017 21:31:36 GMT
   Location: https://videos.example.com/payment-requests/dr-strangelove

   Issue 11: Should getting a PaymentRequest result in an extra round trip?

   It's currently not clear if having an extra round-trip (steps 2 and 3) is beneficial. The alternative is to respond with an HTTP 402 and the payment request (step 4) when the GET for the initial resource is performed. This removes the need to do an extra GET at the expense of providing a little more flexibility wrt. the location of the payment request service. For example, having the Location header enables software developers to split media servers from payment processing servers. That said, there are techniques to do this today without the extra layer of indirection.
   Issue 12: Push-based payments should be documented in the HTTP API

   The model described here does not explicitly mention "push" payments even though they are supported. While there is nothing in this design that precludes payments pushed from a payer to a payee, it may be helpful to point out explicit support for the scenario as well as an example that illustrates this feature.
3. The payer's HTTP client accesses the payment request resource:
   Example 6: Payer requests a payment request

   GET /payment-requests/dr-strangelove HTTP/1.1
   Host: videos.example.com
   Date: Tue, 07 Jun 2017 21:31:37 GMT

4. The payee server provides the payment request.
   Example 7: Payee provides the payment request

   HTTP/1.1 200 OK
   Date: Tue, 07 Jun 2017 21:31:38 GMT
   Content-Type: application/json
   Content-Length: 873
   
   {
     "type": "PaymentRequest",
     "description": "Payment for Dr. Strangelove",
     "paymentTerms": {
       "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
       "paymentAmount": {
         "amount": "2.99",
         "currency": "USD"
       }
     },
     "paymentCompleteService": "https://videos.example.com/services/paymentComplete?transaction=923847298"
   }

4.3 Generating a Payment Response

1. A payment app is selected by the payment mediator to process the payment request generated in the previous section.
2. The paymentRequestService URL, provided in the payment app or the payment request, is used as the HTTP POST endpoint. The payment service provider that is providing the payment app interface receives the payment request, authenticates the payer, and proceeds with the payment:
   Example 8: The payment request is POSTed by the payment mediator for processing at the payment app

   POST /services/cards/2745023475 HTTP/1.1
   Host: mybank.example.org
   Date: Tue, 07 Jun 2017 20:51:35 GMT
   Accept: application/json
   
   {
     "type": "PaymentRequest",
     "description": "Payment for Dr. Strangelove",
     "paymentTerms": {
       "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
       "paymentAmount": {
         "amount": "2.99",
         "currency": "USD"
       }
     },
     "paymentCompleteService": "https://videos.example.com/services/paymentComplete?transaction=923847298"
   }

3. The payment service provider generates a payment response message that contains enough information to verify that the transaction has completed in success or failure:
   Example 9: The payment response is provided back to the payment mediator from the payment app

   HTTP/1.1 200 OK
   Date: Tue, 07 Jun 2017 20:51:36 GMT
   Content-Type: application/json
   Content-Length: 623
   
   {
     "type": "PaymentResponse",
     "description": "Payment to ExampleMerch for widgets",
     "paymentTerms": {
       "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
       "status": "authorized",
       "token": "10025AB",
       "paymentAmount": {
         "amount": "2.99",
         "currency": "USD"
       }
     }
   }

4. The payment response is then relayed back to the payee by the payment mediator using the paymentCompleteService URL provided in the initial payment request:
   Example 10: The payment response is relayed back to the payee by the payment mediator

   POST /services/paymentComplete?transaction=923847298 HTTP/1.1
   Host: videos.example.com
   Date: Tue, 07 Jun 2017 20:51:35 GMT
   Content-Type: application/json
   
   {
     "type": "PaymentResponse",
     "description": "Payment to ExampleMerch for widgets",
     "paymentTerms": {
       "paymentMethod": "https://payments.example.org/payment-schemes#Visa",
       "status": "authorized",
       "token": "10025AB",
       "paymentAmount": {
         "amount": "2.99",
         "currency": "USD"
       }
     }
   }

5. The payee validates the payment response, sets the appropriate access control for the resource, and re-directs the payer to the resource:
   Example 11: The payee grants access to the initially requested resource

   HTTP/1.1 302 Found
   Date: Tue, 07 Jun 2017 20:51:36 GMT
   Cookie: movieToken=2983fhfa92h3iuhf908723nkjcsdh923; Expires=Tue, 08 Jun 2017 20:51:40 GMT
   Location: /movies/dr-strangelove

4.4 Security and Privacy Considerations