Pay or Refund Invoices

Applies to: Invoices APIInvoices API | Refunds APIRefunds API | Payments APIPayments API | Orders APIOrders API

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

An invoice defines a payment schedule, supported payment methods, and other settings that determine how it can be paid. After the invoice is published, Square manages automatic invoice payments and payments that customers make on the invoice payment page.

Square APIs cannot be used to pay for invoices or to manage their payment status. However, developers can use the Refunds APIRefunds API to refund invoice payments.

Square supports the following methods for paying invoices:

• Customers make a payment directly on the invoice payment page using an accepted payment method. The payment page is a Square-hosted web page where the customer can view and pay the invoice.
• Square initiates an automatic payment on the due date configured for a payment request.
• Customers remit payment directly to the seller, who then records the payment in the Square Dashboard, Square Point of Sale, or Square Invoices application.

Square manages payment flows based on invoice settings, such as payment_requests and accepted_payment_methods.

After an invoice is published and the scheduled_at date (if specified) is reached, Square generates the invoice payment page and adds a public_url field that contains the payment link for the invoice. The following is an example payment link:

https://squareup.com/pay-invoice/invtmp:5e22a2c2-47c1-46d6-b061-808764dfe2b9

If a customer provides payment information on this page, Square processes the payment. If the invoice is configured for automatic payments, Square charges the specified card on file on the due_date of the payment request or initiates a bank transfer if the customer approves the payment. The customer receives a request to approve the payment when the invoice is sent or the invoice is updated.

Invoice payment links are temporary and expire after a certain period. Customers can provide the email address or phone number associated with the invoice and request a new link directly from the expired payment page, so no action is required from the developer. However, if you need to share a payment link with the customer a few days or more after it was generated, you should retrieve the invoice first to automatically generate a new up-to-date link. Note that link expiry and dynamic link generation don't trigger invoice.updated webhook events.

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 payment information to 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 doesn't send a receipt to the customer.
• Cancels any PENDING reminders for the corresponding payment request by setting the reminder status to NOT_APPLICABLE.
• Triggers an invoice.payment_made webhook eventwebhook event, along with order.updated, payment.created, and payment.updated events.
• Updates the invoice payment page, Square Dashboard, Square Point of Sale, and Square Invoices application with the payment status, schedule, and history.

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.

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

  Error information indicating why the payment failed isn't 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 payment becomes overdue. However, you can schedule reminders to be sent if the payment isn't made by the due date.

For more information about payment-related invoice settings, see Configuring payment requestsConfiguring payment requests and Configuring how Square processes an invoice.Configuring how Square processes an invoice.

Although Square APIs cannot be used to pay an invoice, you can use Square APIs to retrieve payments that were made for an invoice. You can get the payment ID from the order that is associated with the invoice. Orders store a record of payments in the tenders field.

1. To retrieve the invoice, call GetInvoiceGetInvoice and provide the invoice ID. If you don't have the invoice ID, call ListInvoicesListInvoices or SearchInvoicesSearchInvoices.

   Get invoice

   cURL

   Copy

2. Copy the order_id from the response.

3. To retrieve the order, call RetrieveOrderRetrieveOrder and provide the order ID.

   Retrieve order

   cURL

   Copy

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

   Copy

   Expand

    {
      "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"
            }
          }
        ],
        ...
      }
    }

4. Copy the id of the tender that corresponds to the payment you want to retrieve. This ID represents the payment ID. Note that some tenders also include a payment_id field that contains the same ID.

5. To retrieve the payment, call GetPaymentGetPayment and provide the payment ID.

   Get payment

   cURL

   Copy

You can call the RefundPaymentRefundPayment 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 CancelInvoiceCancelInvoice before they can be refunded.

To refund an invoice payment, you must provide the corresponding payment ID. You can get this ID from the order that is associated with the invoice. Orders store a record of payments in the tenders field.

