---
title: "Start card setup"
method: POST
path: "/v1/account/payment-card/setup"
tags: ["account"]
---

# Start card setup

`POST /v1/account/payment-card/setup`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/account/payment-card/setup`
- Auth: HTTP bearer

Starts adding or replacing the saved card for a workspace billed directly by Brix. Returns a hosted checkout URL where the card is entered, unless `useLastPaid: true` is passed and the payment provider already holds a card that was last used to pay this workspace, in which case that card is saved directly. Returns 409 if the workspace is not billed directly by Brix, and 404 for white-label workspaces.

## Request body

- object
  - `useLastPaid` boolean: Save the card the last invoice was paid with, when that is possible, instead of opening a page.
  - `role` 'primary' | 'backup': `backup` saves a backup card, charged once when the card is declined. Default `primary`.

## Response `200`

Success.

- object
  - `data` union, required
    - object
      - `saved` true, required
      - `payment` AccountPayment, required: Payment settings of an account that Brix invoices directly.
        - `option` 'card' | 'invoice', required: How issued invoices are paid: charged to the saved card, or paid from the invoice email.
        - `card` object, nullable, required
          - `brand` string, required
          - `last4` string, nullable, required
          - `expMonth` integer, nullable, required
          - `expYear` integer, nullable, required
          - `savedAt` string, nullable, required: ISO-8601 timestamp (UTC).
        - `backupCard` object, nullable, required: Charged once when the card is declined.
          - `brand` string, required
          - `last4` string, nullable, required
          - `expMonth` integer, nullable, required
          - `expYear` integer, nullable, required
          - `savedAt` string, nullable, required: ISO-8601 timestamp (UTC).
        - `lastPaid` object, nullable, required: The card the last invoice was paid with.
          - `label` string, required: `Visa •••• 5278`.
          - `brand` string, required
          - `last4` string, required
          - `invoiceNumber` string, required
          - `paidAt` string, nullable, required: ISO-8601 timestamp (UTC).
        - `cardAvailable` boolean, required: Card payment can be set up for this workspace.
        - `invoiceEmail` string, nullable, required: One more address that gets every invoice. The owners always get them.
    - object
      - `saved` false, required
      - `url` string, required: A hosted card page. After it, call `/payment-card/complete` with the `card_session` from the return URL.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: You do not hold the permission for the whole workspace (a grant at one location is not enough).
- `404`: A workspace billed by a partner.
- `409`: `not_brix_billed`, or `card_unavailable`.
- `502`: The card page could not be opened.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)