8️⃣Card Authorisations

This step assumes you have successfully issued a card using Card Issuancestep of this guide

Now that you have created a customer account and issued a first card, you are able to simulate card authorisations and process simulated transactions. To do so, you need to use /simulator/cards/{cardId}/authorisation POST request.

Initiate card authorisation

Simulates card authorisation

POSThttps://api.offblocks.xyz/v1/simulator/cards/{cardId}/authorisation

Authorization

bearerAuth

Path parameters

cardId*AuthorisationId (string (uuid))

ID of card

Header parameters

Body

application/json

amount*Decimal (string (decimal))

Decimal number

currency*string

Authorisation currency (ISO-4217)

capture*boolean

Whether to capture the authorisation immediately

Response

201400401404500

Successful operation

Body

application/json

id*AuthorisationId (string (uuid))

accountId*AuthorisationId (string (uuid))

cardIdAuthorisationId (string (uuid))

status*AuthorisationStatus (enum)

Authorisation status

pendingcapturingcapturedreleasingreleased

amount*Decimal (string (decimal))

Decimal number

currency*string

Currency of the account (ISO-4217)

merchantAmount*Decimal (string (decimal))

Decimal number

merchantCurrency*string

Origin currency of the merchant (ISO-4217)

exchangeRate*Decimal (string (decimal))

Decimal number

merchant*Merchant (object)

Merchant information

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/simulator/cards/{cardId}/authorisation', {
    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({
      "amount": "text",
      "currency": "text",
      "capture": true
    }),
});
const data = await response.json();

Response

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "cardId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "amount": "text",
  "currency": "text",
  "merchantAmount": "text",
  "merchantCurrency": "text",
  "exchangeRate": "text",
  "merchant": {
    "id": "text",
    "name": "text",
    "mcc": 0,
    "country": "text",
    "city": "text"
  },
  "createdAt": "2024-12-21T11:56:58.157Z",
  "updatedAt": "2024-12-21T11:56:58.157Z"
}

Let's say we want to create an authorisation for €20 and automatically capture the funds:

{
  "amount": "20.0",
  "currency": "EUR",
  "capture": true
}

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",
    "amount": "20",
    "cardId": "fc4912aa-cac9-4bb0-a6a7-6ec50bf45879",
    "createdAt": "2024-01-12T15:22:29.451485Z",
    "currency": "EUR",
    "exchangeRate": "1",
    "id": "532a52af-9f68-429b-8945-184773d0889d",
    "merchant": {
        "city": "London",
        "country": "GB",
        "id": "TEST",
        "mcc": 9999,
        "name": "Test Merchant"
    },
    "merchantAmount": "20",
    "merchantCurrency": "EUR",
    "status": "pending",
    "updatedAt": "2024-01-12T15:22:29.905768Z"
}

As automatic capture happens asynchronously, you can verify it has been successfully captured and a new transaction created and processed by first making a GET request to /authorisations/{authorisationId}.

Retrieve authorisation details

Retrieves authorisation's details

GEThttps://api.offblocks.xyz/v1/authorisations/{authorisationId}

Authorization

bearerAuth

Path parameters

authorisationId*AuthorisationId (string (uuid))

ID of the authorisation

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*AuthorisationId (string (uuid))

accountId*AuthorisationId (string (uuid))

cardIdAuthorisationId (string (uuid))

status*AuthorisationStatus (enum)

Authorisation status

pendingcapturingcapturedreleasingreleased

amount*Decimal (string (decimal))

Decimal number

currency*string

Currency of the account (ISO-4217)

merchantAmount*Decimal (string (decimal))

Decimal number

merchantCurrency*string

Origin currency of the merchant (ISO-4217)

exchangeRate*Decimal (string (decimal))

Decimal number

merchant*Merchant (object)

Merchant information

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/authorisations/{authorisationId}', {
    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",
  "cardId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "amount": "text",
  "currency": "text",
  "merchantAmount": "text",
  "merchantCurrency": "text",
  "exchangeRate": "text",
  "merchant": {
    "id": "text",
    "name": "text",
    "mcc": 0,
    "country": "text",
    "city": "text"
  },
  "createdAt": "2024-12-21T11:56:58.157Z",
  "updatedAt": "2024-12-21T11:56:58.157Z"
}

