Copy page

Introduction

FAQ

Use this FAQ as a practical checklist when planning, building, testing, or troubleshooting a Brick integration. For product-specific request and response fields, always confirm the latest details in the relevant API reference page.

Getting Started

What should I read first before integrating with Brick?

Start with the business flow you want to support, then map it to the relevant Brick product:

Goal	Start here
Understand Brick products and capabilities	What is Brick?
Prepare dashboard access and account setup	Brick Dashboard Overview
Prepare API credentials and base URLs	Prepare Yourself to Use API
Understand authentication and environments	Authentication and Environment
Review security expectations	Security at Brick

Before writing production code, confirm which product you are integrating: disbursement, virtual account, QR Code, Ewallet, checkout page, bank account validation, or financial insight.

What must be completed before production access?

Production access requires a verified account, production credentials, and operational readiness.

At minimum, complete:

• KYB verification.
• Dashboard account setup.
• API key and secret provisioning for the correct environment.
• Callback URL configuration.
• Internal testing in Sandbox.
• Production readiness checks for retries, status handling, logging, and reconciliation.

References:

• Verify Your Account (KYB)
• Authentication and Environment
• Production Checklist

Can I use production APIs before KYB is approved?

No. Production access is enabled only after KYB approval and production credential provisioning. You can continue building and testing with Sandbox credentials while KYB is being processed.

What is the difference between Sandbox and Production?

Sandbox is for development and integration testing. It uses Sandbox credentials, Sandbox base URLs, and simulated or test transaction behavior.

Production processes real transactions and uses production credentials, production base URLs, and real settlement or bank network behavior.

Do not mix credentials across environments. A common cause of authentication failure is using production credentials against Sandbox URLs, or Sandbox credentials against production URLs.

Authentication And Tokens

Which token should I use?

Brick has more than one authentication flow. Use the token that matches the API family you are calling.

API family	Token or credential flow	Notes
General Brick APIs	Public Access Token from Generate Public Access Token	Short-lived token used for general API requests.
QR Code SNAP APIs	SNAP B2B access token from Get Access Token (SNAP)	QR Code SNAP-specific authentication flow.
Dashboard actions	Dashboard user access	Managed from the Brick dashboard, not the API token flow.

If you are integrating QR Code SNAP, do not treat the general public access token as the SNAP token. Start with the QR Code SNAP token flow.

Why am I getting 401 Unauthorized?

Common causes include:

• Credentials are for the wrong environment.
• API key, secret, client key, or signature is incorrect.
• The public access token has expired or was already used.
• The request is missing a required authorization header.
• The QR Code SNAP request is using the wrong timestamp or signature format.

Recommended checks:

1. Confirm the base URL.
2. Confirm the credential pair belongs to that environment.
3. Generate a fresh token.
4. Rebuild the request headers.
5. Compare the request with the relevant API reference.

References:

• Authentication and Environment
• Generate Public Access Token
• Get Access Token (SNAP)

Why does my token keep failing after a retry?

Some tokens are short-lived and intended for limited use. Generate a fresh token before retrying an API request, especially if the previous request failed after a delay or was retried by your client.

For production systems, make token generation part of a controlled request flow instead of caching tokens too aggressively.

How should I secure API credentials?

Use server-side storage only. Do not expose Brick credentials in mobile apps, frontend code, public repositories, logs, support screenshots, or analytics events.

Recommended practices:

• Store secrets in a secrets manager or encrypted environment configuration.
• Rotate credentials when access changes.
• Restrict who can view production credentials.
• Mask secrets in application logs.
• Separate Sandbox and Production credentials clearly.

Reference:

• Security at Brick

API Behavior

Does a successful API response mean the transaction is complete?

Not always. For asynchronous payment and disbursement flows, an API response often means Brick accepted the request for processing. The final state may arrive later through a callback or may need to be confirmed through a status endpoint.

Build your system around final transaction status, not only the first API response.

Should I rely on callbacks or status APIs?

Use both, with clear responsibilities:

Mechanism	Best used for
Callback	Primary event notification when status changes.
Status API	Manual check, reconciliation, fallback when a callback is delayed, or support investigation.

