Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Invoices API

Example Walkthrough: Create and Publish Invoices

In this walkthrough, you use the Invoices API to create and publish invoices and then simulate the customer experience of paying an invoice. You also use the Orders API to create orders and the Customers API to create a customer and add a card on file. These resources are created in the Square Sandbox test environment, which provides the test credit card and nonce used to pay the invoices. Sandbox credit cards are never charged.

Prepare for the walkthrough Permalink Get a link to this section

Before you begin the walkthrough, do the following:

  • Gather account information to use for your API requests. You need your Sandbox access token to authenticate API requests and your location ID to create orders and invoices.

  • Create a customer with a card on file in the seller's Customer Directory. The customer profile includes an email address where Square sends invoices and receipts and a card on file to enable automatic payments.

    The procedures in this walkthrough show you how to configure two invoices. The first procedure directs Square to email the invoice to request payment from the customer. The second procedure directs Square to automatically charge a card on file.

Review Sandbox testing considerations Permalink Get a link to this section

In this walkthrough, you create your customer, order, and invoice resources in the Sandbox. The Sandbox is an isolated server environment provisioned for each Sandbox test account. You should use the Sandbox for testing. For more information, see Test in the Sandbox.

Invoices define a payment schedule that specifies payment amounts, due dates, and whether Square should send the customer an invoice requesting payment or automatically charge a card on file. You use Sandbox test values to test both payment flows:

  • Test credit card. For example 1 of this walkthrough, you use a Sandbox test credit card to pay an invoice on the Square-hosted invoice page.

  • Test nonce. To prepare for this walkthrough, you use the Sandbox test nonce (cnon:card-nonce-ok) to add a card on file for a customer. Then, for example 2, you specify the ID of the card on file so Square can charge the card automatically.

Although your invoice settings direct Square to email the invoice, emails are not sent from the Sandbox environment.

You can also use the Sandbox Seller Dashboard to view your Sandbox resources and verify the changes that you make with the Square API.

Note

It is possible for customers to remit a payment directly to a seller using a credit card, check, cash, or other accepted form of payment. The seller can then record the payment using the Seller Dashboard, Point of Sale (POS) application, or Square Invoices application.

Gather account information Permalink Get a link to this section

Follow these steps to gather account information for your Sandbox environment:

  1. Sign in to the Developer Dashboard.

  2. Open an application. If you do not have an application, you need to create one.

  3. Get Sandbox credentials:

    1. At the top of the page, using the Sandbox and Production toggle, choose Sandbox.

    2. On the Credentials page, under Sandbox Access Token, choose Show, and then copy the token. All Square API requests require an access token. This Sandbox access token grants full access to the Sandbox resources in your account.

  4. Get a location ID:

    1. In the navigation pane, choose Locations.

    2. On the Locations page, copy an ID from the Location ID column. Many Square API requests require a location ID.

Create a customer with a card on file Permalink Get a link to this section

In this step, you create a customer profile in your Customer Directory and then add a card on file. For this walkthrough, you can run the cURL commands in a terminal window.

  1. Call CreateCustomer to create a customer profile with an email address. Square sends invoices and receipts to the email address in the Production environment but not in the Sandbox.

    Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string. A unique idempotency key guarantees that Square processes a request only once.

    Create Customer
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    curl https://connect.squareupsandbox.com/v2/customers \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "email_address": "johndoe@company.com",
        "given_name": "John",
        "family_name": "Doe"
      }'

    The following is an example response:

    {
       "customer":{
          "id":"DJREAYPRBMSSFAB4TGAexample",
          "created_at":"2021-05-30T18:38:16.973Z",
          "updated_at":"2021-05-30T18:38:17Z",
          "given_name":"John",
          "family_name":"Doe",
          "email_address":"johndoe@company.com",
          "preferences":{
             "email_unsubscribed":false
          },
          "creation_source":"THIRD_PARTY"
       }
    }
    
  1. Copy the customer ID from the response. You use it to create a customer card in the next step and also when you create order and an invoice.

  1. Call CreateCustomerCard to add a card on file to the customer profile.

    • Replace {ACCESS_TOKEN} with your Sandbox access token.

    • Replace the example customer ID in the path with the customer ID you copied.

    Create Customer Card
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    curl https://connect.squareupsandbox.com/v2/customers/DJREAYPRBMSSFAB4TGAexample/cards \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "card_nonce": "cnon:card-nonce-ok"
      }'

    Note

    For simplicity, this walkthrough uses the Sandbox test nonce and skips the process required to generate your own nonce. For more information, see Manage cards on file.

    The following is an example response:

    {
       "card":{
          "id":"ccof:aC1D4q9aUXTkexample",
          "card_brand":"AMERICAN_EXPRESS",
          "last_4":"6550",
          "exp_month":5,
          "exp_year":2022
       }
    }
    
  2. Copy the card ID. You use it to define invoice payment requests that automatically charge the card on file.

    You can also call RetrieveCustomer or ListCustomers to retrieve a card ID. The IDs of the cards on file for the customer are listed in the cards field.

