🔃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

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",
    "country": "text",
    "city": "text"
  },
  "createdAt": "2024-11-21T06:48:33.460Z",
  "updatedAt": "2024-11-21T06:48:33.460Z"
}

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

Retrieves account's transactions

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

Authorization

bearerAuth

Path parameters

accountId*AuthorisationId (string (uuid))

ID of the account

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*AuthorisationId (string (uuid))

accountId*AuthorisationId (string (uuid))

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/accounts/{accountId}/transactions', {
    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",
    "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",
      "country": "text",
      "city": "text"
    },
    "tokenAmount": "text",
    "token": "text",
    "fees": [
      {
        "type": "partner",
        "tokenAmount": "text"
      }
    ],
    "chainTransactions": [
      {
        "chainId": "text",
        "createdAt": "2024-11-21T06:48:33.460Z"
      }
    ],
    "createdAt": "2024-11-21T06:48:33.460Z",
    "updatedAt": "2024-11-21T06:48:33.460Z"
  }
]

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

Retrieve card transactions

Retrieves card's transactions

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

Authorization

bearerAuth

Path parameters

cardId*AuthorisationId (string (uuid))

ID of the card

Header parameters

Response

200400401404500

Successful operation

Body

application/json

id*AuthorisationId (string (uuid))

accountId*AuthorisationId (string (uuid))

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/cards/{cardId}/transactions', {
    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",
    "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",
      "country": "text",
      "city": "text"
    },
    "tokenAmount": "text",
    "token": "text",
    "fees": [
      {
        "type": "partner",
        "tokenAmount": "text"
      }
    ],
    "chainTransactions": [
      {
        "chainId": "text",
        "createdAt": "2024-11-21T06:48:33.460Z"
      }
    ],
    "createdAt": "2024-11-21T06:48:33.460Z",
    "updatedAt": "2024-11-21T06:48:33.460Z"
  }
]

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

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*AuthorisationId (string (uuid))

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",
  "accountId": "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",
    "country": "text",
    "city": "text"
  },
  "tokenAmount": "text",
  "token": "text",
  "fees": [
    {
      "type": "partner",
      "tokenAmount": "text"
    }
  ],
  "chainTransactions": [
    {
      "chainId": "text",
      "createdAt": "2024-11-21T06:48:33.460Z"
    }
  ],
  "createdAt": "2024-11-21T06:48:33.460Z",
  "updatedAt": "2024-11-21T06:48:33.460Z"
}