💳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

Creates new card for the account

post

/accounts/{accountId}/cards

Authorizations

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

typestring · enumrequired

Card type

Options: virtual, physical

billingAddressobjectrequired

Billing address of a cardholder

shippingAddressobject

Shipping address for the card. Required for physical cards

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.offblocks.xyz/v1/accounts/{accountId}/cards' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
  --header 'Content-Digest: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "virtual",
    "billingAddress": {
      "state": "text",
      "firstLine": "Flat G",
      "secondLine": "321 West End Lane",
      "city": "London",
      "country": "GB",
      "postCode": "NW6 2FG"
    },
    "shippingAddress": {
      "state": "text",
      "firstLine": "Flat G",
      "secondLine": "321 West End Lane",
      "city": "London",
      "country": "GB",
      "postCode": "NW6 2FG"
    }
  }'

201

400

401

404

500

201

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

Successful operation

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

Retrieves account's cards

get

/accounts/{accountId}/cards

Authorizations

Path parameters

accountIdstring · uuidrequired

Unique account ID

Header parameters

Signaturestringrequired

HTTP message signature

Signature-Inputstringrequired

HTTP message signature input

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.offblocks.xyz/v1/accounts/{accountId}/cards' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text'

200

400

401

404

500

200

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

Successful operation

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

Retrieves cards' details

get

/cards

Authorizations

Header parameters

Signaturestringrequired

HTTP message signature

Signature-Inputstringrequired

HTTP message signature input

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.offblocks.xyz/v1/cards' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text'

200

400

401

500

200

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

Successful operation

Retrieve an Individual Card

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

Retrieve card

Retrieves card's details

get

/cards/{cardId}

Authorizations

Path parameters

cardIdstring · uuidrequired

Unique card ID

Header parameters

Signaturestringrequired

HTTP message signature

Signature-Inputstringrequired

HTTP message signature input

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.offblocks.xyz/v1/cards/{cardId}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text'

200

400

401

404

500

200

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

Successful operation

Deactivate a Card

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

Deactivate card

Deactivates card and all associated resources

patch

/cards/{cardId}/deactivate

Authorizations

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.offblocks.xyz/v1/cards/{cardId}/deactivate' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000'

200

400

401

404

409

500

200

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

Successful operation

Reactivate a Card

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

Activate card

Activates card and all associated resources

patch

/cards/{cardId}/activate

Authorizations

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.offblocks.xyz/v1/cards/{cardId}/activate' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000'

200

400

401

404

409

500

200

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

Successful operation

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

Terminates card

delete

/cards/{cardId}

Authorizations

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

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.offblocks.xyz/v1/cards/{cardId}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000'

204

400

401

404

409

500

204

No body

Successful operation