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

post

/simulator/cards/{cardId}/authorisation

Simulates card authorisation

Authorizations

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)

Content-DigeststringRequired

Content digest

Body

amountstring · decimalRequired

Amount to be authorised

Example: 10.0

currencystringRequired

Authorisation currency (ISO-4217)

Example: EUR

capturebooleanRequired

Whether to capture the authorisation immediately

Default: true

Responses

201

Successful operation

application/json

idstring · uuidRequired

Unique authorisation ID

accountIdstring · uuidRequired

Unique account ID

cardIdstring · uuidOptional

Unique card ID

statusstring · enumRequired

Authorisation status

Possible values:

amountstring · decimalRequired

Total authorised amount expressed as a decimal number

Example: 10.0

currencystringRequired

Currency of the account (ISO-4217)

Example: EUR

merchantAmountstring · decimalRequired

Total authorised amount in origin (merchant) currency expressed as a decimal number

Example: 10.0

merchantCurrencystringRequired

Origin currency of the merchant (ISO-4217)

Example: EUR

exchangeRatestring · decimalRequired

Exchange rate for authorisation if merchant currency is different to account currency expressed as a decimal number. If merchant currency is the same as account currency, exchange rate is 1.0

Example: 10.0

createdAtstring · date-timeRequired

Date this authorisation was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this authorisation was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Card not found

500

Internal error

post/simulator/cards/{cardId}/authorisation

POST /v1/simulator/cards/{cardId}/authorisation 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: 49

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "cardId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "amount": "10.0",
  "currency": "EUR",
  "merchantAmount": "10.0",
  "merchantCurrency": "EUR",
  "exchangeRate": "10.0",
  "merchant": {
    "id": "text",
    "name": "text",
    "mcc": 1,
    "country": "text",
    "city": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

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

get

/authorisations/{authorisationId}

Retrieves authorisation's details

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

authorisationIdstring · uuidRequired

Unique authorisation ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique authorisation ID

accountIdstring · uuidRequired

Unique account ID

cardIdstring · uuidOptional

Unique card ID

statusstring · enumRequired

Authorisation status

Possible values:

amountstring · decimalRequired

Total authorised amount expressed as a decimal number

Example: 10.0

currencystringRequired

Currency of the account (ISO-4217)

Example: EUR

merchantAmountstring · decimalRequired

Total authorised amount in origin (merchant) currency expressed as a decimal number

Example: 10.0

merchantCurrencystringRequired

Origin currency of the merchant (ISO-4217)

Example: EUR

exchangeRatestring · decimalRequired

Exchange rate for authorisation if merchant currency is different to account currency expressed as a decimal number. If merchant currency is the same as account currency, exchange rate is 1.0

Example: 10.0

createdAtstring · date-timeRequired

Date this authorisation was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this authorisation was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Authorisation not found

500

Internal error

get/authorisations/{authorisationId}

GET /v1/authorisations/{authorisationId} 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",
  "cardId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "amount": "10.0",
  "currency": "EUR",
  "merchantAmount": "10.0",
  "merchantCurrency": "EUR",
  "exchangeRate": "10.0",
  "merchant": {
    "id": "text",
    "name": "text",
    "mcc": 1,
    "country": "text",
    "city": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

{
    "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

get

/transactions/{transactionId}

Retrieves transaction's details

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

transactionIdstring · uuidRequired

Unique transaction ID

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Responses

200

Successful operation

application/json

idstring · uuidRequired

Unique transaction ID

accountIdstring · uuidRequired

Unique account ID

cardIdstring · uuidOptional

Unique card ID

authorisationIdstring · uuidOptional

Unique authorisation ID

statusstring · enumRequired

Transaction status

Possible values:

directionstring · enumRequired

Direction of the transaction

Possible values:

amountstring · decimalRequired

Transaction amount expressed as a decimal number

Example: 10.0

currencystringRequired

Currency of the transaction (ISO-4217)

Example: EUR

merchantAmountstring · decimalRequired

Total authorised amount in origin (merchant) currency expressed as a decimal number

Example: 10.0

merchantCurrencystringRequired

Origin currency of the merchant (ISO-4217)

Example: EUR

exchangeRatestring · decimalRequired

Exchange rate for authorisation if merchant currency is different to account currency expressed as a decimal number. If merchant currency is the same as account currency, exchange rate is 1.0

Example: 10.0

tokenAmountstring · decimalRequired

Token amount expressed as a decimal number

Example: 10.0

tokenstringRequired

Token contract address

Example: eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f

createdAtstring · date-timeRequired

Date this transaction was created (ISO-8601)

updatedAtstring · date-timeRequired

Date this transaction was updated (ISO-8601)

400

Invalid request

401

Not authorised

404

Transaction not found

500

Internal error

get/transactions/{transactionId}

GET /v1/transactions/{transactionId} 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",
  "cardId": "123e4567-e89b-12d3-a456-426614174000",
  "authorisationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "processing",
  "direction": "debit",
  "amount": "10.0",
  "currency": "EUR",
  "merchantAmount": "10.0",
  "merchantCurrency": "EUR",
  "exchangeRate": "10.0",
  "merchant": {
    "id": "text",
    "name": "text",
    "mcc": 1,
    "country": "text",
    "city": "text"
  },
  "tokenAmount": "10.0",
  "token": "eip155:1/erc20:0x6b175474e89094c44da98b954eedeac495271d0f",
  "fees": [
    {
      "type": "partner",
      "tokenAmount": "10.0"
    }
  ],
  "chainTransactions": [
    {
      "chainId": "eip155:1:0xa3847d82245abb63692bded9da859af0b73b1bfd2409502291c39795eb14954f",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

{
    "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"
}