Sales Channel - Completing a Payment (Payments.json)

Shopify Partner
4 0 0

I'm trying to finish completing a checkout with the Payments API


On the API docs it lists 4 required fields: amount, request_details, session_id, unique_token.


On the Sales Channel Guides it has different fields: payment_token instead of session_idand payment_token is an object not a string. Also there's an option to just pass in a customer (below)?



Your API docs could use some serious clarification, any help here would be extremely appreciated.



Question 1:

How do I use a Stripe Card source (e.g. 'card_8kjfwkdjfskdfh') that I've already created with a saved Stripe Customer ? This is not a one time token, but a source that can be used multiple times by the same customer. What would be my input on the Shopify payment object?


I've created this at the platform account level, not at some individual shopify_payments_account_id


The Guide says:

"If you've already tokenized the customer's credit card and created a customer in your Stripe platform account, then you can send the customer id from your platform account instead of sending the card information."


But it doesn't tell you how to pass in a customer. Also a customer could have multiple cards attached, which one would it choose to charge?


  "payment": {
    "request_details": {
      "ip_address": "",
      "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": "20.00",
    "session_id": "DO I PUT THE CARD (card_8kjfwkdjfskdfh) HERE?????",
    "unique_token": "client-side-idempotency-token"


Question 2:

Another option, Am I supposed to charge the customer (using Stripe) before I send some sort of session_id to Shopify? E.g. using Stripe's Create Charge



const stripe = require("stripe")("sk_test_key");

  amount: 2000,
  currency: "usd",
  customer: "cus_9823ujwdfkjsh",
  source: "card_8kjfwkdjfskdfh",
  description: "Charge for"
}, function(err, charge) {
  // asynchronously called
Shopify Staff
Shopify Staff
1555 80 246

Hey @testusername1.


Firstly, I agree. The docs here certainly need some work. The mismatch looks to be occurring because one surface area assumes you are vaulting the card via Shopify rather than Stripe, and the reference you're reading is just a different path where you opt to send the card details to Stripe in exchange for a token. We should be more explicit with this.


To answer your questions in order:


1. That note more specifically means that when you would normally be posting a `card` object to Stripe, you would instead post a `customer` object (step 2 of our Stripe payment processing guide). Since this happens to be handled by Stripe at this stage in processing the payments, their docs would be the best to refer to here. In exchange for the customer object, you will still receive a Stripe token, which you can then proceed as normal (posting it to Shopify at /checkouts/payments.json). Customer objects in Stripe have a default source set on them, which is the card that is ultimately charged.


2. Assuming you are acquiring a Stripe token by posting to their tokens endpoint: you would not be processing the payment through Stripe. You would instead be providing us that payment_token in a payment object when you POST to the /checkouts/payments.json endpoint, and we would use this to process the payment on Stripe without you needing to.


I hope that helps you out, let me know if anything is unclear and we're going to start looking at refocusing our payment processing docs. That feedback is very appreciated.



Shopify Partner
4 0 0

1. I actually solved this problem using This allows you to choose which card to tokenize. And then you pass this information (the returned source id, e.g. src_123456789) back to Shopify (in Step 3).


I found that adding 

"type": "stripe_vault_token" 

In the POST to Shopify is incredibly important, no matter what type of tokenization you use. I tried to change the text from "stripe_vault_token" and the payment POST completes without errors, but then it fails in the Admin dashboard of the merchant (and no orderCreate webhook is sent). Why do you make us include this string if it cant be changed? (would assume you would include it on your end, and save us the ability to create bugs.) Is there a reason why this still has to be included?



2. Okay makes sense. Found I can complete the checkout by including the shopify_payments_account_id as the associated Connect Account when tokenizing. However, how do you then charge for your Sales Channel? I understand you can set a Recurring Application Charge (at $0 per month), then have a Usage Charge for each item sold. But this seems different than any other Sales Channel that has a commission based model.

  • Spring (now District?), Houzz, Wanelo, etc. all charge ~15% but none of them make you accept a Recurring Application Charge (I've tried installing using a development store).
  • They also withhold the entire payment from the merchant, instead of just taking a small piece using a Shopify Usage Charge. Proof here (Wanelo, Houzz)
  • Houzz is also able to do a unified shopping cart across merchants (something that the Checkout API doesn't allow).

How are they processing payments differently?

Shopify Staff
Shopify Staff
1555 80 246

Hey @testusername1.


Sorry for the delay! My team was pretty busy leading into and during Unite, and we've just acquired some extra bandwidth to start following up on some channels we were communicating in.


Referring to those apps specifically, without being able to go into too much detail, it looks like they're not charging directly through Shopify, rather they are billing for the app externally. If they they are holding all payments, we can also probably infer that rather than creating checkouts, they are likely importing completed orders via the order API.


Hope that helps a bit. Cheers.

Shopify Partner
4 0 0

Hi Alex -


Yes looks like you need to use the Orders API to complete an order without using POST to the Checkout API.


However I run into problems with discount codes (as I'm sure you know) with the Orders API. They don't apply correctly like they do with the Checkout API. I'm sure Shopify does this for a reason (they want to take a cut, so don't allow the same features to places they can't take money).


The Orders API bluntly applies "percentage" discount codes to all line items, no matter if that discount code actually applies that line item.


There was an announcement, saying that they fixed this problem, but it's actually completely incorrect:


The Draft Order API allows you to create line item level discounts. But you first need to know that the discount applies to that line item, so it kind of renders that ability irrelevant. If I have 4 items in a cart, and the discount code only applies to 1 of them, you would need to know that yourself. Shopify doesn't tell you.


Shopify will only allow you to add in a discount code, and have it apply to the correct line items automatically, if you use the Checkout API. And then you can't get paid for your app/Sales Channel without using the Billing API, which they sneakily don't tell you that they take 20% from.


1. Is there any plan to fix discount codes with the Orders API? 

2. Why does Shopify hide the fact that they take 20% of everything through your Sales Channel? It doesn't say this anywhere on the Sales Channel documentation. This is super disingenuous and cost me weeks of development work. I now had to pivot away from the Checkout API because I found this out at the last minute.


No where in any of the documentation is the 20% mentioned, you have to dig to the Billing API documentation, which isn't even referenced







finally its mentioned here



Shopify Staff
Shopify Staff
1555 80 246

Hey @testusername1.


First, to clarify on the 20% you're seeing: we do not take 20% of payments processed by your sales channel. We take 20% of charges for your application, so subscription charges or one time payments to make use of your channel, not the cash flowing through it when processing payments via the checkout API. That would be 2.1%, and I agree this can be better documented.


Thanks for pointing out the issue re: discounts on the orders API. I'm personally struggling to get this to work as well, so I'll do some asking around and let you know of the state of things once I have more information.



New Member
5 0 0

Hi @Alex,


I've had a read through this post and thought you might be able to help us clarify some issues we are having in creating our sales channel;


We are implementing a marketplace solution and over the past month we have already implemented the Order API and external payment processing.

I've recently read the requirements (Section 5.A.4 and Section 13.D.1) which state that a sales channel must use the Checkout API. My understanding is that the Checkout API and the Order API are mutually exclusive.


Given that I must use the Checkout API, how will it be possible for me  to process single orders against multiple merchants using the Checkout API while adhering to the requirements for listing a sales channel set by Shopify?


There is a recent post in the forum, Marketplace post outlining the same solution we are looking for, and just wanted to make sure that Josh from Shopify's response was indeed correct?


I would be incredibly grateful for any light you could shed on this issue.


Thanks in advance, Rob



22 0 1

@Alex What about Usage Charges, does Shopify take 20% of those?

Shopify Staff
Shopify Staff
1555 80 246

@Prazar can you further explain what you mean by how will it be possible for me  to process single orders against multiple merchants using the Checkout API while adhering to the requirements for listing a sales channel set by Shopify ? With regard to Josh's post, it looks like this is a detail we missed. Our team specifically doesn't approve or deny Sales Channel integrations, so that documentation is going to be the better source of truth.


@rgb correct, usage charges also have 20% of rev share taken off, as with recurring charges and app charges.