Invoice example 1: Send an invoice to request payment in full Permalink Get a link to this section

In this example, you create an order, create an invoice for the order, and then publish the invoice. The invoice settings direct Square to send an invoice to the customer requesting one payment for the full order amount. Then, you pay the invoice on the Square-hosted invoice page and retrieve the invoice to verify the payment status.

Create an order Permalink Get a link to this section

In this step, you create an order to associate with your invoice. To create the invoice in the next step, you must provide the ID of an order that was created using the Orders API.

  1. Call CreateOrder to create a sample order for a $1.00 item.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.

    • Replace the example values for location_id and customer_id with your actual values.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "S8GWD5example",
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "line_items": [
            {
              "name": "Example Item",
              "quantity": "1",
              "base_price_money": {
                "amount": 100,
                "currency": "USD"
              }
            }
          ]
        }
      }'

    The following is an excerpt of the example response:

    {
      "order": {
        "id": "AdSjVqPCzOAQqvTnzy46VLexample",
        "location_id": "S8GWD5example",
        "line_items": [
          {
             ...
          }
        ],
        ...
        "total_money": {
          "amount": 100,
          "currency": "USD"
        },
        ...
        "customer_id": "DJREAYPRBMSSFAB4TGAexample"
      }
    }
    

    When you create an invoice, the Invoices API uses the total_money of the associated order to calculate percentage-based payments and ensure that the sum of all invoice payment requests equals the total order amount.

  1. Copy the order ID from the response. You use it in the next step to create an invoice.

Create and publish an invoice Permalink Get a link to this section

