Learn how Square handles invoice payments and how to retrieve and refund an invoice payment.
Invoices API

Pay or Refund Invoices

An invoice defines the payment schedule, supported payment methods, and other settings that determine how invoices are paid. After the invoice is published, Square manages automatic invoice payments and payments that customers make on the Square-hosted invoice payment page. Square APIs cannot be used to manage invoice payments. However, developers can use the Refunds API to refund invoice payments.

Square manages payment flows based on invoice settings, including automatic invoice payments and payments that customers make on the invoice payment page. Square APIs cannot be used to take a payment for the invoice (or the associated order) or to manage the payment status.

After an invoice is published and the scheduled_at date (if specified) is reached, Square generates and hosts a web page where the customer can pay the invoice. At this time, Square also updates the invoice by adding the public_url field with the page URL, for example: https://squareup.com/pay-invoice/inv:0-ChBoaXkM5QOPv9UO9C_Z1baX2b.

Square keeps the invoice payment page updated according to the payment schedule and payment history. If the invoice is configured for automatic payments, Square charges the specified card on file or initiates a bank transfer on the payment due date. For information about payment-related settings (such as payment_requests and accepted_payment_methods), see Configuring payment requests and Configuring how Square processes an invoice.

After an invoice payment is made, Square does the following:

  • Sets the invoice status to PAID, PAYMENT_PENDING, or PARTIALLY_PAID and sets the total_completed_amount_money of the payment request to the amount paid.

  • Adds the payment_id and other payment information to the tenders field of the associated order.

  • Sets the order state to COMPLETED when the order is fully paid.

  • Notifies the seller, if the Paid notification is enabled in the seller's notification settings.

  • Sends a receipt to the customer, as determined by the delivery_method setting for the invoice:

    • EMAIL. Square sends an email to the customer.

    • SMS. Square sends a text message to the customer unless the customer has opted out of text message updates from Square invoices.

    • SHARE_MANUALLY. Square does not send a receipt to the customer.

  • Cancels any PENDING reminders for the corresponding payment request by setting the status to NOT_APPLICABLE.

  • Invokes an invoice.payment_made webhook event, along with order.updated, payment.created, and payment.updated events.

If an automatic payment fails, Square does the following:

  • Sets the automatic_payment_source field of all payment requests for the invoice to NONE.

  • Notifies the seller.

  • Emails an invoice to the customer that contains a link to the invoice payment page where the customer can pay the amount due.

  • Invokes an invoice.scheduled_charge_failed webhook event. Depending on the cause of the failure, Square might invoke payment events, such as a payment.created with a status of FAILED.

    Error information indicating why the payment failed is not available in the webhook payload or corresponding payment. In this case, you or the seller might need to contact the customer.

Square takes no explicit action if an invoice becomes overdue. However, you can schedule reminders to be delivered if the payment is not made by the due_date of a payment request. To determine whether a payment is overdue, retrieve the invoice after the due date and compare the total_completed_amount_money.amount and computed_amount_money.amount fields in the payment request.

Note

Sellers can use the Square Seller Dashboard, Square Point of Sale, or Square Invoices application to view the payment status of an invoice and to record any payments that customers remit to them directly.

