7️⃣Card Issuance

This step assumes you have successfully created a new account record using Account Creationstep of the guide

Now that you have created a customer account, you are able to issue cards for the account. To do so, you need to use /accounts/{accountId}/card POST request.

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-12-21T11:53:28.914Z",
  "updatedAt": "2024-12-21T11:53:28.914Z"
}

Let's say we want to open a new virtual card (physical cards are not supported at the moment):

{
  "type": "virtual",
  "billingAddress": {
    "firstLine": "1 Test Avenue",
    "city": "London",
    "country": "GB",
    "postCode": "SW1 1AA"
  }
}

If everything was successful, you will receive a response with status 201 (Created) which looks similar to the following:

{
    "accountId": "ae61c362-4136-49af-8e01-544457fe265b",
    "billingAddress": {
        "city": "London",
        "country": "GB",
        "firstLine": "1 Test Avenue",
        "postCode": "SW1 1AA"
    },
    "createdAt": "2024-01-12T15:12:26.923705379Z",
    "id": "fc4912aa-cac9-4bb0-a6a7-6ec50bf45879",
    "status": "issuing",
    "type": "virtual",
    "updatedAt": "2024-01-12T15:12:26.923705379Z"
}

At this stage, you can use our Simulator to issue or fail a pending card issuance request.

Assuming you would like to issue the card and proceed with next steps, you need to make an empty PATCH request to /simulator/cards/{cardId}/issue.

Issue card

Simulates card issuing success

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

Authorization

bearerAuth

Path parameters

cardId*AccountId (string (uuid))

ID of card to be issued

Header parameters

Response

202400401404500

Successful operation

Request

JavaScriptCurlPython

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

If your request was successful, you will receive an empty response with status 202 (Accepted).

In our Sandbox environment the card will be automatically issued and activated, which you can verify by making a GET request to /cards/{cardId}.

Retrieve card

Retrieves card's details

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

Authorization

bearerAuth

Path parameters

cardId*CardId (any)

Unique card 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/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-12-21T11:53:28.914Z",
  "updatedAt": "2024-12-21T11:53:28.914Z"
}

{
    "accountId": "ae61c362-4136-49af-8e01-544457fe265b",
    "billingAddress": {
        "city": "London",
        "country": "GB",
        "firstLine": "1 Test Avenue",
        "postCode": "SW1 1AA"
    },
    "createdAt": "2024-01-12T15:12:26.923705Z",
    "id": "fc4912aa-cac9-4bb0-a6a7-6ec50bf45879",
    "status": "active",
    "type": "virtual",
    "updatedAt": "2024-01-12T15:16:03.983949Z"
}

From there we can proceed to simulating card authorisations and transactions.