{
    "accountId": "ae61c362-4136-49af-8e01-544457fe265b",
    "amount": "20",
    "cardId": "fc4912aa-cac9-4bb0-a6a7-6ec50bf45879",
    "createdAt": "2024-01-12T15:22:29.451485Z",
    "currency": "EUR",
    "exchangeRate": "1",
    "id": "532a52af-9f68-429b-8945-184773d0889d",
    "merchant": {
        "city": "London",
        "country": "GB",
        "id": "TEST",
        "mcc": 9999,
        "name": "Test Merchant"
    },
    "merchantAmount": "20",
    "merchantCurrency": "EUR",
    "status": "captured",
    "updatedAt": "2024-01-12T15:22:30.2762Z"
}

And then making a GET request to /transactions/{transactionId} with the same ID.

Retrieve transaction details

Retrieves transaction's details

GEThttps://api.offblocks.xyz/v1/transactions/{transactionId}

Authorization

bearerAuth

Path parameters

transactionId*AuthorisationId (string (uuid))

ID of the transaction

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*AuthorisationId (string (uuid))

accountId*AccountId (any)

Unique account ID

cardIdAuthorisationId (string (uuid))

authorisationIdAuthorisationId (string (uuid))

status*TransactionStatus (enum)

Transaction status

processingprocessedreversingreversed

direction*TransactionDirection (enum)

Direction of the transaction

debitcredit

amount*Decimal (string (decimal))

Decimal number

currency*string

Currency of the transaction (ISO-4217)

merchantAmount*Decimal (string (decimal))

Decimal number

merchantCurrency*string

Origin currency of the merchant (ISO-4217)

exchangeRate*Decimal (string (decimal))

Decimal number

merchant*Merchant (object)

Merchant information

tokenAmount*Decimal (string (decimal))

Decimal number

token*BlockchainAssetId (string)

Universal unique on-chain identifier of the asset following CAIP-19 specification

fees*array of Fee (object)

Fees for the transaction

chainTransactions*array of ChainTransaction (object)

On-chain transactions associated with this transaction

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/transactions/{transactionId}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT",
      "Signature": "text",
      "Signature-Input": "text"
    },
});
const data = await response.json();

Response

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "cardId": "123e4567-e89b-12d3-a456-426614174000",
  "authorisationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "processing",
  "direction": "debit",
  "amount": "text",
  "currency": "text",
  "merchantAmount": "text",
  "merchantCurrency": "text",
  "exchangeRate": "text",
  "merchant": {
    "id": "text",
    "name": "text",
    "mcc": 0,
    "country": "text",
    "city": "text"
  },
  "tokenAmount": "text",
  "token": "text",
  "fees": [
    {
      "type": "partner",
      "tokenAmount": "text"
    }
  ],
  "chainTransactions": [
    {
      "chainId": "text",
      "createdAt": "2024-12-21T11:56:58.157Z"
    }
  ],
  "createdAt": "2024-12-21T11:56:58.157Z",
  "updatedAt": "2024-12-21T11:56:58.157Z"
}

{
    "accountId": "ae61c362-4136-49af-8e01-544457fe265b",
    "amount": "20",
    "authorisationId": "532a52af-9f68-429b-8945-184773d0889d",
    "cardId": "fc4912aa-cac9-4bb0-a6a7-6ec50bf45879",
    "chainTransactions": [
        {
            "chainId": "eip155:280:0x0000000000000000000000000000000067517441607a481e825155eaaadcf7e9",
            "createdAt": "2024-01-12T15:22:30.14091932Z"
        }
    ],
    "createdAt": "2024-01-12T15:22:30.268311Z",
    "currency": "EUR",
    "direction": "debit",
    "exchangeRate": "1",
    "fees": [
        {
            "tokenAmount": "0.1",
            "type": "network"
        }
    ],
    "id": "532a52af-9f68-429b-8945-184773d0889d",
    "merchant": {
        "city": "London",
        "country": "GB",
        "id": "TEST",
        "mcc": 9999,
        "name": "Test Merchant"
    },
    "merchantAmount": "20",
    "merchantCurrency": "EUR",
    "status": "processed",
    "token": "eip155:280/erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F",
    "tokenAmount": "20.1",
    "updatedAt": "2024-01-12T15:22:30.479706Z"
}