# FAQ (Coding)

> Agent reads this ONCE before writing code. Filter items by the user's product. Do NOT re-read during troubleshooting.

---

## 1. Gateway selection causing API request errors

- **Products**: All

Antom uses regional gateways. Sending requests to the wrong gateway URL results in connection failure or authentication errors.

| Region | Gateway URL |
|--------|-------------|
| NA - US | `https://open.antglobal-us.com` |
| NA - Non-US | `https://open-na-global.alipay.com` |
| Asia | `https://open-sea-global.alipay.com` |
| Europe | `https://open-de-global.alipay.com` |

**Common mistakes**:
- Not selecting the correct regional gateway URL from the table above (e.g., using a non-listed gateway or choosing the wrong region for the merchant's registered region)

**Action**: Get the gateway URL, client ID, and keys for the sandbox environment through Developer > Quick start > Integration resources and tools. Verify the gateway URL matches the merchant's region. In generated code, leave gatewayUrl, ClientId, and keys as empty placeholders with inline comments (in the user's working language) stating purpose and retrieval path — never pre-fill values.

---

## 2. Subscription expiry time parameter errors

- **Products**: Subscription

Subscription expiration time (`subscriptionExpiryTime`) must follow specific constraints in the `createPaymentSession` API. Passing an invalid value results in:

```json
{
  "result": {
    "resultCode": "PARAM_ILLEGAL",
    "resultMessage": "Illegal parameters. For example, non-numeric input, invalid date.",
    "resultStatus": "F"
  }
}
```

**Parameter rules**:

| Parameter path | Default | Constraint |
|---------------|---------|------------|
| `subscriptionInfo.subscriptionExpiryTime` | 7 days (card / Apple Pay / Google Pay), 80 min (APM) | APM must be > 74 min |

**Common mistakes**:
- Setting the expiry time too short for APM
- Using incorrect datetime format (must be ISO 8601 with timezone, e.g., `2025-11-27T12:00:01+08:30`)
- Setting the expiry time in the past

**Action**: Use the default value if no specific expiry is needed. Note the different defaults between card and APM payment methods. Always use ISO 8601 format with timezone.

---

## 3. Settlement currency parameter errors

- **Products**: All

Omit `settlementCurrency` by default. Single-currency contracts are auto-filled by Antom. If the merchant has multiple contracted currencies, add `settlementCurrency` proactively.

**Action**: Code without `settlementCurrency` by default. If multiple currencies are contracted, set `settlementCurrency` with the correct value. User can check contracted currencies at Dashboard → Finance → Overview (https://dashboard.antom.com/global-payments/finance/overview). For sandbox, switch to **Test mode** first.

---

## 4. Currency code and amount format errors

- **Products**: All

The amount object requires `currency` (3-letter ISO 4217 code) and `value` (a string representing a positive integer in the smallest currency unit). Incorrect formatting results in API parameter errors.

**Common mistakes**:
- Passing decimal or float values instead of integer strings (e.g., `"10.50"` instead of `"1050"` for USD)
- Ignoring 0-decimal-place currencies — JPY, KRW, VND, CLP have no fractional unit, so ¥1 is `"1"`, not `"100"`
- Violating payment-method-specific value constraints (e.g., JKOPay TWD must be a multiple of 100, Octopus HKD must be a multiple of 10, IDR must be a multiple of 100)
- Passing an amount below the payment method's minimum limit (e.g., DANA minimum is 300 IDR)

**Action**: Before writing code involving any amount object, read [Currency Code & Amount Reference](https://docs.antom.com/ac/ref/cc.md) to confirm the correct currency code, smallest unit rules, and any payment-method-specific constraints.

---

## 5. Subscription notification URL field configuration

- **Products**: Subscription

Subscription integration exposes exactly two URL fields at subscription creation. Multiple notification classes arrive at the same URL — distinguish them by inspecting `notifyType` in the body.

**Action**: Fill in both URL fields on the subscription-creation API request. Dispatch by reading `body.notifyType` inside the endpoint(s). See the `Notification URL Configuration` section of [subscription-notify.md](https://cdn.marmot-cloud.com/page/antom-integration-doc/subscription/notify/subscription-notify.md) for the field name mapping.