💳Cards

API reference for card-related endpoints

Creating and Ordering a New Card for a Customer

A new card for the customer can be created and ordered using the POST endpoint: /customers/{customerId}/cards. This operation creates a new card through our issuance partner with Visa or MasterCard. If a physical card is requested, it also initiates a shipment order to the specified address. Please note that each card is linked to a specific account, and currently, we only support a limit of one virtual and one physical card per customer's account.

Create new card

post

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/accounts/{accountId}/cards

Creates new card for the account

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstring · uuidRequired

Unique account ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Content-DigeststringRequired

Content digest

Body

application/json

typestring · enumRequired

Card type

Possible values:

Responses

201

Successful operation

application/json

400

Invalid request

401

Not authorised

404

Account not found

500

Internal error

post

/accounts/{accountId}/cards

HTTPcURLJavaScriptPython

POST /v1/accounts/{accountId}/cards HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Content-Digest: text
Content-Type: application/json
Accept: */*
Content-Length: 299

{
  "type": "virtual",
  "billingAddress": {
    "firstLine": "Flat G",
    "secondLine": "321 West End Lane",
    "city": "London",
    "state": "text",
    "country": "GB",
    "postCode": "NW6 2FG"
  },
  "shippingAddress": {
    "firstLine": "Flat G",
    "secondLine": "321 West End Lane",
    "city": "London",
    "state": "text",
    "country": "GB",
    "postCode": "NW6 2FG"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "John Carter",
  "network": "visa",
  "maskedPan": "530518******9871",
  "expirationDate": "10/2028",
  "billingAddress": {
    "firstLine": "Flat G",
    "secondLine": "321 West End Lane",
    "city": "London",
    "state": "text",
    "country": "GB",
    "postCode": "NW6 2FG"
  },
  "status": "issuing",
  "createdAt": "2026-06-07T03:01:29.540Z",
  "updatedAt": "2026-06-07T03:01:29.540Z"
}

Card Entity Updates

Any internal updates to the card entity will be reported through webhook update events. For details on how to set up and manage webhook subscriptions, please refer to Webhooks.

Retrieve Cards for a Specific Account

To retrieve a list of cards associated with a specific account, make a GET request to /accounts/{accountId}/cards.

Retrieve account cards

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/accounts/{accountId}/cards

Retrieves account's cards

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstring · uuidRequired

Unique account ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique card ID

accountIdstring · uuidRequired

Unique account ID

typestring · enumRequired

Card type

Possible values:

namestringOptional

Name on the card

Example: John Carter

networkstring · enumOptional

Card network

Possible values:

maskedPanstringOptional

Card PAN masked according to regulations

Example: 530518******9871

expirationDatestringOptional

Expiration date of the card in MM/YYYY format

Example: 10/2028

statusstring · enumRequired

Card status

Possible values:

createdAtstring · date-timeRequired

Date this card was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this card was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Account not found

500

Internal error

get

/accounts/{accountId}/cards

HTTPcURLJavaScriptPython

GET /v1/accounts/{accountId}/cards HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "type": "virtual",
    "name": "John Carter",
    "network": "visa",
    "maskedPan": "530518******9871",
    "expirationDate": "10/2028",
    "billingAddress": {
      "firstLine": "Flat G",
      "secondLine": "321 West End Lane",
      "city": "London",
      "state": "text",
      "country": "GB",
      "postCode": "NW6 2FG"
    },
    "status": "issuing",
    "createdAt": "2026-06-07T03:01:29.540Z",
    "updatedAt": "2026-06-07T03:01:29.540Z"
  }
]

Retrieve All Cards

To retrieve a list of all cards associated with the programme, make a GET request to /cards. To fetch details of a specific card by ID, use a GET request to /cards/{cardId}.

Retrieve cards

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/cards

Retrieves cards' details

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique card ID

accountIdstring · uuidRequired

Unique account ID

typestring · enumRequired

Card type

Possible values:

namestringOptional

Name on the card

Example: John Carter

networkstring · enumOptional

Card network

Possible values:

maskedPanstringOptional

Card PAN masked according to regulations

Example: 530518******9871

expirationDatestringOptional

Expiration date of the card in MM/YYYY format

Example: 10/2028

statusstring · enumRequired

Card status

Possible values:

createdAtstring · date-timeRequired

Date this card was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this card was updated (ISO-8601)

400

Invalid request

401

Not authorised

500

Internal error

get

/cards

HTTPcURLJavaScriptPython

GET /v1/cards HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "type": "virtual",
    "name": "John Carter",
    "network": "visa",
    "maskedPan": "530518******9871",
    "expirationDate": "10/2028",
    "billingAddress": {
      "firstLine": "Flat G",
      "secondLine": "321 West End Lane",
      "city": "London",
      "state": "text",
      "country": "GB",
      "postCode": "NW6 2FG"
    },
    "status": "issuing",
    "createdAt": "2026-06-07T03:01:29.540Z",
    "updatedAt": "2026-06-07T03:01:29.540Z"
  }
]

Retrieve an Individual Card

To retrieve information about an individual card, make a GET request to /cards/{cardId}.

Retrieve card

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/cards/{cardId}

Retrieves card's details

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cardIdstring · uuidRequired

Unique card ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique card ID

accountIdstring · uuidRequired

Unique account ID

typestring · enumRequired

Card type

Possible values:

namestringOptional

Name on the card

Example: John Carter

networkstring · enumOptional

Card network

Possible values:

maskedPanstringOptional

Card PAN masked according to regulations

Example: 530518******9871

expirationDatestringOptional

Expiration date of the card in MM/YYYY format

Example: 10/2028

statusstring · enumRequired

Card status

Possible values:

createdAtstring · date-timeRequired

Date this card was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this card was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Card not found

500

Internal error

get

/cards/{cardId}

HTTPcURLJavaScriptPython

GET /v1/cards/{cardId} HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "John Carter",
  "network": "visa",
  "maskedPan": "530518******9871",
  "expirationDate": "10/2028",
  "billingAddress": {
    "firstLine": "Flat G",
    "secondLine": "321 West End Lane",
    "city": "London",
    "state": "text",
    "country": "GB",
    "postCode": "NW6 2FG"
  },
  "status": "issuing",
  "createdAt": "2026-06-07T03:01:29.540Z",
  "updatedAt": "2026-06-07T03:01:29.540Z"
}

Deactivate a Card

To deactivate a card, use a PATCH request to /cards/{cardId}/deactivate.

Deactivate card

patch

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/cards/{cardId}/deactivate

Deactivates card and all associated resources

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cardIdstring · uuidRequired

Unique card ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique card ID

accountIdstring · uuidRequired

Unique account ID

typestring · enumRequired

Card type

Possible values:

namestringOptional

Name on the card

Example: John Carter

networkstring · enumOptional

Card network

Possible values:

maskedPanstringOptional

Card PAN masked according to regulations

Example: 530518******9871

expirationDatestringOptional

Expiration date of the card in MM/YYYY format

Example: 10/2028

statusstring · enumRequired

Card status

Possible values:

createdAtstring · date-timeRequired

Date this card was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this card was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Account not found

409

Invalid state transition

500

Internal error

patch

/cards/{cardId}/deactivate

HTTPcURLJavaScriptPython

PATCH /v1/cards/{cardId}/deactivate HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "John Carter",
  "network": "visa",
  "maskedPan": "530518******9871",
  "expirationDate": "10/2028",
  "billingAddress": {
    "firstLine": "Flat G",
    "secondLine": "321 West End Lane",
    "city": "London",
    "state": "text",
    "country": "GB",
    "postCode": "NW6 2FG"
  },
  "status": "issuing",
  "createdAt": "2026-06-07T03:01:29.540Z",
  "updatedAt": "2026-06-07T03:01:29.540Z"
}

Reactivate a Card

To reactivate a previously deactivated card, use a PATCH request to /cards/{cardId}/activate.

Activate card

patch

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/cards/{cardId}/activate

Activates card and all associated resources

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cardIdstring · uuidRequired

Unique card ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique card ID

accountIdstring · uuidRequired

Unique account ID

typestring · enumRequired

Card type

Possible values:

namestringOptional

Name on the card

Example: John Carter

networkstring · enumOptional

Card network

Possible values:

maskedPanstringOptional

Card PAN masked according to regulations

Example: 530518******9871

expirationDatestringOptional

Expiration date of the card in MM/YYYY format

Example: 10/2028

statusstring · enumRequired

Card status

Possible values:

createdAtstring · date-timeRequired

Date this card was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this card was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Account not found

409

Invalid state transition

500

Internal error

patch

/cards/{cardId}/activate

HTTPcURLJavaScriptPython

PATCH /v1/cards/{cardId}/activate HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "John Carter",
  "network": "visa",
  "maskedPan": "530518******9871",
  "expirationDate": "10/2028",
  "billingAddress": {
    "firstLine": "Flat G",
    "secondLine": "321 West End Lane",
    "city": "London",
    "state": "text",
    "country": "GB",
    "postCode": "NW6 2FG"
  },
  "status": "issuing",
  "createdAt": "2026-06-07T03:01:29.540Z",
  "updatedAt": "2026-06-07T03:01:29.540Z"
}

Terminate a Card

A card can be terminated using a DELETE request to /cards/{cardId}. This is an irreversible operation, and the card will not be available for new payments. However, it will remain active for pending holds for up to 30 days.

Terminate card

delete

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/cards/{cardId}

Terminates card

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

cardIdstring · uuidRequired

Unique card ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Responses

204

Successful operation

400

Invalid request

401

Not authorised

404

Card not found

409

Invalid state transition

500

Internal error

delete

/cards/{cardId}

HTTPcURLJavaScriptPython

DELETE /v1/cards/{cardId} HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Accept: */*

No content