Your system should be idempotent. If the same status is received more than once, it should not double-credit, double-debit, or duplicate user notifications.

References:

• Error Handling
• Regular Disbursement Callback
• Callback Virtual Account
• Callback Ewallet Payment

Can I reuse the same reference ID?

No. Use a unique reference ID for each transaction. Reusing a reference ID can cause duplicate detection, reconciliation confusion, or rejected requests.

Recommended format:

• Stable and unique from your system.
• Easy to search in logs.
• Not based only on timestamp.
• Stored together with Brick transaction identifiers.

How should I handle timeouts?

If your client times out, do not immediately assume the transaction failed. The request may still have reached Brick and may still be processing.

Recommended flow:

1. Log the request reference ID.
2. Query the relevant status endpoint.
3. Wait for callback if the status is still pending.
4. Retry only when your integration can do so safely with idempotency protection.

Reference:

• Error Handling

Callbacks

Why am I not receiving callbacks?

Check the following:

• Callback URL is publicly reachable from the internet.
• URL uses HTTPS with a valid certificate.
• Your firewall or WAF is not blocking Brick requests.
• The endpoint accepts the expected HTTP method and payload format.
• Your application returns a successful HTTP response quickly.
• Callback configuration is set for the correct environment.

If you recently changed the callback URL, test again in Sandbox before relying on it in Production.

What should my callback handler do?

Keep callback processing reliable and short:

1. Verify the callback source and signature when required.
2. Validate the payload.
3. Store the raw event or an auditable event record.
4. Update transaction status idempotently.
5. Return a successful HTTP response quickly.
6. Run heavier downstream actions asynchronously.

Avoid long-running business logic directly inside the callback response path.

What if a callback arrives before my frontend is updated?

That is normal. Treat callbacks as backend system events. Your frontend should read the latest transaction status from your backend instead of assuming that the browser session has the final state.

Send Money: Disbursement

Which disbursement method should I use?

Choose based on your operational need:

Method	Typical fit
BIFAST	Faster transfer flow where bank coverage and limits match your use case.
Regular disbursement	Broader operational fallback or flows where BIFAST is not available.

Always confirm current coverage, limits, and behavior in the API pages before release.

References:

• BIFAST Disbursement API
• Regular Disbursement
• List of Bank Coverage

Should I validate a bank account before disbursement?

Yes, especially when account data is collected from users or external systems. Account validation helps reduce failed disbursements caused by incorrect bank account numbers or mismatched account details.

Reference:

• Account Validation

Why is a disbursement stuck in PENDING?

Possible reasons:

• Bank processing is still in progress.
• The partner network has not returned a final status.
• Callback delivery is delayed.
• Your system has not processed the latest callback.

Recommended checks:

1. Search by your reference ID.
2. Check status by disbursement ID or reference ID.
3. Review callback logs.
4. Confirm whether the destination bank is experiencing delay.

References:

• Check Status by Disbursement ID
• Check Status by Reference ID
• BIFAST Callback
• Regular Callback

Why does my balance differ from ledger or transaction history?

Different views can answer different questions:

View	What it is useful for
Available balance	Amount currently available for new transactions.
Ledger	Transaction movement and reconciliation trail.
Transaction history	Operational review, filtering, export, and support investigation.

Use ledger and transaction history for reconciliation, not only dashboard balance.

References:

• Ledger / Disbursement History
• Transaction History
• Export Data

How do I provide proof of transfer?

Use the transfer proof feature when your operation needs a downloadable proof for completed disbursements.

Reference:

• Download Transfer Proof API

Receive Money

What is the difference between Open VA and Closed VA?

VA type	Typical behavior	Best fit
Open VA	Reusable virtual account with flexible payment amount.	Customer wallet top-up or recurring customer payments.
Closed VA	One-time or fixed payment flow with an expected amount.	Invoice, checkout, or order-specific payment.

References:

• Virtual Account Overview
• Generate Open VA
• Generate Close VA

Why is a VA payment not reflected yet?

Possible causes:

• Bank processing or settlement delay.
• Callback has not been delivered yet.
• Callback was delivered but your endpoint rejected it.
• Your system has not reconciled the latest VA status.

