Shop Pay Wallet in the context of Shopify's Checkout and Payment

Authorization

Anchor link to section titled "Authorization"

As described in Getting started with the Shop Pay Wallet, the flow starts by asking the buyer to authorize your app to access their wallet. Completing this flow will provide you with an OAuth 2.0 Access Token unique to you and the buyer. This token is required to place an order.

Wallet requests

Anchor link to section titled "Wallet requests"

With that access_token you can fetch the buyer's wallet. The wallet can contain the last four digits, the network (VISA, Mastercard, ...), and the type (credit or debit) of the buyer's credit card as well as the buyer's shipping address, depending on the requested scopes. Note that the wallet does not contain the billing address of the buyer's credit card.

Retrieve payment details

Anchor link to section titled "Retrieve payment details"

You can then confirm the order and retrieve payment information with your internal partner order IDs, as well as the tokenization_type PAYMENT_CREDENTIAL or SESSION. As mentioned in the scopes guide, for Shopify merchants you must ask for SESSION whereas for non-Shopify merchants you must ask for PAYMENT_CREDENTIAL. The latter requires that you are PCI-compliant.

If you ask for PAYMENT_CREDENTIAL, you will receive the buyer's billing address and encrypted PAN. If the credit card supports network tokenization, you will receive a network token along with a cryptogram in place of the PAN. You can use those to process the payment on your own platform.

If you ask for SESSION, you will receive the buyer's billing address and a Session ID. You can use those to process the payment on the Shopify platform. Refer to this fragment of a successful response to see the billing address and the Session ID west-a1584d23a51970fb8065ec71c34d25db:

Create checkout and payment

Anchor link to section titled "Create checkout and payment"

You can use the billing address you received in the previous step, along with the buyer's email address or phone number, to create a checkout. This will give you a checkout token. Use this checkout token, together with the Session ID west-a1584d23a51970fb8065ec71c34d25db that you received from the confirm the order API, to create a payment. Note that you can use this Session ID at most once and the Session ID is valid for at most 1 hour.

This summarizes the above flow:

Shop pay diagram