Documentation Manage Apps

Processing a card payment (REST)

After the SqPaymentForm generates a card nonce and you submit it to your server, you finish processing the payment by sending a request to the Charge endpoint with the details of the transaction.

This article demonstrates using the Unirest HTTP library to send an HTTP request to the Charge endpoint. Versions of Unirest are available for many popular server programming languages. This article uses the Python version.

You are of course free to use any HTTP library that you're comfortable with. If you aren't familiar with HTTP libraries, Unirest is a good place to start, because it's very easy to use with Connect API endpoints.

Installing Unirest

Installation instructions for each version of Unirest are available on the Unirest site.

Retrieving your location IDs

Every Square merchant's business consists of one or more locations. Every payment a merchant processes is associated with one of these locations (even online payments). In order to process a payment with Connect v2, you need to know which location you want to associate the payment with.

To obtain a business' loation IDs, you send a request to the ListLocations endpoint.

After installing the Python version of Unirest, paste the following into a locations-test.py file and run it with python locations-test.py. Be sure to specify your personal access token where indicated. The details of your business' locations will appear in the console.

import unirest

access_token = 'REPLACE_WITH_YOUR_ACCESS_TOKEN'

response = unirest.get('https://connect.squareup.com/v2/locations', headers= {
  'Accept': 'application/json',
  'Authorization': 'Bearer ' + access_token
})

print response.body

Charging the card nonce

Now that you've generated a card nonce with the SqPaymentForm and you have a way to retrieve a business' location IDs, you can charge a buyer's card, like so:

import unirest
import json
import uuid

# Assume you have assigned values to the following variables:
#   card_nonce
#   location_id
#   access_token

response = unirest.post('https://connect.squareup.com/v2/locations/' + location_id + '/transactions',
  headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + access_token,
  },
  params = json.dumps({
    'card_nonce': card_nonce,
    'amount_money': {
      'amount': 100,
      'currency': 'USD'
    },
    'idempotency_key': str(uuid.uuid1())
  })
)

print response.body

In Python, response.body is a dict that contains all of the details of the processed payment.

Learn about OAuth

So far in this tutorial, you've used your personal access token, which gives you full access to your own business' data. If you are developing an application for other businesses to use as well, you use the OAuth API to generate access tokens for those businesses.

The OAuth flow in Connect v2 is identical to the flow in v1. Learn more about the OAuth flow. Code samples for the OAuth flow are available on Github.

Important: In order for your app to process payments on behalf of another merchant, the merchant must authorize your application with the PAYMENTS_WRITE OAuth permission.