Questions on subscriptions and Web SDK + Subscriptions API

Questions
1

We have decided to switch to using the Web Payments SDK and use the inline credit card form on a customer’s site instead of the Checkout API and redirecting a user because the UX on the hosted form is nowhere near good enough for subscriptions.

Here is our example subscription situation again:

$100 upfront, then $150 yearly

I have tried reading lots of threads in the forums around this and my current general understanding of the steps are this:

  • Invoke the Web SDK to build the card form
  • When user submits, verify the user with their billing information and card and receive a token on success
  • Via the API, create the customer, assign the card to their profile, create subscription and have it be paid with the newly added card on file (this is a beast that looks overwhelmingly complicated but will get to that later)

One thing I am confused about is that a previous thread says that subscriptions cannot be paid with the Payments API. However, the Web SDK for the inline card requires a payment amount in order to verify the buyer for SCA rules at the very beginning. So how can I create a payment but then not use a payment for a subscription?

So when prepping the card fields with Web Payments SDK and verifying the buyer, what amount do I use and does this actually charge the customer?

Again, incredibly lost on the steps here in setting up subscriptions.

2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Square Developer
Gift Card Payments
Charge a Card on File

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

I have found the Store Card on File example here: web-payments-quickstart/public/examples/store-card-on-file.html at main · square/web-payments-quickstart · GitHub

This seems to not require any upfront amount. This should work for subscriptions I think?

Not sure if I have the general steps understood though.

4

To set up subscriptions using the Web Payments SDK, you would follow these steps:

  1. Use the Web Payments SDK to create a card entry form on your website. This will allow the customer to enter their card details.

  2. When the customer submits the form, the SDK will generate a payment token. This token represents the customer’s card details and can be used to create a card on file.

  3. Use the Customers API to create a customer profile in your Square account. This profile will represent the customer in your system.

  4. Use the Cards API to create a card on file for the customer. You will need to provide the payment token generated by the Web Payments SDK and the customer ID returned by the Customers API.

  5. Use the Subscriptions API to create a subscription for the customer. You will need to provide the customer ID and the card ID returned by the Cards API. The subscription will automatically charge the card on file according to the payment schedule you specify.

Regarding your confusion about the Payments API and subscriptions, the Payments API is used to process one-time payments, not recurring payments like subscriptions. The initial payment amount you specify when verifying the buyer with the Web Payments SDK does not actually charge the customer. It’s used for Strong Customer Authentication (SCA) purposes. The actual charge happens when you create the subscription with the Subscriptions API.

This answer was reviewed by @Bryan-Square.

5

Thanks for the clarifications, that helped a lot.

I have one-time payments working fine with the Web Payments SDK passing the token and processing via PHP.

However, when I go to create a card I repeatedly get the same error every time using the exact same process of getting the card token:

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "INVALID_CARD_DATA",
      "detail": "Invalid card data.",
      "field": "source_id"
    }
  ]
}

The only example currently available for creating subscriptions involves physical goods. We are never shipping physical goods. Do I need to follow all those steps in regards to creating line items and creating orders as outlined in the example? If so, that means we need to create Catalog Objects as well for each phase? So we would need to create placeholder catalog objects since we don’t actually ship physical items? Then we have to maintain pricing for the catalog item AND the plan variation item? I feel like there is no way that has to be true…

Can I pass just the Subscription Plan Variation ID or do I have to also pass all the phases along with their UIDs? I don’t understand why I would have to pass the plans again if the Plan Variation already had the phases set when it was created.

When a Subscription is created, how do I get the Payment ID for the initial payment that should have been charged at the moment the Subscription was created? I only see an Invoice IDs, but no Payment ID in the Subscription creation response.

6

When you get the INVALID_CARD_DATA are you passing in the same values you used to create the token for zip code in the CreatePayment request?

Also items in the catalog aren’t specific to physical items. You can sell a digital item or a service. In order to sept through and successfully create the subscription you’ll need to follow all the steps that the documentation walks you through even if your passing in the an ID more then once. :slight_smile:

7

I am not clear on what you mean or what the zip code has anything to do with it. I have the exact same form using the JS to get the payment token. That same generated token then gets used as either a single payment or to add a card on file for a user. The add a card on file doesn’t work while the payment does and that doesn’t make sense as to why.

I already have a Subscription Plan and Subscription Plan Variation in the catalog. Do I have to then create yet another catalog item to be used when making the draft orders or do I use the Subscription Plan ID or the Subscription Plan Variation ID? This is wildly unclear when not shipping physical items.

8

No, you can use the same subscription and plan variation over and over again.

What test value did you get INVALID_CARD_DATA? :slight_smile:

9

I don’t understand what you mean. I gave you the response the API gave me:

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "INVALID_CARD_DATA",
      "detail": "Invalid card data.",
      "field": "source_id"
    }
  ]
}
10

It is not allowing me to use the ID from either the Subscription Plan or the Subscription Plan ID when trying to use that during the Create Order steps outlined here: Manage Subscriptions Using the Subscriptions API - it tells me that ID cannot be found. I literally just created it a few lines above and then it isn’t found?

11

I also still have this question. With what I have “working” right now, no Invoice IDs even get generated let alone Payment ID. How can I know that this Subscription was actually set up properly and billing is happening as it should?