In this step, you create a draft invoice and then publish it. Square takes no action on an invoice until it is published.

  1. Call CreateInvoice to create a draft invoice. The invoice in this example specifies one payment request for the full order amount, due by the specified date. It also directs Square to use email to send invoice-related communication to the customer.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.

    • Replace the example values for order_id, location_id, and customer_id with your actual values.

    • Replace the example due date with a date in YYYY-MM-DD format.

    Create Invoice
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    curl https://connect.squareupsandbox.com/v2/invoices \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "invoice": {
          "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
          "location_id": "S8GWD5example",
          "primary_recipient": {
            "customer_id": "DJREAYPRBMSSFAB4TGAexample"
          },
          "delivery_method": "EMAIL",
          "payment_requests": [
            {
              "request_type": "BALANCE",
              "due_date": "2021-06-30"
            }
          ]
        }
      }'

    The following is an example response, which contains the draft invoice:

    {
      "invoice": {
        "id": "5WYzEeTbOJjmOt9example",
        "version": 0,
        "location_id": "S8GWD5example",
        "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
        "payment_requests": [
          {
            "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",
            "request_type": "BALANCE",
            "due_date": "2021-06-30",
            "computed_amount_money": {
              "amount": 100,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "automatic_payment_source": "NONE"
          }
        ],
        "invoice_number": "000006",
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "created_at": "2021-05-30T19:01:32Z",
        "updated_at": "2021-05-30T19:01:32Z",
        "primary_recipient": {
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "johndoe@company.com"
        },
        "delivery_method": "EMAIL"
      }
    }
    

    Note the following invoice fields:

    • version is 0 because this is the first version of the invoice.

    • status is DRAFT because the invoice has not been published.

    • computed_amount_money is the amount due for the payment request.

    • total_completed_amount_money is the amount the customer has paid for the payment request, in this case 0.

    • primary_recipient includes additional customer profile information retrieved by the Invoices API.

  1. Copy the invoice ID from the response. You use it to publish and retrieve the invoice.

  1. Optionally, review the draft invoice in the Sandbox Seller Dashboard as follows:

    1. Sign in to the Developer Dashboard.

    2. In the Sandbox Test Accounts section, choose Open for the Default Test Account.

    3. In the navigation pane, choose Invoices.

    4. Verify that the unpaid invoice is created and that the status is DRAFT.

  1. Call PublishInvoice to publish the draft invoice.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.

    • Replace the example invoice ID in the path with your actual invoice ID.

    Publish Invoice
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    curl https://connect.squareupsandbox.com/v2/invoices/5WYzEeTbOJjmOt9example/publish \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "version": 0,
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    Square generates the invoice page and processes the invoice based on the payment requests, delivery method, and other invoice settings. For more information, see Configuring how Square processes an invoice.

    The following is an example response:

    {
      "invoice": {
        "id": "5WYzEeTbOJjmOt9example",
        "version": 1,
        "location_id": "S8GWD5example",
        "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
        "payment_requests": [
          {
            "uid": "ccc0fc9b-c2a5-42a9-836d-92d01example",            
            "request_type": "BALANCE",
            "due_date": "2021-06-30",
            "computed_amount_money": {
              "amount": 100,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "automatic_payment_source": "NONE"
          }
        ],
        "invoice_number": "000006",
        "public_url": "https://squareupsandbox.com/pay-invoice/5WYzEeTbOJjmOt9example",
        "status": "UNPAID",
        "timezone": "America/Los_Angeles",
        "created_at": "2021-05-30T19:01:32Z",
        "updated_at": "2021-05-30T19:05:01Z",
        "primary_recipient": {
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "johndoe@company.com"
        },
        "next_payment_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "delivery_method": "EMAIL"
      }
    }
    

    The published invoice has the following changes:

    • version changed to 1.

    • status changed from DRAFT to UNPAID.

    • public_url is added to the invoice. This is the URL to the Square-hosted invoice page. The customer can go to this page to pay.

    • next_payment_amount_money is added to the invoice. This example requests one payment in full, so the amount equals the total order amount. If you request multiple payments, the field shows the amount that is due next based on the payment schedule. If one or more payments are overdue, the field includes the overdue amount. For example, consider an invoice for $2 that requires a deposit of $1 and the balance of $1 at a later date. If the deposit is overdue, this field indicates $2 as the next payment amount.

      The following is an example email sent to the customer. The customer can choose Pay Invoice to open the Square-hosted invoice page and make a payment.

      invoices-example-invoice

    Although your invoice settings direct Square to email the invoice, emails are not sent from the Sandbox. If you publish the invoice in the Production environment, Square emails the invoice to both the seller and the customer.

Pay the invoice and verify status Permalink Get a link to this section

The customer has the following options to pay the invoice:

  • Choose Pay Invoice in the emailed invoice to open the Square-hosted invoice page and pay the invoice.

  • Contact the seller and pay by credit card, cash, or other accepted payment method. Sellers can record the payment in the Seller Dashboard, POS application, or Square Invoices application.

In this step, you pay the invoice on the Square-hosted invoice page.

  1. Open the Square-hosted invoice page. You can find the page URL in the public_url field in the PublishInvoice response.

  1. Use the Sandbox test credit card information to pay the invoice.

  1. Call GetInvoice to retrieve the invoice and verify status.

    • Replace {ACCESS_TOKEN} with your Sandbox access token.

    • Replace the example invoice ID in the path with your actual invoice ID.

    Get Invoice
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/invoices/5WYzEeTbOJjmOt9example \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    If you paid in full, the invoice in the response has the following changes:

    • status is PAID.

    • total_completed_amount_money specifies 100 for the amount paid.

    • next_payment_amount_money is removed from the invoice.

    You can also verify the changes in the Sandbox Seller Dashboard.

Invoice example 2: Charge a card on file for deposit and balance payments Permalink Get a link to this section

In this example, you create an order, create an invoice for the order, and then publish the invoice. The invoice settings direct Square to automatically charge a card on file for a deposit when the invoice is published and a balance at a later date. Then, you retrieve the invoice to verify the payment status.

Create an order Permalink Get a link to this section

In this step, you create an order to associate with your invoice. To create the invoice in the next step, you must provide the ID of an order that was created using the Orders API.

  1. Call CreateOrder to create a sample order for $4.00.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.

    • Replace the example values for location_id and customer_id with your actual values.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    curl https://connect.squareupsandbox.com/v2/orders \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "S8GWD5example",
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "line_items": [
            {
              "name": "Example Item",
              "quantity": "1",
              "base_price_money": {
                "amount": 400,
                "currency": "USD"
              }
            }
          ]
        }
      }'
  2. Copy the order ID from the response. You use it in the next step to create an invoice.

Create and publish an invoice Permalink Get a link to this section

In this step, you create a draft invoice and then publish it. Square takes no action on an invoice until it is published.

  1. Call CreateInvoice to create a draft invoice. The invoice in this example specifies a deposit payment request for 25% of the order amount and a balance payment request. Both payment requests direct Square to charge a card on file and provide the card ID. The invoice also directs Square to use email to send invoice-related communication to the customer, which is required for automatic payments.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.

    • Replace the example values for order_id, location_id, customer_id, and card_id with your actual values.

    • Replace the example values for due_date with dates in YYYY-MM-DD format. Use the current date for the deposit (so Square charges the card immediately and you can verify the charge) and a future date for the balance.

    Create Invoice
    • 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
    curl https://connect.squareupsandbox.com/v2/invoices \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "invoice": {
          "order_id": "8NW3YYM7Ho58Ur7k9vkLexample",
          "location_id": "S8GWD5example",
          "primary_recipient": {
            "customer_id": "DJREAYPRBMSSFAB4TGAexample"
          },
          "delivery_method": "EMAIL",
          "payment_requests": [
            {
              "request_type": "DEPOSIT",
              "due_date": "2021-05-30",
              "percentage_requested": "25",
              "automatic_payment_source": "CARD_ON_FILE",
              "card_id": "ccof:aC1D4q9aUXTkexample"
            },
            {
              "request_type": "BALANCE",
              "due_date": "2021-06-15",
              "automatic_payment_source": "CARD_ON_FILE",
              "card_id": "ccof:aC1D4q9aUXTkexample"
            }
          ]
        }
      }'

    Note

    Instead of specifying percentage-based payment amounts, you can specify exact amounts. If you do, the sum of the amounts must match the total_money of the order. For more information, see Payment requests.

    The following is an example response:

    {
      "invoice": {
        "id": "rSb5fMrHWOQRL6xexample",
        "version": 0,
        "location_id": "S8GWD5example",
        "order_id": "8NW3YYM7Ho58Ur7k9vkLexample",
        "payment_requests": [{
          "uid": "968d4546-3d4b-4be7-8411-cddcbexample",
          "request_type": "DEPOSIT",
          "due_date": "2021-05-30",
          "percentage_requested": "25",
          "card_id": "ccof:aC1D4q9aUXTkexample",
          "computed_amount_money": {
            "amount": 100,
            "currency": "USD"
          },
          "total_completed_amount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "automatic_payment_source":"CARD_ON_FILE"
        },
        {
          "uid": "8e1e2012-c9fc-491b-9545-6380fexample",
          "request_type": "BALANCE",
          "due_date": "2021-06-15",
          "card_id": "ccof:aC1D4q9aUXTkexample",
          "computed_amount_money": {
            "amount": 300,
            "currency": "USD"
          },
          "total_completed_amount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "automatic_payment_source":"CARD_ON_FILE"
        }],
        "invoice_number": "000007",
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "created_at": "2021-05-30T03:09:48Z",
        "updated_at": "2021-05-30T03:09:48Z",
        "primary_recipient": {
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "johndoe@company.com"
        },
        "delivery_method": "EMAIL"
      }
    }
    

    Note the following invoice fields:

    • version is 0 because this is the first version of the invoice.

    • status is DRAFT because the invoice has not been published.

    • computed_amount_money is the amount due for each payment request.

    • total_completed_amount_money is the amount the customer has paid for the payment request.

    You can review the draft invoice in the Sandbox Seller Dashboard as described in the first walkthrough example.

  1. Call PublishInvoice to publish the invoice.

    • Replace {ACCESS_TOKEN} with your Sandbox access token and {UNIQUE_KEY} with a unique string.

    • Replace the example invoice ID in the path with your actual invoice ID.

    Publish Invoice
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    curl https://connect.squareupsandbox.com/v2/invoices/rSb5fMrHWOQRL6xexample/publish \
      -X POST \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "version": 0,
        "idempotency_key": "{UNIQUE_KEY}"
      }'

    Square generates the invoice page and processes the invoice based on the payment requests, delivery method, and other invoice settings. For more information, see Configuring how Square processes an invoice.

    The following is an example response:

    {
      "invoice": {
        "id": "rSb5fMrHWOQRL6xexample",
        "version": 1,
        "location_id": "S8GWD5example",
        "order_id": "8NW3YYM7Ho58Ur7k9vkLexample",
        "payment_requests": [
          {
            "uid": "968d4546-3d4b-4be7-8411-cddcbexample",
            "request_type": "DEPOSIT",
            "due_date": "2021-05-30",
            "percentage_requested": "25",
            "card_id": "ccof:aC1D4q9aUXTkexample",
            "computed_amount_money": {
              "amount": 100,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "automatic_payment_source": "CARD_ON_FILE"
          },
          {
            "uid": "8e1e2012-c9fc-491b-9545-6380fexample",
            "request_type": "BALANCE",
            "due_date": "2021-05-30",
            "card_id": "ccof:aC1D4q9aUXTkexample",
            "computed_amount_money": {
              "amount": 300,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "automatic_payment_source": "CARD_ON_FILE"
          }
        ],
        "invoice_number": "000007",
        "public_url": "https://squareupsandbox.com/pay-invoice/rSb5fMrHWOQRL6xexample",
        "status": "UNPAID",
        "timezone": "America/Los_Angeles",
        "created_at": "2021-05-30T03:09:48Z",
        "updated_at": "2021-05-30T03:12:33Z",
        "primary_recipient": {
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "given_name": "John",
          "family_name": "Doe",
          "email_address": "johndoe@company.com"
        },
        "next_payment_amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "delivery_method": "EMAIL"
      }
    }
    

    The published invoice has the following changes:

    • version is incremented. The value depends on whether Square started processing the payment before returning the response.

    • status changed from DRAFT to UNPAID or PAYMENT_PENDING. The value depends on whether Square started processing the payment before returning the response.

    • public_url is added to the invoice. This is the URL to the Square-hosted invoice page. The customer can go to this page to pay.

    • next_payment_amount_money is added to the invoice.

      Soon after the invoice is published, Square charges the customer's card on file if you specified the current date for the deposit. Square sends an invoice receipt to both the seller and customer (in the Production environment only). If the due date is in the future, the customer can optionally choose Make Early Payment to pay the invoice sooner.

Verify the invoice status Permalink Get a link to this section

In this step, you verify that Square automatically charged the card on file for the deposit amount.

  1. Call GetInvoice to retrieve the invoice and verify status.

    • Replace {ACCESS_TOKEN} with your Sandbox access token.

    • Replace the example invoice ID in the path with your actual invoice ID.

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

    After Square charges the card for the deposit, the invoice in the response has the following changes:

    • status changed to PARTIALLY_PAID.

    • total_completed_amount_money for the deposit is 100, which equals the computed_amount_money and indicates that the deposit was paid.

    • next_payment_amount_money is 300, which is the amount of the balance payment request.

    You can also verify the changes in the Sandbox Seller Dashboard or on the Square-hosted invoice page.