💳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

POSThttps://api.offblocks.xyz/v1/accounts/{accountId}/cards

Authorization

bearerAuth

Path parameters

accountId*AccountId (string (uuid))

ID of account

Header parameters

Body

application/json

type*CardType (enum)

Card type

virtualphysical

billingAddress*Address (object)

shippingAddressAddress (object)

Response

201400401404500

Successful operation

Body

application/json

id*AccountId (string (uuid))

accountId*AccountId (string (uuid))

type*CardType (enum)

Card type

virtualphysical

namestring

Name on the card

networkCardNetwork (enum)

Card network

visamastercard

maskedPanstring

Card PAN masked according to regulations

expirationDatestring

Expiration date of the card in MM/YYYY format

billingAddressAddress (object)

status*CardStatus (enum)

Card status

issuingissue_failedactiveinactiveblockedsuspendedterminated

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/accounts/{accountId}/cards', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text",
      "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000",
      "Content-Digest": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "type": "virtual",
      "billingAddress": {
        "firstLine": "text",
        "city": "text",
        "country": "text",
        "postCode": "text"
      }
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "text",
  "network": "visa",
  "maskedPan": "text",
  "expirationDate": "text",
  "billingAddress": {
    "firstLine": "text",
    "secondLine": "text",
    "city": "text",
    "state": "text",
    "country": "text",
    "postCode": "text"
  },
  "status": "issuing",
  "createdAt": "2024-11-21T06:21:13.048Z",
  "updatedAt": "2024-11-21T06:21:13.048Z"
}

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

GEThttps://api.offblocks.xyz/v1/accounts/{accountId}/cards

Authorization

bearerAuth

Path parameters

accountId*AccountId (any)

Unique account ID

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*AccountId (string (uuid))

accountId*AccountId (string (uuid))

type*CardType (enum)

Card type

virtualphysical

namestring

Name on the card

networkCardNetwork (enum)

Card network

visamastercard

maskedPanstring

Card PAN masked according to regulations

expirationDatestring

Expiration date of the card in MM/YYYY format

billingAddressAddress (object)

status*CardStatus (enum)

Card status

issuingissue_failedactiveinactiveblockedsuspendedterminated

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/accounts/{accountId}/cards', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text"
    },
});
const data = await response.json();

Response

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "type": "virtual",
    "name": "text",
    "network": "visa",
    "maskedPan": "text",
    "expirationDate": "text",
    "billingAddress": {
      "firstLine": "text",
      "secondLine": "text",
      "city": "text",
      "state": "text",
      "country": "text",
      "postCode": "text"
    },
    "status": "issuing",
    "createdAt": "2024-11-21T06:21:13.048Z",
    "updatedAt": "2024-11-21T06:21:13.048Z"
  }
]

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

GEThttps://api.offblocks.xyz/v1/cards

Authorization

bearerAuth

Header parameters

Response

200400401500

Successful operation

Body

application/json

id*AccountId (string (uuid))

accountId*AccountId (string (uuid))

type*CardType (enum)

Card type

virtualphysical

namestring

Name on the card

networkCardNetwork (enum)

Card network

visamastercard

maskedPanstring

Card PAN masked according to regulations

expirationDatestring

Expiration date of the card in MM/YYYY format

billingAddressAddress (object)

status*CardStatus (enum)

Card status

issuingissue_failedactiveinactiveblockedsuspendedterminated

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/cards', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text"
    },
});
const data = await response.json();

Response

200

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "type": "virtual",
    "name": "text",
    "network": "visa",
    "maskedPan": "text",
    "expirationDate": "text",
    "billingAddress": {
      "firstLine": "text",
      "secondLine": "text",
      "city": "text",
      "state": "text",
      "country": "text",
      "postCode": "text"
    },
    "status": "issuing",
    "createdAt": "2024-11-21T06:21:13.048Z",
    "updatedAt": "2024-11-21T06:21:13.048Z"
  }
]

Retrieve an Individual Card

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

Retrieve card

Retrieves card's details

GEThttps://api.offblocks.xyz/v1/cards/{cardId}

Authorization

bearerAuth

Path parameters

