Bank Account Inquiry

The Bank Account Inquiry API verifies a beneficiary bank account before you send a disbursement. It returns the account holder name and a status indicating whether the account is valid and fundable, so you can prevent failed transfers caused by inactive, closed, or incorrect accounts.

In the current implementation the API is synchronous in the vast majority of cases, the inquiry is performed against the destination bank within the same HTTP request, and the response carries a final status (SUCCESS, INVALID_ACCOUNT_NUMBER, FAILED, etc.). The legacy PENDING status is reserved for a narrow cache-related edge case described in the status reference below.

This page is the full integration guide. For the raw OpenAPI schema, see the API Reference.

When to call it

Call the inquiry before creating a disbursement whenever you have not previously verified the beneficiary account. Recommended placement in your flow:

1. User submits or selects a beneficiary account.
2. Your backend calls our Bank Account Inquiry API and receives a final status in the same response.
3. If the response is SUCCESS, proceed to Create Disbursement. For INVALID_ACCOUNT_NUMBER, CLOSED, BLACK_LISTED, or SUSPECTED_ACCOUNT, surface the error to the user without sending funds. For FAILED, retry with backoff (see Best practices).

Cache successful inquiry results on your side so you do not repeatedly inquire the same account, this is also what protects you from hitting the rate limits described below.

Endpoint

Environment	Method	URL
Sandbox	POST	https://bigflip.id/big_sandbox_api/v2/disbursement/bank-account-inquiry
Production	POST	https://bigflip.id/api/v2/disbursement/bank-account-inquiry

Content type: application/x-www-form-urlencoded.

Authentication

Send your API Secret Key in the Authorization header using HTTP Basic auth:

Authorization: Basic <Base64(Your-API-SecretKey + ":")>

If signature verification is enabled for your company, also include the X-Signature header. See Retrieving API Access Keys and Generate Signature for details.

Request fields

Field	Required	Description
account_number	Yes	The beneficiary bank account number. Must contain numeric characters only, non-numeric values are rejected at the API edge with HTTP 422.
bank_code	Yes	The destination bank code. Accepted values are listed in Destination Bank Code.
inquiry_key	No	Client-supplied unique identifier for the inquiry. Allowed characters: A-Z, a-z, 0-9, and -. Used to (a) match async callbacks back to your request and (b) look up a previously-cached result on subsequent calls.

Sample request

curl -X POST 'https://bigflip.id/big_sandbox_api/v2/disbursement/bank-account-inquiry' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json; charset=UTF-8' \
  -H 'Authorization: Basic <Base64(Your-API-SecretKey + ":")>' \
  -d 'account_number=5465327020' \
  -d 'bank_code=bca' \
  -d 'inquiry_key=your-unique-id-12344'

Response fields

Field	Type	Description
account_number	string	The account number you inquired about. Echoed from the request.
account_holder	string	The account holder name returned by the destination bank. Empty for PENDING and error statuses.
bank_code	string	The destination bank code (lowercased).
status	string	The inquiry outcome. See the status reference below.
inquiry_key	string	Echoed from the request. Empty string if you did not send one.
is_virtual_account	boolean	true if the destination is a virtual account; false for regular bank accounts.
amount	string	Bill amount (as a string) for closed-amount virtual accounts. Returned only when the upstream bank provider includes the value in its response, so this field can still be null even for a closed-amount virtual account if the provider did not return it. null for all other cases.

Sample response

SUCCESS

Cache hit, or a fresh upstream inquiry that returned a valid fundable account. You can proceed with disbursement.

{
  "bank_code": "bca",
  "account_number": "5465327020",
  "account_holder": "PT Fliptech Lentera IP",
  "status": "SUCCESS",
  "inquiry_key": "your-unique-id-12344",
  "is_virtual_account": false,
  "amount": null
}

INVALID_ACCOUNT_NUMBER

The destination bank rejected the account number. Do not retry — repeated invalid inquiries can cause your inquiry traffic to be temporarily blocked. See Rate limits.

{
  "bank_code": "bca",
  "account_number": "0000000000",
  "account_holder": "",
  "status": "INVALID_ACCOUNT_NUMBER",
  "inquiry_key": "your-unique-id-12344",
  "is_virtual_account": false,
  "amount": null
}

