Getting started with BankU

Work through access, authentication, request handling and testing before you send production traffic. The product reference contains the fields and requirements for each API.

Your integration path

1. Discover the product

   Choose an API from the published catalogue. Read its purpose, prerequisites and endpoint documentation.

2. Confirm access and environment

   Ask your authorised BankU contact for the approved environment and credential process. Do not infer an API base URL from the website address.

3. Implement the contract

   Match required headers, field types and response handling. Keep credentials on your server.

4. Validate before production

   Test successful, invalid, unauthorised and timeout outcomes. Agree operational monitoring and production approval.

Authentication

The product reference is the authority for header names, credential placement and required authentication. Workspace session cookies are not public API credentials.

• Store credentials on your server, outside source control.
• Never embed secrets in browser JavaScript or mobile application bundles.
• Use HTTPS and arrange credential rotation with the service owner.
• Redact secrets and personal data from logs and support messages.

ERP gateway integration

All reseller API documentation is published in this Developers portal. ERP → Developers API remains the secure place for activation, credentials, IP whitelisting, webhooks and statements. Read each operation's BankU contract here; private provider credentials and references are not reseller fields.

Credentials, network and activation

1. Create credentials in ERP → Developers API → Credentials and save the one-time Client Secret and Encryption Key securely.
2. Add your server's exact egress IPv4 or IPv6 address to the IP whitelist. An empty list denies all requests.
3. Send the connection check below using your approved API base URL. It checks credentials and source IP, records the transaction in Statement, and does not call a provider or activate a product.
4. Request product activation with your website and use case. BankU Control approval and BankU product entitlement are separate requirements.

Send X-Client-Id, X-Client-Secret and Idempotency-Key on product requests, including connection check and bank-directory GET. The short-lived report PDF instead uses its returned bearer URL; do not send API credentials or an idempotency header on that download. Your backend generates the idempotency key for each new logical request; it is not a credential, so never substitute the Client Secret or Encryption Key. Identity gateway and connection-check keys contain 16–80 letters, numbers, dots, underscores or hyphens, starting with a letter or number. Dedicated onboarding/AePS/DMT handlers accept 16–80 letters, numbers, dots, underscores, colons or hyphens; website/URL handlers accept 16–128 of those characters. Follow the selected endpoint. Do not send query strings. Secrets expire after 90 days; rotation invalidates the old Client Secret and Encryption Key.

Connection check

Set the base URL and credentials in your secure server environment. BANKU_API_BASE_URL is the approved workspace base URL shown in the product reference, not the public website URL. The sample generates an idempotency key locally; retain it only for an exact retry.

# Request identifier only. Never use the Client Secret or Encryption Key here.
# New operation: generate once. Exact retry: reuse this value.
BANKU_IDEMPOTENCY_KEY="${BANKU_IDEMPOTENCY_KEY:-$(printf '%04x%04x-%04x-%04x-%04x-%04x%04x%04x' $RANDOM $RANDOM $RANDOM $RANDOM $RANDOM $RANDOM $RANDOM $RANDOM)}"

curl --request GET "$BANKU_API_BASE_URL/api/reseller/v1/connection-check" \
  --header "X-Client-Id: $BANKU_CLIENT_ID" \
  --header "X-Client-Secret: $BANKU_CLIENT_SECRET" \
  --header "Idempotency-Key: $BANKU_IDEMPOTENCY_KEY"

Responses, limits and retries

The identity gateway and connection check return success and transaction_id, with data on success or error.code and error.message on failure. Dedicated handlers instead use requestId, checkedAt and their documented report/workflow fields. Read financial and onboarding outcomes from status and nextAction, not HTTP 2xx alone. A reserved transaction also has an X-BankU-Transaction-Id response header. Successful connection-check data contains credentials_valid, ip_whitelisted, source_ip and message; this is not a provider verification result.

Identity gateway limits are 60 authenticated requests per organisation/minute and 120 per source IP/minute, JSON up to 2 MiB, multipart up to 6 MiB and responses up to 2 MiB. Website/URL JSON is limited to 16 KiB; onboarding/AePS/DMT JSON to 128 KiB, with separate policies and durable quotas. Respect Retry-After. Identity operations reject repeated keys with HTTP 409; dedicated handlers can return protected retained results for an exact retry. Never change a retained logical body or silently re-dispatch an uncertain financial operation.

Signed webhooks

Register an HTTPS URL in ERP and obtain deployment approval for that exact destination. Delivery requires the configured worker. Verify X-BankU-Signature as sha256=HMAC-SHA256(encryption_key, timestamp + "." + raw_request_body) using the UTF-8 Encryption Key and a constant-time comparison. Reject timestamps older than five minutes, deduplicate X-BankU-Event-Id, and acknowledge with 2xx only after recording the event.

Delivery is at least once, with up to five delivery attempts. Events contain a transaction reference, status and safe code; they do not contain identity documents, API secrets or provider payloads. Credential or destination disablement cancels delivery.

Environments

Use only the BankU base URL and environment approved for your organisation. Documentation does not grant BankU activation, BankU product entitlement or production access.

API tools

Use published OpenAPI and Postman exports to inspect the contract in your preferred tooling. Exports cover 58 identity/verification operations, connection check and 33 additional reseller routes for Website Intelligence, its PDF, URL Verification, Outlet Onboarding, AePS and DMT. Including PDF HEAD, there are 92 paths and 93 HTTP method entries. Two mobile-change routes are reserved/unavailable; Credit Score Check remains setup-pending with no callable endpoint. Documentation never grants live access.

Understand the response

Read the response field table and examples for each endpoint. Envelopes differ by handler: identity APIs use their reviewed envelope; dedicated website, financial and onboarding APIs publish their own sanitised fields. Missing scores or balances are not zero, and pending/reconciliation-required states are not completed success.

Use the documented operation model. Polling, callbacks and retries should only be implemented where the published contract explicitly supports them. A timeout alone does not prove that an operation failed.

Handle errors deliberately

Check the HTTP status and documented error code. Validate requests before sending them and never retry a financial operation automatically without a documented idempotency strategy.

Get integration support

Include the product, endpoint, environment, timestamp and a redacted request identifier. Never include credentials, payment data or personal documents.