You can pay for your orders with the Payments API (the CreatePayment endpoint) or with the Orders API (the PayOrder endpoint).
Orders API

Pay for Orders

When applications want to pay for an order using a single payment, they can use the Payments API (CreatePayment endpoint). Note the following:

  • The CreatePayment request must include an order ID.

  • The payment amount must match the order total (the total_money in the Order).

The following CreatePayment example charges the specified payment source $2 to pay for the specified order:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "source_id": "{PAYMENT_SOURCE_ID}",
    "reference_id": "123456",
    "order_id": "{ORDER_ID}"
  }'

For more information about how to use payments, see the Take Payments.

Sometimes applications might want to apply multiple payments to an order. For example, first pay a portion using a gift card and then apply a credit card for the rest of the amount. To apply multiple payments to an order, applications must use the Orders API (PayOrder endpoint). These payments must be previously authorized (see Delayed capture). For example, to pay for an order using three payments, you do the following:

  • Call CreatePayment three times. In each request, you specify the order ID and set the autocomplete field to false (to obtain only authorization).

  • Call PayOrder by specifying the authorized payment IDs. The endpoint captures the previously authorized payments. The endpoint also sets the order state to COMPLETED, provided that:

    • The sum of all these payments is equal to the order total (total_money).

    • The order does not include fulfillment.

      Note

      If the order includes fulfillment, you call UpdateOrder to explicitly set both the fulfillment and the order state.

The following PayOrder example pays for an order by specifying payment IDs of previously authorized payments:

Pay Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareupsandbox.com/v2/orders/{order_id}/pay \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order_version": "{ORDER_VERSION}",
    "payment_ids": [
      "{PAYMENT_ID1}",
      "{PAYMENT_ID2}"
    ]
  }'

Suppose you create an order for $20 and apply a $20 discount. You then need to make a $0 payment to set the order state to COMPLETED. Applications can use either the Payments API or Orders API.

  • Using the Payments API. You can use the CreatePayment endpoint to record a $0 CASH or EXTERNAL payment for an order.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    curl https://connect.squareupsandbox.com/v2/payments \
      -X POST \
      -H 'Square-Version: 2022-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "idempotency_key": "{UNIQUE_KEY}",
        "source_id": "CASH",
        "order_id": "{ORDER_ID}",
        "cash_details": {
          "buyer_supplied_money": {
            "amount": 0,
            "currency": "USD"
          },
          "change_back_money": {
            "amount": 0,
            "currency": "USD"
          }
        }
      }'
  • Using the Orders API. You can use the PayOrder endpoint to apply a $0 payment. The request does not include any payment IDs.

    Pay Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    curl https://connect.squareupsandbox.com/v2/orders/{order_id}/pay \
      -X POST \
      -H 'Square-Version: 2022-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}"
      }'

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.