> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify Masivo TOTP

> Check a Masivo one-time code and return that customer's wallet.

Verifies a Masivo TOTP `code` with the merchant's server API key. Spark calls Masivo's authorize endpoint, keeps the bearer token on the server, then calls Masivo verify and returns Masivo's `data` unchanged (`customer`, `wallet`, `metadata`).

> [!NOTE]
>
> Requires a Fire spark access token from [token
> exchange](https://firespark.cloud/docs/storefront-api/oauth/exchange/post.md). There is no channel or
> integration toggle for this route. It works when this environment has an
> active Masivo connection, and returns `409` `MASIVO_NOT_CONNECTED` otherwise.

The Masivo customer id is `data.customer.id`.

Pass `order_id` when a kiosk is about to hand this open order to that customer. Spark checks that the order is `OPEN` and owned by the caller, that `data.customer.id` is a customer of this merchant, and adds `customer_switch_proof`. The proof is a 60-second token signed by Fire spark. Send it to [token exchange](https://firespark.cloud/docs/storefront-api/oauth/exchange/post.md) as `subject_token`. Without `order_id`, the response stays the Masivo payload and includes no proof.

With the SDK:

```ts theme={null}
const verified = await services.masivo.verifyTotp({ code, order_id })
await auth.switchCustomer(verified)
```

`auth.switchCustomer` also accepts `verified.customer_switch_proof` on its own.

## Query parameters

| Parameter | Required | Description |
| - | - | - |
| `code` | Yes | Masivo TOTP code. Trimmed, 1–32 characters. |
| `order_id` | No | Open order to hand to the verified customer. When set, a successful response includes `customer_switch_proof`. |

## Request

```bash theme={null}
curl "https://firespark.cloud/api/storefront/v1/masivo/totp/verify?code=1234" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Response

`200` with Masivo's `data` object.

```json theme={null}
{
  "data": {
    "customer": { "id": "masivo-customer-id", "name": "Ana Pérez" },
    "wallet": { "id": "wallet-id", "totals": [] },
    "metadata": {}
  }
}
```

An invalid code is `422`. Spark keeps Masivo's `error` and `details`. Other Masivo failures use Spark's upstream mapping (`502` for rate limits and server errors) and still keep Masivo's `error` and `details` when Masivo sent them.

No active Masivo connection for this merchant and environment:

```json theme={null}
{
  "error": "This merchant has no Masivo connection.",
  "code": "MASIVO_NOT_CONNECTED",
  "details": { "code": "MASIVO_NOT_CONNECTED" }
}
```

The `error` text follows `Accept-Language` (`es`, `en`, or `pt`). The code stays `MASIVO_NOT_CONNECTED`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.