> For the complete documentation index, see [llms.txt](https://apc-pay.gitbook.io/apc-pay-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apc-pay.gitbook.io/apc-pay-docs/apc-pay/native-api-integration.md).

# Native API Integration

Updated 2026-10-14

The Native API lets your backend create outbound fiat payouts funded from your merchant USDT balance. Your server controls request signing, payout creation, status reconciliation, and callback processing.

> ❇️
>
> ### Real payouts
>
> The supplied materials do not document a sandbox. Treat `/payout/create` as a real-money operation unless APC Pay has explicitly provided you with a test environment.

## Base URL

```
https://pwc-pay-api.chiachair.com/v1
```

| Operation                    | Method and backend path | Guide                                                                           |
| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
| Query USDT balance           | `POST /balance/query`   | [Balance and Currency](broken://pages/c374e00afa6fb109644d34b6d82fbe7b0d8b38c7) |
| Query currency configuration | `POST /currency/query`  | [Balance and Currency](broken://pages/c374e00afa6fb109644d34b6d82fbe7b0d8b38c7) |
| Create a payout              | `POST /payout/create`   | [Create a Payout](broken://pages/85bb23f0c564b16167e4d27ad120123daf5f90b3)      |
| Query a payout               | `POST /payout/query`    | [Query a Payout](broken://pages/d322bd86cc349f7eef7630c43fcea7a59ed35e89)       |

Send requests to the full public URL, including `/v1`. For request signing, use only the backend path in the table.

## Setup requirements

Before calling the API, obtain and configure:

| Requirement               | Purpose                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Merchant number (`mchNo`) | Identifies your merchant account.                                                                 |
| App ID (`appId`)          | Identifies the app making each request.                                                           |
| Merchant RSA key pair     | Your server signs with the private key; APC Pay verifies with the public key uploaded to the app. |
| Platform public key       | Verifies successful response data and payout callbacks.                                           |
| IP whitelist              | Allows each production server public egress IP. CIDR ranges and wildcards are not supported.      |
| Currency whitelist        | Enables every fiat currency the app will use.                                                     |
| Public HTTPS callback URL | Receives final `SUCCESS` or `FAILED` payout notifications.                                        |
| Funded merchant balance   | Pays the locked USDT cost of accepted orders.                                                     |

Store private keys and credentials only in server-side protected configuration. Confirm the public-key fingerprints in the merchant portal before sending requests.

## End-to-end flow

```mermaid
sequenceDiagram
    autonumber
    participant M as Merchant backend
    participant P as APC Pay API
    participant C as Payout channel

    M->>P: Signed currency and balance queries
    P-->>M: Verified configuration and funds
    M->>P: Signed create request with unique mchOrderNo
    P-->>M: Verified ACCEPTED payout and locked values
    P->>C: Process payout
    C-->>P: Final result
    P->>M: Signed SUCCESS or FAILED callback
    M-->>P: HTTP 200, body: success
    M->>P: Signed query when reconciliation is needed
    P-->>M: Verified current state
```

Implement the flow in this order:

1. [Authenticate and sign requests](broken://pages/09fdb741f99cf1deb38cf1b90b063767f12807df).
2. [Query balance and currency configuration](broken://pages/c374e00afa6fb109644d34b6d82fbe7b0d8b38c7).
3. [Create a payout](broken://pages/85bb23f0c564b16167e4d27ad120123daf5f90b3) with a unique `mchOrderNo`.
4. Store `payoutOrderId`, status, amount, currency, rates, fees, and locked USDT cost.
5. [Verify and process the final callback](broken://pages/3ddd4c5270f1825eb62c85633eddb69b50a33b8c) idempotently.
6. [Query the payout](broken://pages/d322bd86cc349f7eef7630c43fcea7a59ed35e89) after a timeout, `4001 SYSTEM_ERROR`, or delayed callback.

## Security model

* Sign each request with the merchant private key using RSA-SHA256.
* Verify every successful non-empty response `data` signature with the platform public key.
* Bind a response to its request by verifying `data.nonceStr`.
* Verify callback signatures before reading or applying their state.
* Match merchant, app, order, amount, and currency to stored data.
* Deduplicate callbacks using a durable unique constraint on `notifyId`.

## Idempotency rule

`mchOrderNo` is the payout idempotency key. Reuse it only when retrying the same payout with identical business parameters.

After an uncertain create result, query the original `mchOrderNo` before retrying. Every retry must use a fresh request time, nonce, and signature.

## Integration guides

* [Balance and Currency](broken://pages/c374e00afa6fb109644d34b6d82fbe7b0d8b38c7)
* [Authentication and Request Signing](broken://pages/09fdb741f99cf1deb38cf1b90b063767f12807df)
* [Create a Payout](broken://pages/85bb23f0c564b16167e4d27ad120123daf5f90b3)
* [Query a Payout](broken://pages/d322bd86cc349f7eef7630c43fcea7a59ed35e89)
* [Payout Webhooks](broken://pages/3ddd4c5270f1825eb62c85633eddb69b50a33b8c)
* [Payout Statuses and Errors](broken://pages/1701152330ec298b264aa8660498f37921c96df6)
* [Production Checklist](broken://pages/51586ee1dbdda74e18dfca2a30c3f8205ecce9e0)

For a runnable path through the supplied TypeScript example, start with the [Quick Start](broken://pages/22c43dd09ce841ec9d903208e876a09fee1a58fe).