Account Balance

GET

/api/v2/accounts/{accountId}/balance

Code sample: Shell / cURL

curl --request GET \
  --url https://api.ztlpay.io/api/v2/accounts/example/balance \
  --header 'Authorization: Bearer <token>' \
  --header 'PSU-IP-Address: 192.158.1.38' \
  --header 'PSU-User-Agent: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0' \
  --header 'consent-id: 3a797348-ef0c-4f52-b821-fdfcdb98c4d9'

• Production environment
• Sandbox environment for testing

Retrieve the current available and booked balance for the account specified.

Authorizations

• OAuth2Sandbox
  api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default
• OAuth2Production
  api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default

Parameters

Path Parameters

accountId

required

string

The ID of the account, as retrieved from the list of accounts. The account ID is sometimes the same as the account bban, but this is not always the case. Also, the account ID may change each time a consent is created/refreshed.

Header Parameters

consent-id

required

string format: uuid

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

A valid consentId

PSU-IP-Address

string

Example

192.158.1.38

AAA IP Address of the end-user initiating the payment. DO NOT use any other IP address than what you can collect from the current user session that uses your system (don’t use something stored in your DB). This information is used by the banks to manage traffic and handle security.

PSU-User-Agent

string

The forwarded Agent header field of the HTTP request between PSU and TPP.

Example

Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0

Responses

200

Successfully retrieved balance

Media typeapplication/json

object

id

Unique Identifier for Account

string

balance

object

booked

object

amount

The booked balance on the account

number

currency

The currency of the booked balance

string

available

object

amount

The available balance on the account

number

currency

The currency of the available balance

string

Example

{
  "id": "11ab5740-f8f5-1234-abcd-b90e4253b7b8",
  "balance": {
    "booked": {
      "amount": 150.51,
      "currency": "NOK"
    },
    "available": {
      "amount": 100.42,
      "currency": "NOK"
    }
  }
}

400

Bad Request

Media typeapplication/json

object

failure

• INVALID_CONSENT Consent is invalid
• INVALID_ACCOUNT Account is either missing or invalid
• ACCESS_DENIED PSU is not allowed to access resource

string

Allowed values: INVALID_CONSENT INVALID_ACCOUNT ACCESS_DENIED

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "failure": "INVALID_CONSENT",
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

403

Forbidden

Media typeapplication/json

object

failure

• INACTIVE_SUBSCRIPTION The company does not have an active subscription to ZTL’s services

string

Allowed values: INACTIVE_SUBSCRIPTION

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "failure": "INACTIVE_SUBSCRIPTION",
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

404

Not found

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

409

Conflict

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

500

Internal server error

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

503

Service unavailable

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9