Recommended checks:

1. Check callback delivery logs.
2. Query VA status.
3. Confirm the payment amount and VA identifier.
4. Reconcile against transaction history if needed.

References:

• Callback Virtual Account
• Status of Open VA
• Status of Close VA

What is the difference between Static QR Code, Dynamic QR Code, and QR Code SNAP?

QR Code type	Typical use
Static QR Code	Reusable QR code for merchant payment acceptance.
Dynamic QR Code	QR code generated for a specific transaction or amount.
QR Code SNAP	SNAP-based QR Code integration using SNAP authentication and request standards.

If you are using QR Code SNAP, start with the SNAP token flow before generating or querying QR Code transactions.

References:

• QR Code Overview
• Generate Dynamic QR Code
• Get Access Token (SNAP)
• Generate Dynamic QR Code (SNAP)

Why can I not generate QR Code?

Common causes include:

• Merchant is not registered or not active.
• QR Code product access has not been enabled.
• Required request fields are missing or invalid.
• QR Code SNAP request is using an invalid token, timestamp, or signature.
• You are calling the wrong environment.

References:

• Registering for QR Code
• QR Code Testing in Sandbox
• Dynamic QR Code Status (SNAP)

When should I use Ewallet or Checkout Page?

Use Ewallet APIs when you want to create and control an Ewallet payment flow directly from your system.

Use Checkout Page when you want a hosted payment page with Brick-managed payment experience, redirects, and checkout status handling.

References:

• Ewallet Overview
• Create Ewallet Payment Link
• Checkout Page Overview
• Create Checkout Page Session

Why does an Ewallet or checkout payment remain unpaid?

Possible causes:

• Customer did not complete the payment.
• Customer closed the app or browser during redirect.
• Payment expired.
• Provider or payment channel was temporarily unavailable.
• Your system has not received or processed the callback.

Recommended checks:

1. Query payment status.
2. Check callback logs.
3. Confirm the payment expiry time.
4. Confirm customer redirect behavior.

References:

• Status Ewallet Payment
• Callback Ewallet Payment
• Checkout Status

Reconciliation And Operations

What data should I store for reconciliation?

Store enough data to trace each transaction across your system, Brick, callbacks, and customer support tools:

• Your reference ID.
• Brick transaction ID or disbursement ID when returned.
• Product type and payment method.
• Amount and currency.
• Current status and status history.
• Raw callback payload or auditable event record.
• Request timestamp and final status timestamp.
• Environment.

This makes support, finance reconciliation, and incident investigation much faster.

How often should I reconcile transaction status?

Use callbacks for real-time updates, then run scheduled reconciliation for safety. The exact interval depends on your volume and operational needs, but a common approach is:

• Short-term checks for transactions still pending after expected processing time.
• Daily reconciliation for finance and operations.
• Manual status lookup for customer support cases.

What should I do before going live?

Use a production readiness review:

• Test successful, failed, pending, and expired scenarios.
• Validate callback signature handling where applicable.
• Confirm idempotent status updates.
• Confirm retry behavior and timeout handling.
• Confirm logging and monitoring.
• Confirm reconciliation workflow.
• Confirm escalation path for operational issues.

Reference:

• Production Checklist

Troubleshooting And Support

What information should I provide when reporting an issue?

Include:

• Environment: Sandbox or Production.
• Product: disbursement, VA, QR Code, Ewallet, checkout, or another product.
• Endpoint called.
• Your reference ID.
• Brick transaction ID, disbursement ID, or payment ID if available.
• Timestamp with timezone.
• Request payload sample with secrets removed.
• Response body and HTTP status code.
• Callback payload or callback delivery logs if relevant.
• Expected result and actual result.

Never send API secrets, private keys, or full authorization headers in support messages.

Reference:

• Error Handling

How can BrickI or Brick MCP help during implementation?

Use Meet BrickI when you need guided support or help finding the right documentation path.

Use Brick MCP when your AI coding assistant needs structured access to Brick documentation while helping you implement, debug, or review an integration.

For production changes, always validate AI-generated output against the official docs, Sandbox behavior, and your internal engineering review process.