> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/chord-oms/developer-tools/next-js/sdk-reference/usesquarecheckout.md).

# useSquareCheckout

{% hint style="info" %}
**This page's documentation only applies to Chord's** [**Next.js starter**](https://github.com/chordcommerce/nextjs-starter-autonomy) **prior to the release of the** [React](/chord-oms/developer-tools/react.md)**. The Next.js starter now uses the React SDK and does not use the methods documented on this page. Check out the** [**React SDK Reference**](https://docs-beta.chord.co/chord-ui/module-react-autonomy) **for complete documentation, and the** [React SDK Migration Guide](/chord-oms/developer-tools/next-js/guides/react-sdk-migration-guide.md)**for details on how to upgrade.**
{% endhint %}

The `useSquareCheckout` hook allows to checkout using Square.

## Example

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { getUserWallet } = useSquareCheckout()
}
```

## Returns

The `useSquareCheckout` hook returns an object with these properties:

| Property               | Description                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `getStates`            | A function to retrieve information about countries and states available in the system- |
| `getUserWallet`        | A function that loads information about the current user wallet.                       |
| `updateOrderAddresses` | A function used to update the order's ship address                                     |
| `updateOrderDelivery`  | A function that allows choosing the shipping option for the current order.             |
| `updateOrderPayment`   | A function that allows completing the payment step of the checkout.                    |
| `finalizeCheckout`     | A function that complete the order with Square.                                        |

## Typical flow

The typical flow is:

* Create a cart and add items into it with the `useCart` module.
* Attach an email address to the order using `modifyCart({ email: "your@email.com" })`. This is only needed for guest checkouts, if the user is logged in, this is not needed and the user's email will be used.
* Add a shipping address to the order using the `updateOrderAddresses()` function.
* Pick a delivery method using the `updateOrderDelivery()` function.
* Attempt a payment via Square using the `updateOrderPayment()` function after retrieving the Square token client-side, using the [Square Web Payment SDK](https://developer.squareup.com/docs/web-payments/overview).
* Finalize the order with `finalizeCheckout()`.

## Functions

### getStates

The `getStates` function is used to retrieve information about countries and states available in the system to be used when we need to update the order's address. It takes the [ISO code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the country and returns the list of states along with other information related to the country itself

**Arguments:**

`getStates(iso)`

| Argument | Type   | Description             |
| -------- | ------ | ----------------------- |
| `iso`    | String | ISO code of the country |

**Returns:**

`Promise<{ states: string | State[]; state_required: boolean }>`

`State`:

| Argument     | Type   | Description          |
| ------------ | ------ | -------------------- |
| `abbr`       | String | Country abbreviation |
| `name`       | String | Country name         |
| `id`         | Number | Record Id            |
| `country_id` | Number | Country Id           |

**Example:**

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { getStates } = useSquareCheckout()
}
```

### getUserWallet

The `getUserWallet` function is used to retrieve information about the user's wallet.

**Arguments:**

None

**Returns:**

`TODO`

**Example:**

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { getUserWallet } = useSquareCheckout()
}
```

### updateOrderAddresses

The `updateOrderAddresses` function is used to update the order's ship address. A valid ship address has the following format:

**Arguments:**

`updateOrderAddresses(options)`

| Argument             | Type   | Description                             |
| -------------------- | ------ | --------------------------------------- |
| `options.name`       | String | The user's name and surname             |
| `options.address1`   | String | The user's address                      |
| `options.address2?`  | String | (Optional) The user's secondary address |
| `options.city`       | String | City name                               |
| `options.country_id` | Number | Country Id                              |
| `options.state_id`   | Number | State Id                                |
| `options.zipcode`    | String | Zipcode                                 |
| `options.phone`      | String | The user's mobile phone                 |
| `options.company`    | String | The name of the company                 |

**Returns:**

`Promise<void>`: A Promise that resolves when the `order` object has been updated in Redux.

**Example:**

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { updateOrderAddresses } = useSquareCheckout()

    const shipAddressAttributes = {
      name: 'Jane Doe',
      address1: '2191 Calico Drive',
      city: 'Phoenix',
      country_id: 233,
      state_id: 3438,
      zipcode: '85022',
      phone: '509-644-9988',
      company: 'Acme Inc.'
    }

    useEffect(() => {
        updateOrderAddresses(shipAddressAttributes)
    }, [])
}
```

