# Setup

> Configure the Account service base URL, apikey, x-timestamp, and outbound IP allowlist before calling account balance, account transaction, account statement, and Global Account APIs.

Account service APIs use dedicated base URLs and an environment-specific `apikey` request header. Before you call account balance, account transaction, account statement, or Global Account endpoints, make sure the target environment, API access, `apikey`, `x-timestamp`, and outbound IP allowlist are ready.

## Setup steps

<steps level="3">

### Confirm API access

Account service APIs are restricted. Onerway must enable the corresponding capability for your merchant account before you can call the endpoints.

- Before calling account balance, account transaction, and account statement APIs, confirm that Account service API access is enabled.
- Before calling Global Account APIs, confirm that Global Account opening, collection, or payout capabilities are enabled.
- If a platform merchant queries on behalf of a sub-merchant, confirm that the parent-child merchant relationship and `onBehalfOf` permission are configured.

### Select the base URL

Use the Account service base URL that matches the environment of your `apikey`.

| Environment | Base URL |
| --- | --- |
| Production | `https://api.onerway.com/account-server` |
| Sandbox | `https://sandbox-api.onerway.com/account-server` |

<note>

Sandbox and production credentials are separate. API paths start with `/api/v2/...` or with the `/api/v1/...` path shown on the current Global Account page. The base URL, API path, and `apikey` must come from the same environment.

</note>

### Store the apikey

Account service APIs identify caller permissions through the `apikey` request header.

| Header | Required | Description |
| --- | --- | --- |
| `apikey` | Yes | Credential value assigned for Account service access. |

<warning>

Store the `apikey` on your server. Do not expose it in frontend pages, mobile apps, client-side bundles, logs, or public repositories.

</warning>

### Send x-timestamp

Account balance, account transaction, and account statement APIs require both `apikey` and `x-timestamp`. The gateway uses `x-timestamp` to check whether the request is within the accepted time window and reduce replay risk.

| Header | Required | Description |
| --- | --- | --- |
| `x-timestamp` | Yes | Request timestamp. Accepts 10-digit seconds or 13-digit milliseconds. Must be within 10 minutes of the server time. |
| `Content-Type` | Yes (POST) | `application/json`. |

### Provide outbound IP addresses

Send your stable server outbound IP addresses to Onerway so they can be added to the Account service allowlist.

- Provide only stable server outbound IP addresses.
- If sandbox and production use different outbound IP addresses, provide them separately.
- If an outbound IP address changes, update the allowlist before switching traffic.

### Send a server-side request

After the environment, `apikey`, `x-timestamp`, and IP allowlist are ready, call the API from your server and include the required request headers.

```bash
curl https://sandbox-api.onerway.com/account-server/api/v2/account/balance/overview/query \
  -H 'Content-Type: application/json' \
  -H 'apikey: replace_with_account_service_apikey' \
  -H 'x-timestamp: 1776931200' \
  -d '{
    "requestId": "REQ-BAL-OV-20260423-0001",
    "displayCurrency": "USD"
  }'
```

</steps>

## Endpoint URLs

The current public Account service endpoint URLs are listed below. Build the request URL by appending the API path to the base URL for the target environment.

| Category | Endpoint | Method | Path |
| --- | --- | --- | --- |
| Account balance | Query account balance overview | `POST` | `/api/v2/account/balance/overview/query` |
| Account balance | Query account balance | `POST` | `/api/v2/account/balance/query` |
| Account transaction | Query account transactions | `POST` | `/api/v2/account/transactions/query` |
| Account transaction | Query account transactions by transaction order number | `POST` | `/api/v2/account/transactions/service/query` |
| Account statement | Export daily account statement | `POST` | `/api/v2/account/statement/daily/export` |
| Global Account | Create Global Account | `POST` | `/api/v1/account/global/create` |
| Global Account | Get Global Account details | `POST` | `/api/v1/account/global/getDetail` |

Complete Sandbox examples:

- `https://sandbox-api.onerway.com/account-server/api/v2/account/balance/overview/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/balance/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/service/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/statement/daily/export`
- `https://sandbox-api.onerway.com/account-server/api/v1/account/global/create`
- `https://sandbox-api.onerway.com/account-server/api/v1/account/global/getDetail`

## Idempotency

Account balance, account transaction, and account statement APIs are idempotent. Reuse the same `requestId` to safely retry a request within 10 minutes. A repeated `requestId` returns a `10006 DUPLICATE_REQUEST` error of type `idempotency_error`.

## Next steps

- [Query account balance overview](/account/api-reference/endpoints/query-account-balance-overview) - Query multi-currency account balance summaries
- [Query account balance](/account/api-reference/endpoints/query-account-balance) - Read the balance for one account currency
- [Query account transactions](/account/api-reference/endpoints/query-account-transactions) - Review account transaction records and balance movements
- [Query account transactions by transaction order number](/account/api-reference/endpoints/query-account-transactions-by-service-id) - Query related account transactions by transaction order number
- [Export daily account statement](/account/api-reference/endpoints/export-daily-statement) - Export a daily account statement CSV
- [Create Global Account](/account/api-reference/endpoints/create-global-account) - Create a Global Account for collection and payout scenarios
- [Get Global Account details](/account/api-reference/endpoints/get-global-account-details) - Retrieve Global Account onboarding details and status
- [Response codes](/account/api-reference/response-codes) - Handle Account service response codes and troubleshooting actions