Although Square APIs cannot be used to pay an invoice, you can retrieve the corresponding Payment object after a payment is made. To do so, get the tender that represents the payment in the associated order.

  1. Call GetInvoice to retrieve the invoice, if needed.

    Get Invoice
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    Copy the order_id from the response.

  2. Call RetrieveOrder to retrieve the order.

    Retrieve Order
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The following excerpt of an example response shows the tenders field:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
     {
       "order": {
         "id": "DIxOlEityYPJtcuvKTVKT1example",
         "location_id": "P3CCK6example",
         ...
         "tenders": [
           {
             "id": "EnZdNAlWCmfh6Mt5FMN3example",
             "location_id": "P3CCK6example",
             "transaction_id": "lgwOlEityYPJtcuvKTVKT1example",
             "created_at": "2020-08-06T02:47:36.293Z",
             "amount_money": {
               "amount": 1000,
               "currency": "USD"
             },
             "type": "CARD",
             "card_details": {
               "status": "CAPTURED",
               "card": {
                 "card_brand": "AMERICAN_EXPRESS",
                 "last_4": "6550"
               },
               "entry_method": "ON_FILE"
             },
             "tip_money": {
               "amount": 0,
               "currency": "USD"
             }
           }
         ],
         ...
       }
     }
    

    Copy the id of the tender (or the payment_id if included in the tender) that corresponds to the payment you want to retrieve.

  3. Call GetPayment. For the payment_id parameter, provide the payment ID that you copied in the previous step.

    Get Payment
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/payments/{payment_id} \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

Note

Payments also appear on the Transactions page of the Seller Dashboard.

You can call the RefundPayment endpoint in the Refunds API to refund invoice payments.

The invoice status must be PAID, CANCELED, or FAILED to refund a payment. Invoices with a status of PARTIALLY_PAID must be canceled using CancelInvoice before they can be refunded.

After an invoice payment is refunded, Square invokes an invoice.refunded webhook event, along with refund.created, refund.updated, payment.updated, and order.created (for the new order that Square creates for the refund) events. The inventory.count.updated event is also invoked if the associated order was itemized using catalog objects and the seller configured the Inventory management for invoices setting to adjust inventory levels through invoices.

To refund an invoice payment, you need the ID of the tender that was recorded for the payment on the associated order. An order can have multiple tenders. You must make a separate call to RefundPayment for each tender that you want to refund.

  1. Get the order ID from the invoice. To retrieve the invoice, call GetInvoice if you have the invoice ID or call ListInvoices or SearchInvoices if you do not have the ID. The following example request calls GetInvoice:

    Get Invoice
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/invoices/{invoice_id} \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    Copy the order_id from the response.

  2. Get the tender ID from the order. To retrieve the order, call RetrieveOrder in the Orders API and provide the order ID.

    Retrieve Order
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The following excerpt of an example response shows the tenders field:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
     {
       "order": {
         "id": "DIxOlEityYPJtcuvKTVKT1example",
         "location_id": "P3CCK6example",
         ...
         "tenders": [
           {
             "id": "EnZdNAlWCmfh6Mt5FMN3example",
             "location_id": "P3CCK6example",
             "transaction_id": "lgwOlEityYPJtcuvKTVKT1example",
             "created_at": "2020-08-06T02:47:36.293Z",
             "amount_money": {
               "amount": 1000,
               "currency": "USD"
             },
             "type": "CARD",
             "card_details": {
               "status": "CAPTURED",
               "card": {
                 "card_brand": "AMERICAN_EXPRESS",
                 "last_4": "6550"
               },
               "entry_method": "ON_FILE"
             },
             "tip_money": {
               "amount": 0,
               "currency": "USD"
             }
           }
         ],
         ...
       }
     }
    

    Copy the id of the tender (or the payment_id if included in the tender). This is the payment ID that you use to refund the payment. Also note the amount paid for the tender, which is the maximum amount that you can refund for the payment.

  3. Refund the payment. Call RefundPayment in the Refunds API and provide the payment ID and the amount to refund.

    Refund Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    curl https://connect.squareupsandbox.com/v2/refunds \
      -X POST \
      -H 'Square-Version: 2022-07-20' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "payment_id": "EnZdNAlWCmfh6Mt5FMN3example",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "Optional reason for the refund."
      }'

    The following is an example response:

After a refund is processed, the invoice status changes to REFUNDED if the entire amount paid for the invoice is refunded or PARTIALLY_REFUNDED if only a portion of the payment is refunded. The original order remains unchanged and set to the COMPLETED status.

Note

Sellers can also refund invoice payments using the Seller Dashboard, Square Point of Sale, and Square Invoices application.

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