All Tutorials

Complete a sales channel payment with the Checkout API

All Tutorials

Complete a sales channel payment with the Checkout API

On this page

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

A diagram of the process for completing a payment with Stripe

  1. Customer initiates checkout.
  2. Your sales channel app uses the Checkout API to create a checkout.
  3. Shopify returns the shopify_payments_account_id.
  4. Your channel sends the merchant's managed account id and the customer's credit card information to Stripe to generate a token.
  5. Your channel uses the Checkout API to create a payment transaction, and it passes the token from Stripe to Shopify.
  6. 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:

  1. 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.

  2. 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.

  3. 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

A diagram of the process for completing a payment with Spreedly

  1. The customer initates the checkout process.
  2. Your sales channel app uses the Checkout API to create a checkout object in Shopify.
  3. Shopify returns the checkout information to your sales channel app.
  4. Your sales channel app passes the credit card information to Spreedly.
  5. Spreedly generates a vaulted credit card token.
  6. Spreedly passes the credit card information to Shopify’s vault.
  7. The Shopify vault passes a payment session ID to Spreedly.
  8. Spreedly sends the vaulted credit card token and the payment session ID to your sales channel app.
  9. Your sales channel app then sends the payment session to Shopify and creates an order using the Checkout API.
  10. Shopify processes the payment using the merchant's payment gateway.

Complete a payment using Spreedly

To complete a payment using Spreedly:

  1. Sign up for a Spreedly account and get an environment key and secret access token.

  2. 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.

  3. 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.

  4. Send the payment_method.token and the receiver token from Spreedly to Shopify's PCI-compliant card storage environment.

    The header and body 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.

  5. 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
      }
    ]
  }
}

  6. 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

A diagram of the process for completing a payment from your sales channel app

  1. The customer initates the checkout process.
  2. Your sales channel app uses the Checkout API to create a checkout object in Shopify.
  3. Shopify returns the checkout information to your sales channel app.
  4. Your sales channel app passes the credit card information to Shopify's PCI compliant card server.
  5. Shopify's card server returns a payment session ID to your sales channel app.
  6. Your sales channel app uses the Checkout API to pass the payment session ID to Shopify.
  7. 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.