Pay or Refund Invoices
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 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 Seller Dashboard, Square Point of Sale, or Square Invoices application.
Note
Applications cannot use Square APIs to take payments for invoices or to manage their payment status. In addition, after an order is associated with an invoice, Square APIs cannot be used to pay the order directly.
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 the public_url
field to the invoice. The following is an example payment page URL:
https://squareup.com/pay-invoice/inv:0-ChBoaXkM5QOPv9UO9C_Z1baX2b
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 buyer approves the payment. The buyer receives a request to approve the payment when the invoice is sent or the invoice is updated.
After an invoice payment is made, Square does the following:
Sets the invoice
status
toPAID
,PAYMENT_PENDING
, orPARTIALLY_PAID
and sets thetotal_completed_amount_money
of the payment request to the amount paid.Adds payment information to the associated order.
Sets the order
state
toCOMPLETED
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 reminder status toNOT_APPLICABLE
.Invokes an
invoice.payment_made
webhook event, along withorder.updated
,payment.created
, andpayment.updated
events.Updates the invoice payment page, Seller 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 toNONE
.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 apayment.created
with a status ofFAILED
.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 payment becomes overdue. However, you can schedule reminders to be sent if the payment is not made by the due date.
Note
If needed, you can determine whether a payment is overdue by retrieving the invoice after the due date and comparing the total_completed_amount_money
and computed_amount_money
amounts in the payment request.
For more information about payment-related invoice settings, see Configuring payment requests and 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.
To retrieve the invoice, call GetInvoice and provide the invoice ID. If you do not have the invoice ID, call ListInvoices or SearchInvoices.
Copy the
order_id
from the response.To retrieve the order, call RetrieveOrder and provide the order ID.
The following excerpt of an example response shows the
tenders
field: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 apayment_id
field that contains the same ID.To retrieve the payment, call GetPayment and provide the payment ID.
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.
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.
To retrieve the invoice, call GetInvoice and provide the invoice ID. If you do not have the invoice ID, call ListInvoices or SearchInvoices.
Copy the
order_id
from the response.To retrieve the order, call RetrieveOrder and provide the order ID.
The following excerpt of an example response shows the
tenders
field: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 apayment_id
field that contains the same ID. Theamount_money
field shows the maximum amount that can be refunded for the payment.To refund the payment, call RefundPayment 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.
The following is an example response:
Note
The
order_id
in the response references the return order that Square creates for the refund operation. Thesource_order_id
of the return order references the original order. For more information, see Order Returns and Exchanges.
The following considerations apply when refunding invoice payments:
When an invoice payment is refunded, Square updates the invoice
status
toREFUNDED
if the entire amount paid for the invoice is refunded orPARTIALLY_REFUNDED
if only a portion is refunded.Square also updates the
updated_at
andversion
fields, but does not update thetotal_completed_amount_money
field of the corresponding payment request. To find the amount that was refunded, retrieve the payment and check therefunded_money
field. Note that customers cannot pay an invoice in theREFUNDED
orPARTIALLY_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 event after the refund is processed, along withrefund.created
,refund.updated
, andpayment.updated
events. Theinventory.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 invoices setting to adjust inventory levels through invoices.Sellers can also refund invoice payments using the Seller Dashboard, Square Point of Sale, and Square Invoices application. Payments also appear on the Transactions page of the Seller Dashboard.
The following are example invoice.refunded
payloads for a REFUNDED
invoice and a PARTIALLY_REFUNDED
invoice.
For more information about invoice webhooks, see Webhooks.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.