### updateOrderDelivery

The `updateOrderDelivery()` function allows choosing the shipping option for the current order. At the moment we do not support multiple delivery options, so this function is only needed to move the checkout from the delivery step to the payment step. During this process, shipping costs and taxes will be added to the order.

{% hint style="info" %}
This function should be called only when the order is in the delivery state, meaning that a valid address has been added to the order previously. This way it will be able to correctly pick the right delivery option based on the shipping address and correctly compute taxes based on the shipment route.
{% endhint %}

**Arguments:**

`updateOrderDelivery(options)`

| Argument                          | Type   | Description                                               |
| --------------------------------- | ------ | --------------------------------------------------------- |
| `options.payment_method_type`     | String | The payment method type. In this case it will be 'square' |
| `options.source_attributes.nonce` | String | Your token                                                |

**Returns:**

`Promise<void>`: A Promise that resolves when the `order` object has been updated in Redux.

**Example:**

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { updateOrderPayment } = useSquareCheckout()

    const paymentAttributes = {
      payment_method_type: 'square',
      source_attributes: {
        nonce: 'your-token'
      }
    }

    useEffect(() => {
        updateOrderAddresses(paymentAttributes)
    }, [])
}
```

### updateOrderPayment

The `updateOrderPayment()` function allows completing the payment step of the checkout. Before using this function, the client should retrieve a token using the [Web Payments SDK](https://developer.squareup.com/docs/web-payments/overview) provided by Square. When the order is successfully completed, the payment source will be added to the user's wallet (for authenticated users only), allowing to re-use the payment token later, without having to input the credit card information again

{% hint style="info" %}
This function should be called only when the order is in the payment state, meaning that a valid delivery option has been added to the order previously. At this stage the order is updated with shipping costs and taxes, allowing to complete the payment with the right amount.
{% endhint %}

{% hint style="info" %}
For now, this endpoint doesn't support the ability to pay with an existing token. In the future we will provide this support, allowing to re-use a previously saved credit card from the user wallets.
{% endhint %}

**Arguments:**

`updateOrderDelivery(options)`

| Argument                          | Type   | Description                                               |
| --------------------------------- | ------ | --------------------------------------------------------- |
| `options.payment_method_type`     | String | The payment method type. In this case it will be 'square' |
| `options.source_attributes.nonce` | String | Your token                                                |

**Returns:**

`Promise<void>`: A Promise that resolves when the `order` object has been updated in Redux.

**Example:**

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { updateOrderPayment } = useSquareCheckout()

    const paymentAttributes = {
      payment_method_type: 'square',
      source_attributes: {
        nonce: 'your-token'
      }
    }

    useEffect(() => {
        updateOrderPayment(paymentAttributes)
    }, [])
}
```

### finalizeCheckout

`finalizeCheckout()` is the last method that needs to be called to complete the order with Square. Call this method when you want to move the user to the thank you page and let them start a new order.

**Arguments:**

None

**Returns:**

`Promise<void>`

**Example:**

```javascript
import { useSquareCheckout } from '~/hooks/actions'

export default () => {
    const { finalizeCheckout } = useSquareCheckout()

    useEffect(() => {
        finalizeCheckout()
    }, [])
}
```

{% hint style="info" %}
This function should be called only when the order is in the "confirm" state, meaning that a valid payment has been added to the order already.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/chord-oms/developer-tools/next-js/sdk-reference/usesquarecheckout.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.