Announcing the new Square Payments API

I’m excited to share the new and improved API for taking payments online and in-app - the Payments API launches today!

This new API replaces the Transactions API and launches with key new features like:

• Paying with a Square Gift Card
• Paying for an order with multiple payments
• Collecting tips at time of payment
• Providing additional information about CVV and AVS statuses, as well as improved card decline reasons
• Simplified payment interface: location ID management is not required for creating or refunding payments
• Refunding up to 1 year after the payment was taken

“The Payments API has everything you need to charge a customer and fully control the experience. It has lots of customizability. It’s simple when you want it to be and it’s flexible when you need it to be.”

– Kush Patel, Co-founder and CTO of TheCut, has been using the Payments API since early 2019.

The Payments API is designed to work with the Payment Form and the In-App Payments SDK - allowing you to take payments wherever your customers are.

Let’s dive into a few examples:

Take a payment

Once you’ve gotten a nonce from the Payment Form or In-App Payments SDK, here’s how you’d create a payment with it for $20.

curl -X POST \
  https://connect.squareup.com.com/v2/payments \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "idempotency_key": "7ad6806a-7f44-4ad8-8137-f99d9a2330b8",
  "amount_money": {
    "amount": 2000,
    "currency": "USD"
  },
  "source_id": "cnon:gngeeEp2DNcAdl1dPIBAYVkSnYC",
}'

Collect tips

In your call to CreatePayment, you add an additional field tip_money that specifies how much above-and-beyond amount_money to collect. Let’s make that same $20 payment as above but include a $4 tip, for a total charge of $24 to the buyer:

curl -X POST \
  https://connect.squareup.com.com/v2/payments \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "idempotency_key": "7ad6806a-7f44-4ad8-8137-f99d9a2330b8",
  "amount_money": {
    "amount": 2000,
    "currency": "USD"
  },
  "tip_money": {
  	"amount": 400,
  	"currency": "USD"
  },
  "source_id": "cnon:gngeeEp2DNcAdl1dPIBAYVkSnYC",
}'

Why did we build a new API?

The Transactions API had limitations that prevented us from adding features and flexibility our developers were requesting. So we split the API into the new Payments API and a more robust Orders API. We will continue to enhance these APIs, also offering you the flexibility to use the two APIs together or separately.

As of today, the Transactions API is deprecated which means that you can still use this API but Square does not plan to add any new features to it. We will continue to support it until the end of life takes effect in September 2021. We are releasing the Payments API prior to terminating support for the Transactions API to ensure that existing developers have plenty of time to develop, test and migrate to the new API.

Check out our full guide to migrating and let us know what you think, and want to see next! With a better foundation in place we’re looking forward to adding more capabilities to help you grow your business!