1. To retrieve the invoice, call GetInvoiceGetInvoice and provide the invoice ID. If you don't have the invoice ID, call ListInvoicesListInvoices or SearchInvoicesSearchInvoices.

   Get invoice

   cURL

   Copy

2. Copy the order_id from the response.

3. To retrieve the order, call RetrieveOrderRetrieveOrder and provide the order ID.

   Retrieve order

   cURL

   Copy

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

   Copy

   Expand

    {
      "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"
            }
          }
        ],
        ...
      }
    }

4. Copy the id of the tender that corresponds to the payment you want to refund. This ID represents the payment ID. Some tenders also include a payment_id field that contains the same ID. The amount_money field shows the maximum amount that can be refunded for the payment.

5. To refund the payment, call RefundPaymentRefundPayment and provide the payment ID and the amount to refund. For orders with multiple payments, you must make a separate call for each payment that you want to refund.

   Refund payment

   cURL

   Copy

   The following is an example response:

   Copy

   Expand

   {
     "refund": {
       "id": "EnZdNAlWCmfh6Mt5FMN3example_qOfJKjOzCyU3fZexample",
       "status": "COMPLETED",
       "amount_money": {
         "amount": 1000,
         "currency": "USD"
       },
       "payment_id": "EnZdNAlWCmfh6Mt5FMN3example",
       "order_id": "AqBDyr9oJqj4oDHj8example",
       "created_at": "2020-08-16T18:28:33Z",
       "reason": "Optional reason for the refund."
     }
   }

   Note

   The order_id in the response references the return order that Square creates for the refund operation. The source_order_id of the return order references the original order. For more information, see Order Returns and ExchangesOrder Returns and Exchanges.

The following considerations apply when refunding invoice payments:

• When an invoice payment is refunded, Square updates the invoice status to REFUNDED if the entire amount paid for the invoice is refunded or PARTIALLY_REFUNDED if only a portion is refunded.

  Square also updates the updated_at and version fields, but doesn't update the total_completed_amount_money field of the corresponding payment request. To find the amount that was refunded, retrieve the paymentretrieve the payment and check the refunded_money field. Note that customers cannot pay an invoice in the REFUNDED or PARTIALLY_REFUNDED state from the invoice payment page, so you should create a new invoice if a payment is still due.

• Square invokes an invoice.refunded webhook eventwebhook event after the refund is processed, along with refund.created, refund.updated, and payment.updated events. The inventory.count.updated event is also invoked if the order associated with the invoice was itemized using catalog objects and the seller configured the Inventory management for invoicesInventory management for invoices setting to adjust inventory levels through invoices.

• Sellers can also refund invoice payments using the Square DashboardSquare Dashboard, Square Point of SaleSquare Point of Sale, and Square InvoicesSquare Invoices application. Payments also appear on the Transactions page of the Square Dashboard.

The following are example invoice.refunded payloads for a REFUNDED invoice and a PARTIALLY_REFUNDED invoice.

