Complete a sales channel payment with the Checkout API
Sales channel apps use the Checkout API to send your customers' credit card information to Shopify and complete their payments.
By default, your app can provide checkout links to Shopify's web checkout for each product. This lets your platform use Shopify's web checkout instead of building your own native checkout form. You can direct customers to a checkout link by using the web_url
parameter of the Checkout API.
If you want to accept payments directly in your app instead, then it's recommended that you use a third-party service to tokenize your customers' credit card information and send it to Shopify. By tokenizing this information, you reduce the PCI compliance scope for payments using your sales channel app. The tokenization service that you integrate with your app determines the type of payment gateway that Shopify merchants can use with your sales channel:
- Integrate with Stripe to process payments for merchants who have Shopify Payments activated as their payment gateway.
- Integrate with Spreedly (or a similar forwarding service) to process payments for merchants who are using a payment provider other than Shopify Payments.
Integrate Stripe with your sales channel app
You can use Shopify's integration with Stripe to tokenize credit cards on behalf of merchants that have enabled Shopify Payments as their payment gateway solution.
How it works
- Customer initiates checkout.
- Your sales channel app uses the Checkout API to create a checkout.
- Shopify returns the
shopify_payments_account_id
. - Your channel sends the merchant's managed account id and the customer's credit card information to Stripe to generate a token.
- Your channel uses the Checkout API to create a payment transaction, and it passes the token from Stripe to Shopify.
- Shopify processes the payment using Shopify Payments.
Setup requirements
Shopify's integration with Stripe has the following requirements:
- You'll need to get token create access for Shopify's Custom accounts in Stripe
- Users of your app need to have Shopify Payments enabled
Obtaining token create access:
You'll need token create access to tokenize credit cards on behalf of Shopify's Custom accounts in Stripe. To get token create access, provide Shopify with your Stripe account id
. You can query for this id
using the Stripe API.
Complete a payment using Stripe
To complete a payment using Stripe:
When the customer makes a checkout, create a checkout object for the transaction. When you create a checkout, Shopify will return the merchant's
shopify_payments_account_id
. Note that if the product requires shipping, then you will need to specify the shipping and billing addresses, poll for shipping rates, and set the applicable shipping rate.Send the merchant's
shopify_payments_account_id
and the card information from your platform account to Stripe using the tokens endpoint. The secret key corresponds to your Stripe secret key which you can grab from the API section of your Stripe account.POST /v1/tokens HTTPS/1.1 Host: api.stripe.com Authentication: Basic #{secret_key} Stripe-Account: #{shopify_payments_account_id} card: { number: '4242424242424242', exp_month: 12, exp_year: 2019, cvc: 123 }
A successful request returns a token for the customer's credit card.
Send the token using the Checkout API to process the payment in Shopify. The
unique_token
can be any client-generated unique identifier:POST /admin/checkouts/#{token}/payments.json HTTPS/1.1 Host: shop-name.myshopify.com X-Shopify-Access-Token: #{shopify_access_token} X-Shopify-Checkout-Version: 2016-08-28 { "payment": { "amount": "33.00", "unique_token": "12345", "payment_token": { "payment_data": "tok_1AgzvXGp4JCfxblBH7gs5kLB", "type": "stripe_vault_token" }, "request_details": { "ip_address": "123.1.1.1", "accept_language": "en" "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36" }, } }
A successful request completes payment using the Stripe token and a corresponding order is created in the shop.
For more information about vaulting with Stripe, see the Stripe API Reference.
Send credit card information using a third-party service
You can use a third-party payment forwarding service like Spreedly to send customer credit card information to Shopify's PCI compliant card server.
How it works
- The customer initates the checkout process.
- Your sales channel app uses the Checkout API to create a checkout object in Shopify.
- Shopify returns the checkout information to your sales channel app.
- Your sales channel app passes the credit card information to Spreedly.
- Spreedly generates a vaulted credit card token.
- Spreedly passes the credit card information to Shopify’s vault.
- The Shopify vault passes a payment session ID to Spreedly.
- Spreedly sends the vaulted credit card token and the payment session ID to your sales channel app.
- Your sales channel app then sends the payment session to Shopify and creates an order using the Checkout API.
- Shopify processes the payment using the merchant's payment gateway.
Complete a payment using Spreedly
To complete a payment using Spreedly:
Sign up for a Spreedly account and get an environment key and secret access token.
Add Shopify as a receiver in Spreedly using the Spreedly API:
POST /v1/receivers.json HTTPS/1.1 Host: core.spreedly.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/<format> { "receiver": { "receiver_type": "shopify" } }
The response contains a
token
parameter. This is your receiver token, which you'll use when vaulting credit cards with Spreedly.When a customer checks out, send their credit card information to Spreedly.
There are multiple methods available for sending credit card information to Spreedly. You can use the iFrame Payment Form or Spreedly Express, which require a low level of PCI compliance.
You can also use the Spreedly Javascript API to send the credit card directly to Spreedly from the client’s browser:
POST /v1/payment_methods.<format> HTTPS/1.1 Host: core.spreedly.com Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/<format> { "payment_method": { "credit_card": { "first_name": "Joe", "last_name": "Jones", "number": "5555555555554444", "verification_value": 423, "month": "3", "year": "2032" }, "email": "joey@example.com" } }
The response to this call will include a
payment_method.token
parameter, which you'll use to store the credit card.Send the
payment_method.token
and the receiver token from Spreedly to Shopify's PCI-compliant card storage environment.The
header
andbody
parameters provided are the header and body of the request that Spreedly will forward to Shopify. The credit card details are provided as Spreedly receiver variables through a templating syntax.POST https://core.spreedly.com/v1/receivers/#{receiver_token}/deliver.json Authorization: Basic #{spreedly_auth_token} Content-Type: application/json { "delivery": { "payment_method_token": #{payment_method.token}, "url": "https://elb.deposit.shopifycs.com/sessions", "headers": "Content-type: application/json", "body":"{ \"payment\": { \"credit_card\":{ \"number\": \"{{ credit_card_number }}\", \"month\": \"{{ credit_card_month }}\", \"year\": \"{{ credit_card_year }}\", \"verification_value\": \"{{ credit_card_verification_value }}\", \"first_name\":\"{{ credit_card_first_name }}\", \"last_name\":\"{{ credit_card_last_name }}\"}}}" } }
The response object will contain an
id
parameter, which you'll send to Shopify when you create the payment.Create a new checkout object in Shopify using the Shopify API:
POST /admin/checkouts.json HTTP/1.1 Host: shop-name.myshopify.com Content-Type: application/json X-Shopify-Access-Token: #{shopify_access_token} { "checkout": { "email": "jamiedee@mailinator.com", "billing_address": { "first_name": "Jamie", "last_name": "Dwyer", "address1": "150 Elgin St.", "country": "CA", "province": "ON", "city": "Ottawa", "zip": "K2P1L4" }, "shipping_address": { "first_name": "Jamie", "last_name": "Dwyer", "address1": "150 Elgin St.", "country": "CA", "province": "ON", "city": "Ottawa", "zip": "K2P1L4" }, "line_items": [ { "variant_id": 27166731523, "quantity": 1 } ] } }
Send the
id
using the Checkout API to process the transaction in Shopify:POST /admin/checkouts/#{token}/payments.json HTTP/1.1 Host: shop-name.myshopify.com Content-Type: application/json X-Shopify-Access-Token: #{shopify_access_token} { "payment": { "request_details": { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.98 Safari\/537.36" }, "amount": "1675.99", "session_id": #{id}, "unique_token": "client-side-idempotency-token" } }
For more information about vaulting with Spreedly, see the Spreedly documentation on Payment Method Distribution and the Spreedly API Reference.
Send credit card information from your sales channel app
To complete a payment on your sales channel app, you can send the customer's credit card information to Shopify's PCI compliant card server from your sales channel app.
How it works
- The customer initates the checkout process.
- Your sales channel app uses the Checkout API to create a checkout object in Shopify.
- Shopify returns the checkout information to your sales channel app.
- Your sales channel app passes the credit card information to Shopify's PCI compliant card server.
- Shopify's card server returns a payment session ID to your sales channel app.
- Your sales channel app uses the Checkout API to pass the payment session ID to Shopify.
- Shopify processes the payment using the merchant's payment gateway.
Complete a payment from your sales channel app
To send the credit card information to Shopify from your app, you'll need to create a payment session using the credit card details.