Use the Check Balance API to verify whether a bank client has enough funds on their account, typically before an attempt to initiate a payment transaction on their behalf.

There are two versions of the service:

• One requires the bank client to give you permissions to perform the operation via the OAuth flow with the consent page.
• The other one’s flow does not involve the bank client granting you the permission interactively. Instead, you need to obtain the permission to call the service from ČSOB in advance, e.g. the client gives you the right via internet banking.

Both services have the same behavior and request and response structures. The only difference is the OAuth access token requirement.

Check account balance with client giving consent

POST /api/csob/psd2/v1/my/payments/balanceCheck

This operation requires you possess the PSD2 PISP scope.

Request security requirements

Check account balance with pre-granted permission

POST /api/csob/psd2/v1/accounts/balanceCheck

This operation requires you possess the PSD2 CISP scope.

Request security requirements

Supported features

Operation-specific errors

Please refer to the Overview section for the error response data structure and a list of errors common to all operations.

Request schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "exchangeIdentification": {
      "description": "Unique identification of the request; maximum 18 digits",
      "type": "integer"
    },
    "card": {
      "description": "Transaction card",
      "type": "object",
      "properties": {
        "cardholderName": {
          "description": "Name of the card holder",
          "type": "string",
          "maxLength": 45
        },
        "maskedPan": {
          "description": "Masked number of the card",
          "type": "string",
          "maxLength": 30
        }
      },
      "required": [
        "maskedPan"
      ]
    },
    "debtorAccount": {
      "type": "object",
      "properties": {
        "identification": {
          "type": "object",
          "properties": {
            "iban": {
              "description": "Debtor's account IBAN",
              "type": "string",
              "minLength": 1,
              "maxLength": 30,
              "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$"
            }
          },
          "required": [
            "iban"
          ]
        },
        "currency": {
          "type": "string",
          "maxLength": 3,
          "pattern": "^[A-Z]{3}$"
        }
      },
      "required": [
        "identification"
      ]
    },
    "authenticationMethod": {
      "description": "Code of the authentication method of the bank client",
      "type": "string",
      "minLength": 4,
      "maxLength": 4
    },
    "merchant": {
      "description": "Merchant performing the transaction",
      "type": "object",
      "properties": {
        "identification": {
          "description": "Identification of the merchant, e.g. 'IČO' within the Czech Republic",
          "type": "string",
          "maxLength": 35
        },
        "type": {
          "description": "Code of the merchant type; OPOI: Point Of Interaction initiating the card payment transaction, MERC: Merchant providing goods and service in the card payment transaction, ACCP: Card acceptor, party accepting the card and presenting transaction data to the acquirer, ITAG: Party acting on behalf of other parties to process or forward data to other parties, ACQR: Entity acquiring card transactions, CISS: Party that issues cards, DLIS: Party to whom the card issuer delegates to authorise card payment transactions",
          "type": "string",
          "minLength": 4,
          "maxLength": 4
        },
        "shortName": {
          "type": "string",
          "maxLength": 35
        },
        "commonName": {
          "description": "Merchant name as stated in the payment confirmation",
          "type": "string",
          "maxLength": 70
        },
        "address": {
          "type": "string",
          "maxLength": 140
        },
        "countryCode": {
          "description": "Two-letter country code according to ISO 3166",
          "type": "string",
          "maxLength": 2,
          "pattern": "^[A-Z]{2}$"
        },
        "merchantCategoryCode": {
          "description": "Merchant category code according to ISO 18245",
          "type": "string",
          "minLength": 3,
          "maxLength": 4
        }
      },
      "required": [
        "identification",
        "shortName",
        "commonName",
        "merchantCategoryCode"
      ]
    },
    "transactionDetails": {
      "description": "The requested amount and currency",
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "maxLength": 3,
          "pattern": "^[A-Z]{3}$"
        },
        "totalAmount": {
          "type": "number",
          "minimum": 0,
          "maximum": 9999999999999.99,
          "multipleOf": 0.01
        }
      },
      "required": [
        "currency",
        "totalAmount"
      ]
    }
  },
  "required": [
    "exchangeIdentification",
    "debtorAccount",
    "transactionDetails"
  ]
}

Sample request

HTTP

POST /api/csob/psd2/v1/my/payments/balanceCheck HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Authorization: Bearer 3/1rLE5Q2Sw58nd2awsbz8K9wcM9FEd6ZyiSuRUSdg78yfZp6RczaZ3CmtxCkI6TaS
Cache-Control: no-cache

{
  "exchangeIdentification": 123456,
  "card": {
    "cardHolderName": "Jan Novák",
    "maskedPan": "1234***********6789"
  },
  "debtorAccount": {
    "identification": {
      "iban": "CZ9103000000001019382023"
    },
    "currency": "CZK"
  },
  "authenticationMethod": "NPIN",
  "merchant": {
    "identification": "471 16 129",
    "shortName": "NEOLUXOR",
    "commonName": "Neoluxor s.r.o.",
    "address": "Hlavní 5, Praha 1",
    "countryCode": "CZ",
    "merchantCategoryCode": "5192"
  },
  "transactionDetails": {
    "currency": "CZK",
    "totalAmount": 54444410050.12
  }
}

cURL

curl -X POST \
  https://api.csob.cz/api/csob/psd2/v1/my/payments/balanceCheck \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Authorization: Bearer 3/1rLE5Q2Sw58nd2awsbz8K9wcM9FEd6ZyiSuRUSdg78yfZp6RczaZ3CmtxCkI6TaS' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "exchangeIdentification": 123456,
  "card": {
    "cardHolderName": "Jan Novák",
    "maskedPan": "1234***********6789"
  },
  "debtorAccount": {
    "identification": {
      "iban": "CZ9103000000001019382023"
    },
    "currency": "CZK"
  },
  "authenticationMethod": "NPIN",
  "merchant": {
    "identification": "471 16 129",
    "shortName": "NEOLUXOR",
    "commonName": "Neoluxor s.r.o.",
    "address": "Hlavní 5, Praha 1",
    "countryCode": "CZ",
    "merchantCategoryCode": "5192"
  },
  "transactionDetails": {
    "currency": "CZK",
    "totalAmount": 54444410050.12
  }
}'

Response schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "responseIdentification": {
      "type": "integer"
    },
    "exchangeIdentification": {
      "type": "integer"
    },
    "response": {
      "description": "Result of the check: APPR means that the client has the asked amount, DECL means the client has not enough funds",
      "type": "string",
      "maxLength": 4,
      "pattern": "(APPR|DECL)"
    }
  },
  "required": [
    "responseIdentification",
    "exchangeIdentification",
    "response"
  ]
}

Sample response

HTTP/1.1 200 OK

{
  "responseIdentification": 98765,
  "exchangeIdentification": 123456,
  "response": "APPR"
}