🔃Transactions

Authorisation

Before a debit (payment) transaction is created, we usually receive an authorisation request from a payment network. We then either approve or reject the request based on various parameters, including customer and account statuses, on-chain balances etc. If authorisation is approved and authorised funds are claimed by the merchant, we proceed with creating a transaction entity.

Retrieving a Specific Authorisation

For the time being we only support retrieving an individual authorisation entity, however we will be expanding our API soon to support more endpoints.

To retrieve an individual authorisation, make a GET request to /authorisations/{authorisationId}.

Retrieve authorisation details

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/authorisations/{authorisationId}

Retrieves authorisation's details

Authorizations

bearerAuth

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}

HTTPcURLJavaScriptPython

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-03-27T18:11:37.357Z",
  "updatedAt": "2026-03-27T18:11:37.357Z"
}

Authorisation Entity Updates

Any internal updates to the authorisation entity will be reported through webhook update events. For details on how to set up and manage webhook subscriptions, please refer to Webhooks.

Transaction

Retrieving Transactions for a Specific Account or Card

To obtain a comprehensive list of transactions for a specific account or card, initiate a GET request to the corresponding endpoint:

• /accounts/{accountId}/transactions for account transactions

Retrieve account transactions

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/accounts/{accountId}/transactions

Retrieves account's transactions

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

accountIdstring · uuidRequired

Unique account 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

Account not found

500

Internal error

get

/accounts/{accountId}/transactions

HTTPcURLJavaScriptPython

GET /v1/accounts/{accountId}/transactions 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-03-27T18:11:37.357Z"
      }
    ],
    "createdAt": "2026-03-27T18:11:37.357Z",
    "updatedAt": "2026-03-27T18:11:37.357Z"
  }
]

• /cards/{cardId}/transactions for card transactions

Retrieve card transactions

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/cards/{cardId}/transactions

Retrieves card's transactions

Authorizations

bearerAuth

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

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

Card not found

500

Internal error

get

/cards/{cardId}/transactions

HTTPcURLJavaScriptPython

GET /v1/cards/{cardId}/transactions 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-03-27T18:11:37.357Z"
      }
    ],
    "createdAt": "2026-03-27T18:11:37.357Z",
    "updatedAt": "2026-03-27T18:11:37.357Z"
  }
]

Transaction Entity Updates

Any internal updates to the transaction entity will be reported through webhook update events. For details on how to set up and manage webhook subscriptions, please refer to Webhooks.

Retrieving a Specific Transaction

To retrieve detailed information about a specific transaction, make a GET request to /transactions/{transactionId}.

Retrieve transaction details

get

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/transactions/{transactionId}

Retrieves transaction's details

Authorizations

bearerAuth

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}

HTTPcURLJavaScriptPython

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-03-27T18:11:37.357Z"
    }
  ],
  "createdAt": "2026-03-27T18:11:37.357Z",
  "updatedAt": "2026-03-27T18:11:37.357Z"
}