Repository Standards

Appearance

On this page

Package Purchase Flow ​

To initiate a purchase, the client will send the following request to the Payment Gateway.
POST /v2/purchase

json
{
	"package_id": "com.foo.mypackage",
	"payment_secret": "7bafed94-b15e-456d-b882-f985da16bfa2"
}

The Payment Gateway has a few courses of action that it may take to respond to this payment request.

  • If no further action is required and the package should be considered as purchased, returning a status code of 202 Accepted is the appropriate action for the Payment Gateway to take.
  • If further action is required (ie. directing users to an external payment processor), the Payment Gateway should return 303 See Other and provide a URL for the client to direct to in the Location header.
  • If any other unexpected issue occurs, the Payment Gateway may return an invalid status code, which the client will treat as an error and recover from.

TIP

The client will take responsible steps to ensure that a direct and instant payment cannot happen without some sort of confirmation (through prompts, FaceID/TouchID, etc).

If the Payment Gateway returns 303 See Other, the client will open the URL supplied in the Location header and add a query parameter onto it to control the callback (see the example below). Once a request is made to the callback URL, the client assumes that the payment was successful.

yaml
# Original header response:
Location: https://mygateway.com/confirm_purchase

# The client will open the URL like so:
https://mygateway.com/confirm_purchase?callback=myclient%3A%2F%2FpurchaseCallback