API Introduction

The Bank Accounts API lets you read the accounts, balances and transactions of the banks you connected in the panel from your own server. If your connection supports it, the same API also sends money transfers from your connected account and exchanges currency between your accounts. Money movement endpoints need a separate permission and an IP allowlist; the read endpoints are not affected by them.

Endpoints

Base URL: https://api-gateway.lunixi.com/api/v1/bank-connect

There is no endpoint for connecting or disconnecting a bank; that is done only in the panel. → Connect a Bank in the Panel

Authentication

These endpoints require a request signed with your API key on every request. An Authorization: Bearer token or a panel session is not accepted as identity; a request without the signature headers gets 401 AUTH_HEADERS_MISSING.

The signed canonical string is the lines METHOD, full path, X-Date:… and X-Nonce:… joined with \n. Read endpoints have no body, so the Digest line is not written; signing money movement requests that carry a body: Money Transfers › Signing a request with a body. Canonical string rules and key management: Authentication › Canonical string.

The cURL examples in this section compute the signature with the shell function below (requires OpenSSL 3.0 or later):

# lunixi-sign.sh — Usage: source lunixi-sign.sh; lunixi_sign GET "/api/v1/bank-connect/accounts"
LUNIXI_KEY_ID="mk_test_..."
LUNIXI_KEY_FILE="lunixi-signing.key"
 
lunixi_sign() {
  local method="$1" req_path="$2"
  DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  NONCE=$(openssl rand -hex 16)
  printf '%s\n%s\nX-Date:%s\nX-Nonce:%s' "$method" "$req_path" "$DATE" "$NONCE" > canonical.txt
  SIGNATURE=$(openssl pkeyutl -sign -inkey "$LUNIXI_KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
}

PHP SDK

The PHP examples use the bankConnect() client of the PHP SDK (lunixi/php-sdk, 0.14.0 or later; 0.22.0 or later for transfers and currency exchange). The SDK signs every request for you:

use Lunixi\Sdk\LunixiClient;
 
$lunixi = LunixiClient::create([
    'baseUrl'     => 'https://api-gateway.lunixi.com',
    'keyId'       => getenv('LUNIXI_KEY_ID'),
    'privateKey'  => getenv('LUNIXI_PRIVATE_KEY_PEM'),
    'environment' => 'TEST', // your key's environment: TEST or LIVE
]);
 
$bankConnect = $lunixi->bankConnect();

• The list methods (listBanks, listConnections, listAccounts, listBalances, listTransactions) return a single page: items(), hasMore(), nextCursor(). The matching iterate… methods walk all pages for you.
• The SDK rejects unknown filters, values outside their set and date or amount ranges that break the rules with Lunixi\Sdk\Exception\ConfigurationException, before sending the request.
• API errors arrive as Lunixi\Sdk\Exception\ApiException; branch on getStatusCode() and getErrorCode().

Permissions

After the signature is verified, two things are checked:

1. Product. Your key must carry the Bank Connections product (BANK_CONNECT); otherwise 403 PRODUCT_NOT_ENABLED. → Error Handling › PRODUCT_NOT_ENABLED
2. Permission. Your key must carry the endpoint's permission; otherwise 403 API_INSUFFICIENT_SCOPE.

IP allowlist

Money movement endpoints (bank-connect:transfer) have no verification code; the approval is the key's permission, the request signature and the IP address the request comes from. Therefore:

1. When you create or update a key: the bank-connect:transfer permission can only be given to a key with an IP allowlist. Adding it while the list is empty is refused with 400 organization.api_key.scope_requires_ip_allowlist.
2. On every request: the request's IP address must be on the key's list. A key with an empty list gets 403 bank_connect.auth.ip_allowlist_required; an address not on the list gets 403 bank_connect.auth.ip_not_allowed. If the list cannot be verified for a moment, the request gets 503 bank_connect.auth.ip_allowlist_unavailable; retry the same request.

The list takes single IP addresses (IPv4 or IPv6); address ranges (CIDR) are not accepted, and up to 50 addresses can be added. Changes to the list take effect within 15 seconds. Read endpoints (bank-connect:view, bank-connect:transactions:view) are not subject to this rule.

Environment

Your key's environment (test or live) determines the environment. A test key sees only connections and data in the test environment, a live key only those in the live environment. You do not send environment in the query; if you do, the request gets 400 VALIDATION_ERROR. A record of another organization or of the other environment returns 404.

Response envelope

On success, the data is under data. For endpoints that return a single record, data is the record itself. For list endpoints, records are in data.items and the pagination info pageInfo sits next to data:

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "items": [ ]
  },
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Envelope fields omitted from the examples for brevity (message, timestamp …) are also present in the response; for the full field list and the error envelope see Error Handling. On errors, branch on code, not on message. This product's codes: Error Codes.

Common field rules

Pagination

List endpoints use cursor-based pagination:

• If pageInfo.hasMore is true, request the next page with cursor=<nextCursor>.
• On these endpoints pageInfo.totalCount is always null; even with includeTotal=true no total is returned. hasMore is enough to move forward.
• Do not build or alter cursors. A malformed cursor returns 400 bank_connect.cursor.invalid; start again from the first page.
• Reset the cursor when you change filters; a cursor from one set of filters is not used with other filters.

Next steps

• Banks you can connect: Banks
• Your accounts and freshness: Accounts
• Reading transactions and keeping in sync: Transactions
• Sending money: Money Transfers
• Buying and selling currency between your accounts: Currency Exchange