FAILED

The inquiry could not be completed because the upstream bank was unreachable or returned an unrecoverable error. Retry with backoff (see Best practices).

{
  "bank_code": "bca",
  "account_number": "5465327020",
  "account_holder": "",
  "status": "FAILED",
  "inquiry_key": "your-unique-id-12344",
  "is_virtual_account": false,
  "amount": null
}

Status reference

Status	Meaning	Recommended action
SUCCESS	Account verified and fundable.	Proceed with disbursement.
INVALID_ACCOUNT_NUMBER	Destination bank rejected the account number, or the account exists but is not fundable for non-e-wallet rails.	Surface the error to your user. Do not retry the same account.
TOP_UP_LIMIT_EXCEEDED	E-wallet account exists but has reached its top-up limit and cannot receive funds at this time.	Ask the user to choose a different account or retry later.
BLACK_LISTED	Account is flagged on Flip's blocklist.	Do not disburse. Contact Our support if you believe this is incorrect.
CLOSED	Bank reports the account as closed.	Ask the user for a different account.
SUSPECTED_ACCOUNT	Account is suspected of fraud or other risk.	Do not disburse. Escalate to your risk team.
FAILED	Inquiry could not be completed upstream bank unreachable, timeout, or other unrecoverable error.	Retry with backoff (see Best practices). If the error persists, check the Disbursement FAQ.
PENDING	Rare in the current implementation. The inquiry endpoint runs synchronously and normally returns a final status in the same response. PENDING is only returned when the request matches a cached record that was previously written in a "still verifying" state by an earlier async flow.	Treat the same way you would treat a FAILED do not disburse on PENDING. Wait for the legacy callback (see Handling Bank Account Inquiry Callback) or re-inquire after a short delay. If you consistently see PENDING for new inquiries, contact support.

How it works internally

The diagram below describes the request lifecycle from edge validation through to response. Use it as a mental model when interpreting status codes and rate-limit behavior.

Flow Diagram

A few non-obvious points to highlight:

• The flow is synchronous. The destination bank is queried in the same HTTP request, and the response carries a final status. There is no asynchronous "wait for callback" path in normal operation, the status PENDING is only returned in the narrow legacy-cache case described in the status reference.
• Cache lookups happen twice. First in the "only inquiry_key" shortcut (no other fields needed), and again after the rate-limit gate when both bank_code and inquiry_key are present. This is why sending an inquiry_key on retries can return instantly without consuming the upstream bank call.

Rate limits

The inquiry endpoint enforces rate limits per company to ensure fair capacity across all Flip for Business merchants and to protect upstream banks.

Response when rate-limited

When a request is rate-limited, you receive HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 120
Content-Type: application/json

{
  "code": 429,
  "message": "Too many invalid inquiries. Please try again in 120 seconds."
}

tip

If your integration consistently requires more capacity, contact your sales support representative with your company ID, expected QPS, and business justification.

Handling guidance

• Always respect Retry-After. Retrying earlier than indicated will not unblock you and may extend the cool-down.
• Never retry a non-SUCCESS response automatically. INVALID_ACCOUNT_NUMBER, CLOSED, and similar non-success statuses should be surfaced to the user/merchants so they can correct the input and confirm the account.
• Validate account_number is numeric on the client side before sending. Non-numeric values are rejected at the edge with 422, but they still indicate buggy input that you should catch earlier.
• Cache verified results on your side. A SUCCESS for a given bank_code + account_number pair will not change in the short term, so re-inquiring wastes quota.

Best practices

• Implement the inquiry before every disbursement to a new beneficiary; cache the result for repeat transfers.
• Build retry-with-backoff for FAILED only, bounded retries, exponential backoff, and always honoring Retry-After.
• Optionally configure your callback URL in the Flip for Business Dashboard so that, if a PENDING response is ever returned for a cached legacy record, the final status can still be delivered asynchronously. See Configure your callback URL. In the current sync-only flow this is not required for normal operation.

Related

• API Reference: Bank Account Inquiry
• Destination Bank Code
• List Dummy Account (sandbox testing)
• Handling Bank Account Inquiry Callback
• Disbursement FAQ