> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niobi.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Best Practices

This section is designed to help developers integrate with our API more efficiently and reliably. It highlights best practices, common pitfalls, and configuration tips.

We strongly recommend reviewing this page before starting your integration.

## Phone Number Validation

Proper phone number validation is essential to avoid rejected transactions or delivery failures. Here’s what to keep in mind:

### Validation Rules

* **Length Requirements**:
  * Minimum: 8 digits (excluding country code)
  * Maximum: 15 digits (including country code)
* **Characters**:
  * Only digits allowed. No spaces, `+`, or symbols.

### Country Code Formatting

* Always prepend the correct country code.
* Example:
  * Kenya: `254712345678`
  * Ghana: `233501234567`
* Do not prefix with `+`, `00`, or local formats like `07xxx`.
* **Correct:** `254712345678` (Kenya)
* **Incorrect:** `+254 712 345 678` or `0712345678`

### Common Pitfalls

* Using local formats (e.g., `0712...`) without converting to international format.
* Adding trailing symbols like +
* Mismatching the country code with the country specified in the API request

## Callback Configuration

Callbacks allow us to notify your system of transaction events. To ensure proper delivery, follow the setup guidelines below:

### Required Fields

* Your endpoint **must** accept POST requests with:
  * `reference`
  * `status`
  * `amount`
  * `timestamp`
  * `transaction_id`

### Valid Endpoint Format

* Must be publicly accessible.
* Should respond with HTTP status `200` to confirm receipt.

### Expected responses

* The expected status codes and statuses sent within the callback body can be found [here](/callback-urls)

### Callback Testing Tips

* Use tools like [Webhook.site](https://webhook.site/) or Postman’s Mock Server for initial testing.
* Monitor logs to ensure your server handles callback retries properly.
* Simulate various status codes (e.g., `failed`, `success`, `pending`) for robust testing.

See detailed [callback response schema](/callback-urls)

## Transaction Status API Usage

The [Transaction Status API](/api-reference/payment/niobi-get-transaction-status-v3) lets you query the transaction status besides the callback notifications.

### When to Use It

* To verify transaction status post-callback
* To check pending or delayed payments

### Best Practices

* **Avoid frequent polling** — respect API rate limits.
* Cache results where possible to reduce unnecessary requests.
* Always handle `4xx` and `5xx` errors gracefully:
  * Retry on 5xx with exponential backoff.
  * Log and escalate 4xx (e.g., `404` for invalid reference).