> For the complete documentation index, see [llms.txt](https://docs.jgopay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jgopay.com/english/readme.md).

# Overview

> **Version:** 1.6.0\
> **Last Updated:** July 2026

> 🇨🇳 [简体中文版本](/jian-ti-zhong-wen/zh-cn.md)

| Environment | Base URL                             |
| ----------- | ------------------------------------ |
| Production  | `https://api.pays3bucket.com/api/v1` |

> Staging credentials and endpoint are available on request from your account manager.

## Supported Currency

| Currency | Region   | Deposits               | Withdrawals | Gateway Behavior |
| -------- | -------- | ---------------------- | ----------- | ---------------- |
| **MYR**  | Malaysia | DuitNow QR / FPX / TNG | Bank        | Redirect         |

## Integration Flow

### Deposits

```
1. Authenticate     →  POST /auth/token
2. Create Payment   →  POST /payment/request
3. Handle Response  →  Redirect customer
4. Receive Callback  →  Payment status notification
```

### Withdrawals

```
1. Authenticate     →  POST /auth/token
2. Create Withdrawal →  POST /payment/withdraw
3. Receive Callback  →  Withdrawal result notification
```

## Quick Start

1. **Get your credentials** — You'll receive a `merchant_id` and `api_key` from your account manager
2. **Authenticate** — Exchange credentials for an access token ([Authentication](/english/authentication.md))
3. **Create a payment** — Call the payment endpoint ([Create Payment](/english/create-payment.md))
4. **Handle the response** — Redirect the customer to the gateway page ([Payment Methods](/english/payment-methods.md))
5. **Create a withdrawal** — Call the withdrawal endpoint ([Create Withdrawal](/english/create-withdrawal.md))
6. **Receive callbacks** — Get notified when payment or withdrawal completes ([Callbacks](/english/webhooks.md))

## Integration modes

| Mode                            | Request                                       | Customer flow                                                                                                                                        |
| ------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mode 1 — Direct integration** | Supply `payment_method`                       | Your integration chooses the method and handles the returned QR page or gateway redirect. For online banking, supply `metadata.provider_channel_id`. |
| **Mode 2 — Hosted checkout**    | Omit `payment_method` and `preferred_gateway` | Open `payment_url`. The customer selects TNG, DuitNow QR, or online banking, then selects their bank when needed.                                    |

These modes use the same endpoint; do not send a `mode` field. Mode 2 starts as `PENDING` and has no `gateway` data until the customer selects a method. The checkout shows our payment ID and amount, without the merchant name or merchant reference.

Open MYR checkout as a full page in the current tab or a customer-clicked new tab. Embedded Mode 2 pages offer an **Open payment page** handoff for the same session. Online banking availability depends on the merchant’s configured minimum and gateway limits; this minimum affects Mode 2 only. See [Create Payment](/english/create-payment.md) for request examples, iframe guidance, and amount rules.

## Rate Limiting

API endpoints are rate-limited per merchant. Exceeding the limit returns HTTP `429 Too Many Requests`.

| Endpoint                 | Limit            |
| ------------------------ | ---------------- |
| `POST /payment/request`  | 100 requests/min |
| `POST /payment/withdraw` | 50 requests/min  |
| Other endpoints          | 100 requests/min |

## Security

* All API requests **must use HTTPS** (`https://`). HTTP requests are rejected.
* `callback_url` and `redirect_url` **must use HTTPS** in production. HTTP URLs will be rejected.
* Never transmit API keys, access tokens, or credentials over unencrypted connections.
* See [Authentication](/english/authentication.md) for credential storage and rotation guidance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.jgopay.com/english/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.