Completing a payment

To complete a payment on your sales channel app, your application needs to use the Checkout API to send the customer's credit card information to Shopify. You can integrate Stripe with your sales channel app to handle the credit card information for you. You can also send the card information to Shopify with a third-pary service like Spreedly, or directly from your sales channel app.

Integrate Stripe with your sales channel app

If you use Stripe to complete payments for your sales channel app, then merchants who use your sales channel will need to have Shopify Payments on their store.

How it works

A diagram of the process for completing a payment with Stripe
  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 an id that represents the merchant's account.
  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.

Complete a payment using Stripe

To complete a payment using Stripe:

  1. When the customer initates a checkout, create a checkout object for the transaction.

    When you create a checkout, Shopify will return the merchant's shopify_payments_account_id.

  2. Send the merchant's shopify_payments_account_id and the card information from your platform account to Stripe:

    POST /v1/tokens HTTPS/1.1
    Host: api.stripe.com
    Authentication: Basic #{stripe_auth_token}
    Stripe-Account: #{shopify_payments_account_id}
    
    card: {
      number: '4242424242424242',
      exp_month: 12,
      exp_year: 2019,
      cvc: 123
    }
    

    Stripe will return a token that represents the customer's credit card.

  3. Send the token using the Checkout API to process the payment in Shopify:

    POST /api/checkouts/#{token}/payments.json HTTPS/1.1
    Host: shop-name.myshopify.com
    X-Shopify-Access-Token: #{shopify_access_token}
    {
      "payment": {
        "payment_token": {
          "type": "stripe_vault_token",
          "payment_data": "tok_AQ21IJuMzhuGmp"
        },
        "unique_token": "client-side-idempotency-token"
      }
    }
    

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\": \"\", \"month\": \"\", \"year\": \"\", \"verification_value\": \"\", \"first_name\":\"\", \"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.