API
Language
Ask for a seat

Closed beta. Nothing here is callable yet. These docs describe the day-one contract, and names marked proposed may change before the beta opens. Ask for a seat

Docs · Reference

Cards

List the owner’s debit cards and freeze one. Unfreezing stays in the Novo app.

List debit cards

GET/v1/cards

The account owner's debit cards, with the last 4 digits and status. Full card numbers and expiry dates are never returned. Card field names are not final yet.

Authentication

Bearer token whose client has the scope cards:read

Response · a list of Card

dataarray of Card

The page of results

Each item in data:

idstringrequired

The card's id

nicknamestringuntrusted text

Card nickname, when set

last_fourstringrequired

Last 4 digits of the card

statusstringrequired

Card status

typestring

physical or virtual, when available

Responses

  • 200OK
  • 401The token is missing, expired or unknown, or the client was revoked or switched off
  • 403The client lacks the scope, the owner's standing changed, or the API isn't enabled for this business
  • 429Too many requests. Wait for Retry-After
  • 500Something failed unexpectedly on Novo's side. Not retryable: quote request_id to support
  • 503Something the answer depends on is unavailable. Retry after Retry-After
Request
curl "https://$NOVO_API_HOST/v1/cards" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "nickname": "Ops card",
      "last_four": "4321",
      "status": "EXAMPLE_STATUS",
      "type": "virtual"
    }
  ]
}

Freeze a debit card

POST/v1/cards/{card_id}/freeze

Freezes the card. Freezing a card that is already frozen returns 200 with the current state. There is no unfreeze endpoint: unfreezing stays in the Novo app. card_id must be a UUID. An Idempotency-Key is recommended, not required. A card that doesn't exist, or isn't the owner's, returns 404; a card in a state that can't be frozen returns 409.

Authentication

Bearer token whose client has the scope cards:freeze

Parameters

card_idpath · stringrequired

The card's id

uuid

Idempotency-Keyheader · string

A key you choose, so that a retry is recognised as the same request

max 255 characters

Response · FreezeResult

card_idstringrequired

The card's id

uuid

statusstringrequired

frozen, including when the card was already frozen

One of frozen

request_idstring

Same as the Novo-Request-Id header

Responses

  • 200The card is frozen
  • 400A parameter is invalid. Not retryable
  • 401The token is missing, expired or unknown, or the client was revoked or switched off
  • 403The client lacks the scope, the owner's standing changed, or the API isn't enabled for this business
  • 404Nothing with that id in the bound business
  • 409The Idempotency-Key was reused or is still in flight, or the card can't be frozen
  • 413The body is over the size limit. Not retryable
  • 415The operation doesn't accept the body's content type. Not retryable
  • 429Too many requests. Wait for Retry-After
  • 500Something failed unexpectedly on Novo's side. Not retryable: quote request_id to support
  • 503Something the answer depends on is unavailable. Retry after Retry-After
Request
curl -X POST "https://$NOVO_API_HOST/v1/cards/00000000-0000-4000-8000-000000000001/freeze" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "card_id": "00000000-0000-4000-8000-000000000001",
  "status": "frozen",
  "request_id": "req_example_01"
}