Download the PHP package codetay/bankapi-php without Composer

codetay/bankapi-php

Official PHP SDK for BankAPI.VN — bank account connections, transaction listing/matching, payment intents, and webhook signature verification.

Framework-agnostic. If you're on Laravel, use codetay/bankapi-laravel instead (service provider, facade, webhook middleware) — see its README.

Install

The SDK talks HTTP through PSR-18 and auto-discovers an installed client via php-http/discovery. If your project doesn't already depend on a PSR-18 client, add one:

You can also pass a specific PSR-18 client, request factory, and stream factory explicitly to BankApi::__construct() instead of relying on discovery.

Configure the client you pass in. A discovered client runs with its own defaults, and Guzzle's default is no timeout at all — one hung API call then occupies a PHP-FPM worker until the socket closes. Two settings are worth making explicit in any client you hand to the SDK:

The Laravel package ships a client configured this way out of the box.

The base URL must be https (plain http is accepted only for loopback hosts during local development); anything else is refused with an InvalidArgumentException rather than sending your API key in clear text. Pass your API origin only (e.g. https://acme.bankapi.vn) — the SDK appends /v1 itself (the public HttpTransport::API_VERSION_PATH constant), so a baseUrl that already ends in /v1 is rejected instead of doubling the path.

Quickstart

BankApi::__construct(string $apiKey, string $baseUrl = 'https://api.bankapi.vn', ...) authenticates every request with an X-API-Key: <apiKey> header.

Base URL is your organization host. Org-scoped operations (banking, webhook endpoints) must be called on your organization's own host — https://<your-org-slug>.bankapi.vn — not the account-level API host. Calling them on a non-organization host fails with 403 "this operation must be accessed on an organization host". Pass your org host as $baseUrl:

Pagination

List methods (banking()->transactions(), banking()->paymentIntents(), webhookEndpoints()->all(), webhookEndpoints()->deliveries()) return a BankApi\Page, a cursor-paginated single page:

Payment intents

createPaymentIntent and webhookEndpoints()->create() are idempotent: pass your own idempotencyKey to control retries explicitly, or omit it and the SDK generates one with bin2hex(random_bytes(16)). A retry with the same key and the same request body replays the first response instead of creating a second intent. ApiException::$replayed is true only when the replayed response was itself an error; a successful replay returns the same intent (same id), which is all a caller needs.

ApiException::errorCode() is the registry error code (problem.type with the urn:bankapi:error: prefix stripped), typed ?string since a server can roll out a new code before this SDK is regenerated. Compare it against BankApi\ErrorCode constants, or use ErrorCode::isKnown() to check whether it's one this SDK knows about:

Webhook verification

BankAPI signs webhooks on Standard Webhooks. Verify every delivery before trusting its payload, then respond 2xx quickly (BankAPI retries on 408/429/5xx):

Webhook::constructEvent() verifies that any v1,<base64> entry of the webhook-signature header equals base64(HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>")), alongside the webhook-id and webhook-timestamp (Unix seconds) headers. It also rejects deliveries whose timestamp is more than $tolerance seconds (default 300) from now in either direction, to guard against replay. Always pass the raw, unparsed request body — re-encoding JSON before verifying will break the signature check.

A signing secret can be rotated: webhook-signature may carry more than one v1,<base64> entry, and verification succeeds if any one matches.

An event type this SDK version does not know yet (the server added one after this SDK was generated) still parses — $event->isKnown() returns false instead of the call throwing. Check EventType::ALL / $event->isKnown() before branching on $event->type, and treat $event->data as an untyped array for anything unrecognized.

flow.output events carry the flow run's trigger event in $event->trigger (null for every other type).

The webhook secret (whsec_<base64>) is shown once, in the response of webhookEndpoints()->create(...) — store it immediately, it cannot be retrieved again later. A secret minted before this SDK version may be URL-safe base64, padded or not — Webhook::decodeSecret() accepts both alphabets, so an old secret keeps verifying unchanged.

Errors

Every failure raises a subclass of BankApi\Exception\ApiException — HTTP errors are built from the API's problem+json body, transport failures are wrapped too:

All of them expose ->status, ->title, ->detail, and ->body (the decoded problem response). Catching ApiException catches every failure the SDK can raise during a request.

GET requests are retried automatically (up to 2 extra attempts) on network errors, 429, and 5xx responses, with backoff and jitter. Non-GET requests are never retried automatically, since they may not be idempotent.