Build with a clear contract.

A practical guide to understanding BankU APIs, preparing your integration and handling every response with confidence.

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

The public API reference uses the same product catalogue and gateway operations as ERP → Developers API. It publishes every BankU request schema in the current Cashfree Secure ID mapping and links each operation to its official Cashfree contract.

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 Cashfree product entitlement are separate requirements.

Send X-Client-Id, X-Client-Secret and Idempotency-Key on every request, including GET. 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. The key must contain 16–80 characters: letters, numbers, dots, underscores or hyphens, starting with a letter or number. 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 gateway returns success and transaction_id, with data on success or error.code and error.message on failure. 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.

Limits: 60 authenticated requests per organisation per minute, 120 requests per source IP per minute, JSON bodies up to 2 MiB, multipart bodies up to 6 MiB and responses up to 2 MiB. A repeated key returns HTTP 409 with the original transaction and never calls the provider twice. Response bodies are not retained for replay. Reconcile timeouts and “Indeterminate” or “In progress” transactions in Statement before using a new key; do not assume an error means no provider charge.

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, Cashfree product entitlement or production access.

API tools

Use published OpenAPI and Postman exports to inspect the contract in your preferred tooling. Exports include all 58 BankU operations, their request schemas and examples, plus connection check. Bank Directory is explicitly outside Cashfree; the other operations identify their Cashfree provider method, path and official contract.

Understand the response

Read the response field table and examples for each endpoint. Every provider result uses the shared BankU success envelope, while the data object retains its operation-specific Cashfree status and fields.

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.