cardId*AccountId (string (uuid))

ID of a card to be retrieved

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*AccountId (string (uuid))

accountId*AccountId (string (uuid))

type*CardType (enum)

Card type

virtualphysical

namestring

Name on the card

networkCardNetwork (enum)

Card network

visamastercard

maskedPanstring

Card PAN masked according to regulations

expirationDatestring

Expiration date of the card in MM/YYYY format

billingAddressAddress (object)

status*CardStatus (enum)

Card status

issuingissue_failedactiveinactiveblockedsuspendedterminated

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/cards/{cardId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text"
    },
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "text",
  "network": "visa",
  "maskedPan": "text",
  "expirationDate": "text",
  "billingAddress": {
    "firstLine": "text",
    "secondLine": "text",
    "city": "text",
    "state": "text",
    "country": "text",
    "postCode": "text"
  },
  "status": "issuing",
  "createdAt": "2024-11-21T06:21:13.048Z",
  "updatedAt": "2024-11-21T06:21:13.048Z"
}

Deactivate a Card

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

Deactivate card

Deactivates card and all associated resources

PATCHhttps://api.offblocks.xyz/v1/cards/{cardId}/deactivate

Authorization

bearerAuth

Path parameters

cardId*CardId (any)

Unique card ID

Header parameters

Response

200400401404409500

Successful operation

Body

application/json

id*AccountId (string (uuid))

accountId*AccountId (string (uuid))

type*CardType (enum)

Card type

virtualphysical

namestring

Name on the card

networkCardNetwork (enum)

Card network

visamastercard

maskedPanstring

Card PAN masked according to regulations

expirationDatestring

Expiration date of the card in MM/YYYY format

billingAddressAddress (object)

status*CardStatus (enum)

Card status

issuingissue_failedactiveinactiveblockedsuspendedterminated

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/cards/{cardId}/deactivate', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text",
      "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000"
    },
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "text",
  "network": "visa",
  "maskedPan": "text",
  "expirationDate": "text",
  "billingAddress": {
    "firstLine": "text",
    "secondLine": "text",
    "city": "text",
    "state": "text",
    "country": "text",
    "postCode": "text"
  },
  "status": "issuing",
  "createdAt": "2024-11-21T06:21:13.048Z",
  "updatedAt": "2024-11-21T06:21:13.048Z"
}

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

PATCHhttps://api.offblocks.xyz/v1/cards/{cardId}/activate

Authorization

bearerAuth

Path parameters

cardId*CardId (any)

Unique card ID

Header parameters

Response

200400401404409500

Successful operation

Body

application/json

id*AccountId (string (uuid))

accountId*AccountId (string (uuid))

type*CardType (enum)

Card type

virtualphysical

namestring

Name on the card

networkCardNetwork (enum)

Card network

visamastercard

maskedPanstring

Card PAN masked according to regulations

expirationDatestring

Expiration date of the card in MM/YYYY format

billingAddressAddress (object)

status*CardStatus (enum)

Card status

issuingissue_failedactiveinactiveblockedsuspendedterminated

createdAt*DateTime (string (date-time))

ISO-8601 timestamp

updatedAt*DateTime (string (date-time))

ISO-8601 timestamp

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/cards/{cardId}/activate', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text",
      "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000"
    },
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "type": "virtual",
  "name": "text",
  "network": "visa",
  "maskedPan": "text",
  "expirationDate": "text",
  "billingAddress": {
    "firstLine": "text",
    "secondLine": "text",
    "city": "text",
    "state": "text",
    "country": "text",
    "postCode": "text"
  },
  "status": "issuing",
  "createdAt": "2024-11-21T06:21:13.048Z",
  "updatedAt": "2024-11-21T06:21:13.048Z"
}

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

DELETEhttps://api.offblocks.xyz/v1/cards/{cardId}

Authorization

bearerAuth

Path parameters

cardId*CardId (any)

Unique card ID

Header parameters

Response

204400401404409500

Successful operation

Request

JavaScriptCurlPython

const response = await fetch('https://api.offblocks.xyz/v1/cards/{cardId}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text",
      "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000"
    },
});
const data = await response.json();