Webhook for Completed Payment

I am completely new to the concept of webhooks, and I have read up on the subject. But some assistance would still be appreciated.

Currently, my eCommerce app has a shopping cart that sends customers to the Square Checkout page when they want to pay via online-checkout/payment-links. What I need is for Square to notify my app when the customers have successfully completed payment. Once the customer has successfully payment, my app needs to add the customers’ name to a list within the app and send a confirmation email.

I have looked through the Square API document on webhooks, but I am not sure which webhook to use. I see there’re payment.updated and invoice.payment_made. Am I on the right track?


With our webhooks you’ll want to listen to the payments.updated events to pull the customer_id from the payment. Once you have the customer_id you can call RetrieveCustomer to get the name of the customer to send the email confirmation. :slight_smile:

Great! I will give this a shot.

Another question related to this. Right now while I am in development mode, I can successfully send access Square’s online customer checkout page. My understanding is I cannot simulate a successful payment/transaction in that page. If that is the case, how do I test my webhooks?

You’ll be able to test in sandbox. The sandbox will allow you to preview the link and process a payment that will trigger the payment.updated webhook events. :slight_smile:

I don’t see customer_id returned to me.

Was a customer_id passed in the CreatePayment request? This payment is an EXTERNAL payment and there isn’t any additional information for us to infer the customer. :slight_smile:

I didn’t use CreatePayment. I used online-checkout/payment-links. I did not notice before, but now I can see that under the order parameter. It now says customer_id is in BETA. Does that mean it’s new and is being tested? Is it ok to use?

I added customer_id to the online-checkout/payment-links POST request, but it still did not reutrn with the customer ID:

Okay, this is sandbox and the sandbox experience isn’t great with the Payment links. It will be there in production. Unfortunately there isn’t a way to test this end to end in sandbox. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slight_smile:

Well, is there any way for me to pretend I do receive customer_id so that I can build and test out the steps that are supposed to execute afterwards?

If you call CreatePayment with directly with the following it will trigger a webhook event with the customer_id:

    "idempotency_key": "{{$guid}}",
    "autocomplete": true,
    "amount_money": {
        "amount": 100,
        "currency": "USD"
    "source_id": "cnon:card-nonce-ok",
    "customer_id": "{{customer_id}}"


I can call both payment-links and CreatePayment? Which comes first? Won’t this cause 2 transactions rather than 1?

Does CreatePayment also send the customer to Square’s checkout session?

I am obviously confused. Haha.

No, you won’t call both for production. For testing I’m suggesting that you call CreatePayment with a customer_id to pretend to get the customer_id for testing. :slightly_smiling_face:

Ah. Let me give that a shot. Thanks.

Can I get clarification on customer id. Isn’t it generated randomly by Square?

It looks like the call for CreatePayment is POST /v2/payments.

If the customer is new, do I have to call POST /v2/customers to create a new customer before calling CreatePayment so that a Square-generated ID can be inputted as part of that call?

Because right now, my app generates an ID that is in a different format than that of Square.

Yes, you’ll need to first create a customer within Square to get an ID to pass in the payment request. :slightly_smiling_face:

Ok, so right now, I am finally able to create a new customer, then from there, I succeeded in using CreatePayment.

However, I’m not sure I understand the step-by-step process and I can’t seem to find the documentation for it.

I want to be able to send the customer to the Square-hosted checkout page, but I am not sure when or if at all it happens.

Is it:

  1. Create customer
  2. Create payment
  3. Send customer to Square-hosted checkout page


  1. Create customer
  2. Send customer to Square-hosted checkout page
  3. Create payment

Glad to hear your making progress. So remember you were only calling CreatePayment to test seeing the customer_id in the webhook. In production you won’t be calling CreatePayment.

You’ll call CreateCustomer if your collecting the customer information prior to creating the link and if the customer doesn’t exist within the directory already. Otherwise we will create the customer profile when the customer checkouts out through the link. :slightly_smiling_face: