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 and Cards 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 payment token used to pay the invoices.

Prepare for the walkthrough Permalink Get a link to this section

Before you begin the walkthrough, do the following:

  • Review Sandbox testing considerations to understand how you use the Square Sandbox for testing.

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

  • Create a customer and card on file in the seller's Customer Directory. The customer profile includes an email address where Square sends invoices and receipts. The card on file associated with the customer profile enables 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.

    Note

    It is also 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.

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 credit card to pay an invoice on the Square-hosted invoice page.

  • Test payment token. To prepare for this walkthrough, you use the Sandbox payment token 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.

Sandbox payment methods are never charged.

Note

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.

Gather account information Permalink Get a link to this section

Follow these steps to get the access token and location ID used in this walkthrough.

  1. Sign in to the Developer Dashboard. If you do not have a Square account, see Get Started to learn how to create an account and an application.

  2. Open your application.

  3. Get your Sandbox access token:

    1. At the top of the page, in 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 for authorization. This personal access token grants full access to the Sandbox resources in your account.

  4. Get your location ID:

    1. In the navigation pane, choose Locations.

    2. On the Locations page, keep Default Test Account selected and copy a location ID.

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

To prepare for this walkthrough, you create a customer profile in your Customer Directory and then add a card on file. 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-09-15' \
      -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",
          "version":0
       }
    }
    
  2. Copy the customer ID from the response. You use it to save a card on file in the next step and also when you create orders and invoices.

  3. Call CreateCard to associate a card on file with the customer profile.

    • Replace {ACCESS_TOKEN} with your Sandbox access token.

    • Replace the example value for customer_id with the customer ID you copied.

    Create Card
    • 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/cards \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "source_id": "cnon:card-nonce-ok",
        "card": {
          "billing_address": {
            "address_line_1": "500 Electric Ave",
            "address_line_2": "Suite 600",
            "locality": "New York",
            "administrative_district_level_1": "NY",
            "postal_code": "94103",
            "country": "US"
          },
          "cardholder_name": "John Doe",
          "customer_id": "DJREAYPRBMSSFAB4TGAexample",
          "reference_id": "alternate-id-1"
        }
      }'

    Note

    For simplicity, this walkthrough uses the Sandbox payment token for source_id. It skips the process of generating a payment token using the Web Payments SDK or In-App Payments SDK.

  4. Copy the card ID from the response. You use it to define invoice payment requests that automatically charge the card on file.

    To retrieve an existing card ID, you can call ListCards and include the customer_id query parameter.

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.

Note

If you want to share the URL of the Square-hosted invoice page with the customer directly, set the delivery_method field to SHARE_MANUALLY in your CreateInvoice request. This setting tells Square not to send the invoice to the customer. The URL is returned in the public_url field of the PublishInvoice response.

Square does not send test emails for invoices that are published in the Sandbox environment.

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-09-15' \
      -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.

  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 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 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
    • 23
    • 24
    curl https://connect.squareupsandbox.com/v2/invoices \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "invoice": {
          "order_id": "AdSjVqPCzOAQqvTnzy46VLexample",
          "primary_recipient": {
            "customer_id": "DJREAYPRBMSSFAB4TGAexample"
          },
          "delivery_method": "EMAIL",
          "payment_requests": [
            {
              "request_type": "BALANCE",
              "due_date": "2021-06-30"
            }
          ],
          "accepted_payment_methods": {
            "card": true
          }
        }
      }'

    The following example response contains the draft invoice:

    {
      "invoice": {
        "id": "inv:0-ChC9tyZuZGGkQ1op9mVTSDexample",
        "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"
        },
        "accepted_payment_methods": {
          "card": true,
          "square_gift_card": false,
          "bank_account": false
        },
        "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.

    • accepted_payment_methods are the payment methods customers can use to pay the invoice on the Square-hosted invoice page.

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

  3. 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.

  4. 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/inv%3A0-ChC9tyZuZGGkQ1op9mVTSDexample/publish \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -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, scheduled date, delivery method, and other invoice settings. For more information, see Configuring how Square processes an invoice.

    The following is an example response:

    {
      "invoice": {
        "id": "inv:0-ChC9tyZuZGGkQ1op9mVTSDexample",
        "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"
        },
        "accepted_payment_methods": {
          "card": true,
          "square_gift_card": false,
          "bank_account": false
        },
        "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.

      An example invoice that Square emails to customers, which includes a "Pay Invoice" button that opens to the invoice payment page.

    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.

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

  3. 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/inv%3A0-ChC9tyZuZGGkQ1op9mVTSDexample \
      -H 'Square-Version: 2021-09-15' \
      -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-09-15' \
      -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 sets the delivery method that Square uses for invoice-related communication with the customer to EMAIL, 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, 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
    • 32
    • 33
    • 34
    curl https://connect.squareupsandbox.com/v2/invoices \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "invoice": {
          "order_id": "8NW3YYM7Ho58Ur7k9vkLexample",
          "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"
            }
          ],
          "accepted_payment_methods": {
            "card": true,
            "square_gift_card": true
          }
        }
      }'

    Note

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

    The following is an example response:

    {
      "invoice": {
        "id": "inv:0-ChB1vUizal7VFGWas0H1Bexample",
        "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"
        },
        "accepted_payment_methods": {
          "card": true,
          "square_gift_card": true,
          "bank_account": false
        },
        "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.

    • accepted_payment_methods are the payment methods customers can use to pay the invoice on the Square-hosted invoice page. At least one payment method must be set to true. This setting is independent of any automatic payment requests for the invoice.

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

  2. 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/inv%3A0-ChB1vUizal7VFGWas0H1Bexample/publish \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -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, scheduled date, delivery method, and other invoice settings. For more information, see Configuring how Square processes an invoice.

    Note

    Square does not send emails for invoices that are published in the Sandbox environment.

    The following is an example response:

    {
      "invoice": {
        "id": "inv:0-ChB1vUizal7VFGWas0H1Bexample",
        "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"
        },
        "accepted_payment_methods": {
          "card": true,
          "square_gift_card": true,
          "bank_account": false
        },
        "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/inv%3A0-ChB1vUizal7VFGWas0H1Bexample \
      -H 'Square-Version: 2021-09-15' \
      -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.