{
  "merchant_id": "8QJTJCE6AZSN6",
  "location_id": "M8AKAD8160XGR",
  "type": "invoice.refunded",
  "event_id": "30f55824-298d-5dcf-9e36-f87bfdca7111",
  "created_at": "2023-01-13T21:35:00Z",
  "data": {
    "type": "invoice",
    "id": "inv:0-ChCdyLo76f9j5v1u8of0gmX4EI45",
    "object": {
      "invoice": {
        "accepted_payment_methods": {
          "bank_account": false,
          "buy_now_pay_later": false,
          "card": true,
          "square_gift_card": true,
          "cash_app_pay": false
        },
        "created_at": "2022-01-08T11:16:48Z",
        "delivery_method": "EMAIL",
        "id": "inv:0-ChCdyLo76f9j5v1u8of0gmX4EI45",
        "invoice_number": "99846834",
        "location_id": "M8AKAD8160XGR",
        "order_id": "kJqJVajFUiMTE7XkCCF3kcq9vaB",
        "payment_requests": [
          {
            "automatic_payment_source": "CARD_ON_FILE",
            "card_id": "ccof:kkr7aMBaTCQexGQl3GB",
            "computed_amount_money": {
              "amount": 5000,
              "currency": "USD"
            },
            "due_date": "2023-01-08",
            "request_type": "BALANCE",
            "tipping_enabled": false,
            "total_completed_amount_money": {
              "amount": 5000,
              "currency": "USD"
            },
            "uid": "d7c905dc-63ab-4adb-92de-ccdd7c194bd2"
          }
        ],
        "primary_recipient": {
          "customer_id": "RDWCQZA0D0YRSD2MEC687KC79W",
          "email_address": "sara.vera0101@gmail.com",
          "family_name": "Vera",
          "given_name": "Sara",
          "phone_number": "2065551234"
        },
        "public_url": "https://squareupsandbox.com/pay-invoice/invtmp:5e22a2c2-47c1-46d6-b061-808764dfe2b9",
        "status": "REFUNDED",
        "store_payment_method_enabled": false,
        "timezone": "America/Los_Angeles",
        "updated_at": "2023-01-13T21:35:00Z",
        "version": 4
      }
    }
  }
}

{
  "merchant_id": "8QJTJCE6AZSN6",
  "location_id": "M8AKAD8160XGR",
  "type": "invoice.refunded",
  "event_id": "6d97283f-60d2-535f-bb51-2de63677ae7a",
  "created_at": "2023-01-17T20:41:00Z",
  "data": {
    "type": "invoice",
    "id": "inv:0-ChBgiproSx86epKcfiVJgPDsEI45",
    "object": {
      "invoice": {
        "accepted_payment_methods": {
          "bank_account": false,
          "buy_now_pay_later": false,
          "card": true,
          "square_gift_card": true,
          "cash_app_pay": false
        },
        "created_at": "2022-12-26T18:15:09Z",
        "delivery_method": "EMAIL",
        "id": "inv:0-ChBgiproSx86epKcfiVJgPDsEI45",
        "invoice_number": "99846845",
        "location_id": "M8AKAD8160XGR",
        "order_id": "K2ZyH9ByPUtKK52MovOkq8xfvaB",
        "payment_requests": [
          {
            "automatic_payment_source": "NONE",
            "computed_amount_money": {
              "amount": 2500,
              "currency": "USD"
            },
            "due_date": "2023-01-02",
            "percentage_requested": "50",
            "request_type": "DEPOSIT",
            "tipping_enabled": false,
            "total_completed_amount_money": {
              "amount": 2500,
              "currency": "USD"
            },
            "uid": "a6c8674d-eed3-485b-87f9-7c7c688efbac"
          },
          {
            "automatic_payment_source": "NONE",
            "computed_amount_money": {
              "amount": 2500,
              "currency": "USD"
            },
            "due_date": "2023-01-17",
            "request_type": "BALANCE",
            "tipping_enabled": false,
            "total_completed_amount_money": {
              "amount": 2500,
              "currency": "USD"
            },
            "uid": "3813fc1f-83c3-4c42-9e4b-17fb01302384"
          }
        ],
        "primary_recipient": {
          "customer_id": "RDWCQZA0D0YRSD2MEC687KC79W",
          "email_address": "sara.vera0101@gmail.com",
          "family_name": "Vera",
          "given_name": "Sara",
          "phone_number": "2065551234"
        },
        "public_url": "https://squareupsandbox.com/pay-invoice/invtmp:5e22a2c2-47c1-46d6-b061-808764dfe2b9",
        "status": "PARTIALLY_REFUNDED",
        "store_payment_method_enabled": false,
        "timezone": "America/Los_Angeles",
        "updated_at": "2023-01-19T20:41:00Z",
        "version": 6
      }
    }
  }
}

For more information about invoice webhooks, see Webhooks.Webhooks.

• Invoices APIInvoices API
• API Reference: Invoices APIAPI Reference: Invoices API