Near Pay External API Integration Guide
This guide is for third-party developers collecting payments with Near Pay. Your business server calls the open API; Near Pay handles collection routing, transaction states, and refunds. Keep AppSecret, EncryptKey, and signature operations on your server.
Read in this order: Apply for an application → configure notifications and authorization → obtain and activate keys → verify signatures → create and pay an order → receive notifications/query status → refund → production acceptance.
The current protocol uses /open/pay/v1, HMAC-SHA256 signing, and AES-256-GCM field/notification encryption. Available payment methods, currencies, and refund capabilities depend on what the platform has enabled for your application and store.
1. Before you integrate
Submit the following information through the platform's designated application channel or integration contact. The current open API has no anonymous registration, key application, approval, or self-service store authorization endpoints. The platform provisions these before you call the transaction APIs.
| Information | What to provide |
|---|---|
| Integrator and application | Company/platform name, application name, purpose, technical contact, incident contact channel |
| Business ownership | Collecting entity, target stores, operating market, currency |
| Environment | Sandbox or production; apply separately and keep credentials separate |
| Capabilities | Read, collect, refund; request only what you need |
| Source IP | Fixed server egress IP or CIDR; a container's internal IP is usually not the address seen by the platform |
| Notifications | Public HTTPS notification URL, allowed callback domains, receiving-service contact |
| Capacity and limits | Expected peak QPS, refund requirements, requested daily refund limit |
| Payment methods | Target device/browser environment and desired methods; the platform confirms available products |
The platform must be able to reach your notification service. Its certificate must be valid and DNS must not resolve to loopback, private, or link-local addresses. Notifications are separate from the customer's browser return page and must not depend on browser login cookies.
1.1 Provisioning steps and readiness criteria
| Step | Platform action | What to confirm |
|---|---|---|
| 1. Register application | Record ownership, purpose, environment; allocate AppId; application awaits activation | Correct AppId, ownership, environment |
| 2. Configure capabilities | Configure READ/COLLECT/REFUND, rate limit, refund limit, egress IP | Separate permissions and limits for read, collect, refund |
| 3. Configure and verify notifications | Register URL/domain and complete platform verification | URL accepts POST; follow the supplied verification procedure |
| 4. Approve and activate application | Review and activate the application | Application is ACTIVE; AppId alone is insufficient |
| 5. Issue and activate keys | Generate AppSecret/EncryptKey after application activation; verify, approve, activate keys | Securely receive one-time plaintext and serials; the usable version is active; DRAFT keys cannot call APIs |
| 6. Authorize stores | Grant specific stores and actions through platform/merchant authorization management | Correct storeRef and granted actions |
| 7. Test and accept | Verify signatures, business outcomes, notifications, recovery | Pass sandbox acceptance, then provision production separately |
Application activation, key activation, and store authorization are three independent requirements. Application actions map to API scopes as follows:
| Action | API scope | Allowed calls |
|---|---|---|
| READ | pay:read |
Query payments/refunds and available store payment methods |
| COLLECT | pay:create |
Create orders, initiate payments, close orders |
| REFUND | pay:refund |
Request refunds |
Effective access is current application permissions ∩ authorized store actions ∩ enabled store products and current business restrictions. Refund scope also requires REFUND authorization on the original payment's store and sufficient limits.
1.2 Connection details you receive
| Item | Purpose and handling |
|---|---|
| API_BASE_URL | Platform-provided environment address; examples assume an HTTPS origin with no extra path prefix |
| AppId | Application number assigned by the platform; sent as X-App-Id |
| AppSecret | Request signing and response/notification verification; normally prefixed sk_test_ or sk_live_ |
| Signing key serial | Request X-Key-Serial and response/notification signing-version lookup; store as an opaque string |
| EncryptKey | 32 UTF-8 bytes, currently issued as 32 alphanumeric characters; encrypts sensitive fields and notification resource |
| Encryption key serial | Request X-Encrypt-Serial and notification resource.keySerial lookup |
| storeRef | Platform-provided authorized store business number, not an internal database ID |
| Notification confirmation | Registered URL, verification status, whether encrypted notifications are enabled |
| Limits and capabilities | QPS, daily refund limit, currencies, payment methods, refund restrictions |
Key plaintext is provided only once at issuance. Request a new version if lost; do not rely on retrieving plaintext later. Application, payment-channel, and POS-device keys are different and cannot substitute for one another. The AppSecret display prefix does not participate in HMAC. Do not strip a prefix from EncryptKey or Base64-decode it.
2. Common requests and responses
2.1 Addresses and environments
{API_BASE_URL}/open/pay/v1/orders
Sandbox and production each use separate AppIds, keys, and authorization. The platform provides domains, entry points, and available channels. Do not infer an address from an example domain or key prefix. Do not add /api or use internal/operations endpoints as open APIs.
APP-DEMO, STORE-DEMO-001, and P-DEMO-001 are placeholders. Replace them with provisioned values. Example amounts do not imply that a store supports those limits.
2.2 Required request headers
| Header | Required | Description |
|---|---|---|
Content-Type |
For JSON | application/json; charset=UTF-8 |
X-App-Id |
Yes | Application AppId |
X-Timestamp |
Yes | Current UTC milliseconds as a decimal string; within 300 seconds of platform time |
X-Nonce |
Yes | Unique per HTTP request, 8–64 characters; 32 random hexadecimal characters recommended |
X-Signature |
Yes | Standard Base64 signature calculated using P1 in section 3 |
X-Key-Serial |
Recommended | Platform-issued signing-version serial; specify explicitly during rotation |
X-Encrypt-Serial |
With encrypted fields | EncryptKey serial used for these sensitive fields |
X-Request-Id |
No | Troubleshooting correlation ID; not a business idempotency number |
For each retry, generate a new timestamp, nonce, and signature while preserving the business number and business parameters. Do not replay the previous signed HTTP request unchanged.
2.3 Success and error envelopes
{
"code": 0,
"message": "OK",
"data": {},
"requestId": "REQ-DEMO-001"
}
code=0 means the API operation succeeded. Read data.status for the payment outcome. HTTP 200, successful order creation, and returned payment parameters do not prove receipt of funds. Error responses also use code/message/data/requestId. Handle HTTP status first, then nonzero business codes. message is for display/troubleshooting, not program branching.
2.4 Numbers, times, and fields
- JSON uses camelCase and UTF-8 request bodies.
amountMinor/paidMinor/refundedMinorare integers in the currency's smallest unit. For a two-decimal currency, 12000 means 120.00. Use the platform's currency precision configuration; not all currencies have two decimals.- Send amounts as JSON integers, not
120.00or strings relying on coercion. JavaScript amounts must be within the safe integer range; discuss compatibility with the platform before exceeding it. - Time fields are UTC millisecond integers. Unoccurred or inapplicable fields may be null.
- Ignore unknown new response fields. Treat unknown states as requiring reconciliation, not automatic success or failure.
3. Signing, verification, and encryption
3.1 P1: Request signing
Encrypt sensitive fields first, then sign the final raw request-body bytes you will send.
stringToSign =
METHOD + "\n" +
PATH + "\n" +
CANONICAL_QUERY + "\n" +
APP_ID + "\n" +
TIMESTAMP + "\n" +
NONCE + "\n" +
lowercase_hex(SHA256(rawBody))
X-Signature = Base64(HMAC-SHA256(hmacKey, UTF8(stringToSign)))
- Uppercase METHOD. PATH contains only the API path, without scheme, host, query, or fragment. Use the actual accepted path; do not independently add/remove a trailing
/. - The signing string has seven lines separated by LF and no trailing newline. Preserve the empty third line when there is no query.
- Sort QUERY by decoded parameter name, then value for repeated names. RFC3986-encode names and values separately; join with
=and&. A space is%20, a literal+is%2B, and~remains unencoded. - For GET without a body, hash an empty byte sequence, not
{}. Its SHA-256 ise3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. hmacKeyis the UTF-8 bytes of AppSecret after removingsk_test_/sk_live_. Do not Base64/Hex-decode it again.- Use standard Base64, not Base64URL or hexadecimal.
- Serialize the body once and send the exact bytes you hashed. Whitespace, Unicode encoding, newlines, and field order affect signatures.
Query example:
Input: b=%2B&a=hello+world&a=hello%20world&empty=
Canonical: a=hello%20world&a=hello%2Bworld&b=%2B&empty=
3.2 P2: Response and webhook verification
Use the response/notification's own timestamp, nonce, signature, and actual raw body:
responseString = X-Timestamp + "\n" + X-Nonce + "\n" + lowercase_hex(SHA256(rawResponseBody))
expected = Base64(HMAC-SHA256(hmacKey, UTF8(responseString)))
Read raw bytes first, check the time window, select your stored AppSecret version using X-Key-Serial, and compare signatures in constant time. Parse business content only after verification. P2 is different from the P1 request signing string.
Authentication failures may be unsigned when the platform has no usable signing key for the application. Network/proxy error pages may also be unsigned. Treat them as integration/transport errors; they do not confirm payment failure and must not trigger another charge. After correcting configuration, query the original business order first.
3.3 P3: Encrypting sensitive request fields
| API | JSON field paths |
|---|---|
| Create payment order | payer.phone, payer.email, payer.name |
| Request refund | refundAccount.bankCode, refundAccount.accountNo, refundAccount.accountName |
These objects may be omitted. Encrypt every supplied sensitive field independently; null fields may be omitted. Queries return masked values only.
Algorithm: AES-256-GCM
key: UTF8(EncryptKey), 32 bytes
IV: 12 random bytes per field
AAD:UTF8(AppId + "|" + 字段完整点路径)
Field value: Base64(IV || ciphertext || tag)
tag length: 16 bytes
The AAD for refundAccount.accountNo is, for example, APP-DEMO|refundAccount.accountNo. Never reuse an IV across fields, even for identical values. Sign again after re-encryption. payerOpenId/payerAppId are not in the sensitive-field table; pass them normally according to business requirements.
The Node.js example provides encryptField. Prepare a sensitive body in this order: encrypt fields → serialize JSON once → P1-sign → send those JSON bytes.
3.4 P4: Decrypting notification resource
Verify the entire raw webhook body using P2 before decrypting resource:
Algorithm: AES-256-GCM
key: EncryptKey version identified by resource.keySerial
IV: Base64Decode(resource.nonce), 12 bytes
AAD:UTF8(eventType + "|" + eventId)
Input: Base64Decode(resource.ciphertext) = ciphertext || tag
resource.associatedData must equal your locally reconstructed eventType|eventId. P4's nonce is a separate field, not part of ciphertext. P3 prefixes the IV to its ciphertext; the formats are not interchangeable. Process the decrypted object as described in section 7.
3.5 Offline checks
Download the examples and test vectors and save all three files together:
python3 open_api.py --self-test
node crypto.mjs
Public vectors include historical timestamps and fixed IVs for offline verification only. Online requests require current timestamps and random nonces/IVs. The lowercase P4 event name validates an existing encryption vector; business notification enums are the uppercase names in section 7.
4. Your first API call
Confirm the application, signing key, and store READ authorization are active. This Python standard-library example verifies responses before parsing. It is not a production SDK; implement multi-version key lookup in your system.
Save open_api.py as a module and run from the same directory:
import os
import urllib.parse
from open_api import OpenApi
client = OpenApi(
os.environ["NEARPAY_BASE_URL"],
os.environ["NEARPAY_APP_ID"],
os.environ["NEARPAY_APP_SECRET"],
os.environ.get("NEARPAY_KEY_SERIAL"),
)
store_ref = urllib.parse.quote(os.environ["NEARPAY_STORE_REF"], safe="")
http_status, envelope = client.call(
"GET", f"/open/pay/v1/stores/{store_ref}/pay-methods"
)
if http_status != 200 or envelope["code"] != 0:
raise RuntimeError(f"request failed: {http_status}, requestId={envelope.get('requestId')}")
methods = envelope["data"]
Inject credentials through deployment secret management or secure local configuration. Never put them in a webpage, app package, Git, or logs. Do not send AppSecret to a browser for direct signing.
5. API reference
5.1 Endpoint overview
| Method | Path | Scope / store action | Purpose |
|---|---|---|---|
| GET | /open/pay/v1/stores/{storeRef}/pay-methods |
pay:read / READ | Available store payment methods |
| POST | /open/pay/v1/orders |
pay:create / COLLECT | Create payment order |
| GET | /open/pay/v1/orders?outOrderNo=... |
pay:read / READ | Query by your order number |
| GET | /open/pay/v1/orders/{payOrderNo} |
pay:read / READ | Query by Near Pay payment number |
| POST | /open/pay/v1/orders/{payOrderNo}/pay |
pay:create / COLLECT | Select method and initiate payment |
| POST | /open/pay/v1/orders/{payOrderNo}/close |
pay:create / COLLECT | Close incomplete payment |
| POST | /open/pay/v1/orders/{payOrderNo}/refunds |
pay:refund / REFUND | Request refund |
| GET | /open/pay/v1/refunds/{payRefundNo} |
pay:read / READ | Query refund |
Encode each path parameter as a single URI path segment. The platform verifies application and original-order ownership; knowing another party's payment number does not grant access.
5.2 Get available store payment methods
GET /open/pay/v1/stores/{storeRef}/pay-methods
| Parameter | Location | Required | Description |
|---|---|---|---|
| storeRef | path | Yes | Authorized store number |
| market | query | No | Usually omitted; defaults to the store's operating market |
No body. data is an array. An empty array means no methods are currently available; do not proceed with a hardcoded list.
{
"code": 0,
"message": "OK",
"data": [{"payMethod": "LINEPAY", "payChannel": "NEWEBPAY", "accessMode": "MERCHANT_OWN"}],
"requestId": "REQ-DEMO-001"
}
This example describes the shape, not channel availability. Use payMethod to initiate payment. payChannel/accessMode support display or the corresponding client integration; they do not let you specify/change a collection account.
5.3 Create payment order
POST /open/pay/v1/orders
| Field | JSON type | Required | Description |
|---|---|---|---|
| outOrderNo | string | Yes | Your stable order number, 1–64 characters; persist before calling |
| storeRef | string | Yes | Store with COLLECT authorization |
| amountMinor | integer | Yes | Positive integer in smallest currency units |
| currency | string | Yes | Matches store currency, e.g. TWD |
| subject | string | Yes | Nonempty goods/order description without sensitive identity data |
| expireMinutes | integer | No | 1–1440, default 30; affects order validity only |
| bizNo | string | No | Business reference; defaults to outOrderNo; not a substitute idempotency number |
| payer | object | No | Optional phone/email/name; P3-encrypt supplied fields individually |
{
"outOrderNo": "DEV202611120001",
"storeRef": "STORE-DEMO-001",
"amountMinor": 12000,
"currency": "TWD",
"subject": "示例商品",
"expireMinutes": 30
}
The endpoint does not accept per-order notifyUrl/returnUrl, channel keys, or collection-account selection. Notification addresses come from registered configuration. The platform determines the channel and collection route.
Successful data is a payment order:
{
"payOrderNo": "P-DEMO-001",
"outOrderNo": "DEV202611120001",
"status": "CREATED",
"amountMinor": 12000,
"paidMinor": 0,
"refundedMinor": 0,
"currency": "TWD",
"market": "TW",
"payChannel": null,
"payMethod": null,
"expireAt": 1794443400000,
"succeededAt": null,
"closedAt": null,
"checkoutUrl": null,
"payer": null
}
This is only data; the HTTP response retains the common envelope. Save the payOrderNo ↔ outOrderNo relationship.
| Response field | Type | Meaning |
|---|---|---|
| payOrderNo / outOrderNo | string | Platform payment number / your order number |
| status | string | Payment state; section 6 |
| amountMinor / paidMinor / refundedMinor | integer | Due / collected / refunded amount |
| currency / market | string | Currency / operating market |
| payChannel / payMethod | string or null | Selected channel/method; may be empty at creation |
| expireAt / succeededAt / closedAt | integer or null | UTC milliseconds; null before the event |
| checkoutUrl | string or null | Returned at creation only when hosted checkout is configured; null for API-only integrations |
| payer | object or null | Masked payer fields, neither plaintext nor ciphertext |
Choose a checkout approach:
- If
checkoutUrlis present, use hosted checkout for the customer. It contains a short-lived token; treat it as a sensitive short link. - For your own frontend, your server calls section 5.5 and passes the returned parameters to the integrated channel page/SDK.
Creation idempotency: within the same application, identical outOrderNo and content return the original order; conflicting core content produces a conflict. Repeated creation may issue a new short-lived checkout token without creating a new order. Queries neither recover the original checkoutUrl nor extend validity.
5.4 Query payment order
By Near Pay number: GET /open/pay/v1/orders/{payOrderNo}.
By your order number: GET /open/pay/v1/orders?outOrderNo=DEV202611120001.
Both have no body. Successful data matches section 5.3 with checkoutUrl=null. Prefer the saved payOrderNo. Merchant isolation within one application can make a business number ambiguous; lookup by outOrderNo returns not found when no unique visible result exists. Do not create another transaction on that basis.
If creation timed out before you obtained payOrderNo, query the original outOrderNo first. If still not found, retry creation with the same number and parameters. Do not change the number to bypass a conflict.
The endpoint does not promise a real-time channel query on every call. For uncertain states, wait for notifications, query at the agreed cadence, or contact the platform for reconciliation.
5.5 Initiate payment
POST /open/pay/v1/orders/{payOrderNo}/pay
| Field | JSON type | Required | Description |
|---|---|---|---|
| payMethod | string | Yes | From the store's current available list and suitable for the client integration |
| payerOpenId | string | Conditional | E.g. a WeChat JSAPI payer identifier from your legitimate user authorization flow |
| payerAppId | string | Conditional | Matches the payer and channel application; follow platform integration requirements |
{"payMethod": "LINEPAY"}
Successful data:
{
"payOrderNo": "P-DEMO-001",
"outTradeNo": "TX-DEMO-001",
"payChannel": "NEWEBPAY",
"payParams": {}
}
payParams is a channel-specific string map determined by the enabled method. The empty object illustrates the type, not a usable payment result. Follow the channel instructions. Do not assume a url field always exists or inject arbitrary strings into HTML.
This endpoint does not accept card numbers, track data, POS card data, or mobile payment codes as generic fields. POS capabilities use their own integration contract.
An order may have multiple transaction attempts. After an initiation timeout, query the current order first. /pay is not an idempotent retry endpoint callable at any time; do not immediately switch methods and charge again. The original order state and platform rules determine whether another attempt is allowed.
5.6 Close payment order
POST /open/pay/v1/orders/{payOrderNo}/close
Omit the body, or send:
{"reason": "顾客取消"}
Returns a payment order. The platform first checks channel status. If already paid, it preserves/advances the actual payment result. An uncertain channel result may also return the current state. Mark the order closed only when the actual returned state confirms closure; HTTP 200 does not guarantee CLOSED. Reverse an already paid transaction through refund capabilities.
5.7 Request refund
POST /open/pay/v1/orders/{payOrderNo}/refunds
| Field | JSON type | Required | Description |
|---|---|---|---|
| outRefundNo | string | Yes | Your stable refund number, 1–64 characters; a different number for each refund request |
| amountMinor | integer | Yes | Positive integer within the refundable amount, application limits, and channel capabilities |
| reason | string | No | Refund reason |
| refundAccount | object | Conditional/optional | Only when explicitly enabled and required by the platform; P3-encrypt fields; does not change the original refund route |
{"outRefundNo": "REF202611120001", "amountMinor": 2000, "reason": "部分退货"}
Successful data:
{
"payRefundNo": "R-DEMO-001",
"outRefundNo": "REF202611120001",
"status": "PENDING_REVIEW",
"amountMinor": 2000,
"currency": "TWD",
"succeededAt": null,
"refundAccount": null
}
| Response field | Type | Meaning |
|---|---|---|
| payRefundNo / outRefundNo | string | Platform refund number / your refund number |
| status | string | Refund state; section 6 |
| amountMinor / currency | integer / string | This refund's amount / original currency |
| succeededAt | integer or null | Refund-success time in UTC milliseconds |
| refundAccount | object or null | Masked account, neither plaintext nor ciphertext |
Pending review or execution does not mean completed. Requests may require one- or two-person review; integrators neither need nor have permission to call operations approval endpoints.
Within one application, outRefundNo cannot be reused for a different original payment or amount. Preserve the original parameters. A new partial refund requires a new outRefundNo. Changing reasons/account details is not a way to modify an accepted refund.
Daily refund limits currently use UTC calendar days. A limit of zero disables refunds. The platform determines counted usage; an in-progress refund does not imply released capacity. Limit checks may occur before replay recognition, so retrying an accepted request whose response was lost can still be rejected by current limits/states. Contact the platform using original identifiers; do not change the refund number and duplicate the refund.
5.8 Query refund
GET /open/pay/v1/refunds/{payRefundNo}, no body.
Returns the section 5.7 refund object. There is currently no separate open endpoint to query by outRefundNo. If the first response was lost, business conditions permitting, retry the original outRefundNo/payment number and identical parameters to recover the platform number. If recovery still fails, submit those identifiers to the platform. Once payRefundNo is known, query it instead of requesting again.
6. States and recovery
6.1 Payment states
| State | Business handling |
|---|---|
| CREATED | Order created; collection unconfirmed |
| AWAITING_PAYMENT | Awaiting payment/result; wait or query |
| AUTHORIZED / AWAITING_CONFIRM | Authorization/confirmation in progress; not final collection success |
| UNKNOWN or unrecognized | Reconcile; retain original order; do not charge again or fulfill |
| SUCCEEDED | Confirmed paid; validate ownership, amount, currency before business processing |
| PARTIALLY_REFUNDED | Partial refund after payment; reconcile cumulative refunded amount |
| REFUNDED | Fully refunded after payment; do not trigger fulfillment as a new payment success |
| CLOSED / FAILED | Current transaction closed/failed; query original order and contact platform on conflicting notifications |
6.2 Refund states
| State | Business handling |
|---|---|
| REQUESTED / PENDING_REVIEW / PENDING_SECOND_REVIEW | Requested/awaiting review, not successful yet |
| APPROVED | Approved, but completion is unconfirmed |
| DISPATCHED | Dispatched to channel; awaiting result |
| OFFLINE_PENDING_PROOF | Awaiting proof/processing; meaningful only for explicitly supported scenarios |
| UNKNOWN or unrecognized | Reconcile; do not refund twice |
| SUCCEEDED | This refund succeeded |
| FAILED / REJECTED | Current refund failed/rejected; retain record and reconcile the cause |
6.3 Timeouts and idempotency
| Scenario | Correct recovery |
|---|---|
| Create timeout | Query original outOrderNo; if needed, recreate with the same number/parameters |
| Initiate timeout | Query original payOrderNo; await notification; do not blindly repeat pay or change orders |
| Close timeout | Query original payOrderNo; follow actual state |
| Refund-request timeout | Query known payRefundNo; if unknown, recover with original number or contact platform |
| Duplicate notification | Deduplicate eventId; do not repeat fulfillment/refund |
| Late/conflicting notification | Query original order; never overwrite current business state with an older event |
| 429 rate limit | Back off with jitter; re-sign with new nonce while retaining business number |
| 5xx/disconnection | Outcome is uncertain; query business result before deciding if retry is safe |
Business idempotency primarily uses outOrderNo/outRefundNo, not a self-invented Idempotency-Key header. Do not configure indiscriminate automatic retries for every POST.
6.4 Server-side workflow example
Reuse client from section 4. Persist the local order and stable outOrderNo first; read platform numbers from actual responses rather than placeholders. Recover timeouts under section 6.3 instead of wrapping this example in unlimited retries.
# 1. Persisted local order. Never regenerate outOrderNo for a network retry.
order_request = {
"outOrderNo": local_order_no,
"storeRef": os.environ["NEARPAY_STORE_REF"],
"amountMinor": 12000,
"currency": "TWD", # Use the currency confirmed by the platform for this store.
"subject": "示例商品",
}
http_status, response = client.call("POST", "/open/pay/v1/orders", order_request)
if http_status != 200 or response["code"] != 0:
raise RuntimeError(f"create failed, requestId={response.get('requestId')}")
order = response["data"]
pay_order_no = order["payOrderNo"]
# Persist the relationship between pay_order_no and the local order.
# 2. Hosted checkout uses order.get("checkoutUrl").
# Only custom checkout calls /pay from the server; do not start both flows.
selected_method = selected_from_available_methods
http_status, started = client.call(
"POST", f"/open/pay/v1/orders/{pay_order_no}/pay",
{"payMethod": selected_method},
)
# Check code, save the transaction number, then pass payParams to the integrated frontend.
# Do not fulfill yet; wait for verified notifications or query results.
# 3. Query the original order; validate amount/currency/ownership before updating local state.
http_status, queried = client.call("GET", f"/open/pay/v1/orders/{pay_order_no}")
# 4. A separate after-sales action triggers refunds. Persist a stable refund number first.
# http_status, refunded = client.call(
# "POST", f"/open/pay/v1/orders/{pay_order_no}/refunds",
# {"outRefundNo": local_refund_no, "amountMinor": 2000, "reason": "部分退货"},
# )
local_order_no/selected_from_available_methods/local_refund_no come from your business state, not automatic generation by the example library. Methods needing payerOpenId/payerAppId also require the legitimate payer context described in section 5.5.
7. Asynchronous notifications
7.1 Endpoint and request headers
The platform sends HTTPS POST to the application's registered notification URL. Configure it at application level, not per order.
Headers include X-App-Id/X-Timestamp/X-Nonce/X-Signature/X-Event-Id, plus X-Key-Serial for versioned signing. Verify using P2. The header nonce is for signing; resource.nonce is for AES encryption. Do not confuse them.
7.2 Notification envelope
{
"eventId": "EVT-DEMO-001",
"eventType": "PAYMENT_SUCCEEDED",
"stateVersion": 2,
"createdAt": 1794441601000,
"resource": {
"algorithm": "AEAD_AES_256_GCM",
"keySerial": "ENC-SERIAL-DEMO",
"nonce": "<Base64编码的12字节随机值>",
"associatedData": "PAYMENT_SUCCEEDED|EVT-DEMO-001",
"ciphertext": "<Base64编码的密文与Tag>"
}
}
Encrypted fields above are placeholders, not decryption test data. Use the downloadable vectors for runnable examples.
| Field | Description |
|---|---|
| eventId | Stable across retries; opaque format; do not parse its internal structure |
| eventType | Current event enums below |
| stateVersion | State-version information for event content, not a global sequence or ordering across events |
| createdAt | Event creation UTC milliseconds, not each delivery time |
| resource | P4-encrypted business data |
| data | May appear only in an explicitly enabled transitional mode without EncryptKey; still requires P2 verification |
Current events:
| eventType | Meaning |
|---|---|
| PAYMENT_SUCCEEDED | Payment succeeded |
| PAYMENT_CLOSED | Payment closed |
| REFUND_SUCCEEDED | Refund succeeded |
| REFUND_FAILED | Refund failed |
Example decrypted payment object:
{
"payOrderNo": "P-DEMO-001",
"outOrderNo": "DEV202611120001",
"status": "SUCCEEDED",
"amountMinor": 12000,
"paidMinor": 12000,
"refundedMinor": 0,
"currency": "TWD",
"payChannel": "NEWEBPAY",
"payMethod": "LINEPAY",
"succeededAt": 1794441600000,
"closedAt": null
}
Refund events include the same original payment fields and add payRefundNo/outRefundNo/refundAmountMinor/refundStatus. Top-level business status/amountMinor describe the original payment. Read refundStatus/refundAmountMinor for this refund's outcome/amount.
7.3 Receiving and processing
- Preserve raw body before parsing/rewriting JSON. Find the key by AppId/signing serial, check timestamp window, and verify P2.
- Compare
X-Event-Idto body.eventId and confirm X-App-Id belongs to an application your service accepts. Retain unknown event types without executing unknown actions. - Decrypt resource with the matching EncryptKey version and verify AAD. If encryption is required but only data arrives, treat it as an error rather than downgrading.
- Persist receipt with a unique key on
AppId + eventId. Update local business state or save a reliable processing task in the same transaction. Acknowledge duplicates already received. - Verify original payment/refund ownership, currency, amount. Reconcile amount mismatches, conflicting states, or uncertain outcomes before fulfillment.
- After successful persistence, quickly return 2xx, e.g. HTTP 200 and
{"received":true}. No fixed response string or ACK signature is required. - Return non-2xx on persistence failure so the platform retries. Use your own reliable tasks for slow processing; do not ACK first and then retain work only in memory.
HTTP nonce is not the business deduplication key. Nonce/signature/encryption IV can change on each redelivery while eventId stays the same.
7.4 Redelivery and reconciliation
Default delivery timeout is five seconds. Failed deliveries retry with exponential backoff, initially 30 seconds and capped at two hours, moving to manual handling after roughly 24 hours. Scheduling and configuration affect actual timing. Formal commitments come from provisioned integration information; do not derive precise attempt counts or an SLA from these defaults.
Out-of-order, duplicate, and delayed events are possible. stateVersion is not a counter incremented for every notification. Do not use it alone to filter different payment/refund events on one order. Deduplicate each eventId and validate business state/cumulative amounts. Recover missing notifications through original-order queries and platform reconciliation.
8. Key rotation and application maintenance
- Request new key versions and securely receive plaintext/serials. Add them to server-side version lookup before deleting any old version.
- The platform verifies/activates the new version and confirms the overlap window.
- New requests use the new
X-Key-Serial/AppSecret. Select EncryptKey andX-Encrypt-Serialseparately for sensitive fields. - Verify responses and notifications using the actual serial, not always the latest key. Historical redeliveries may retain signing/encryption versions frozen at first delivery.
- Retain old versions until both sides confirm the historical delivery/retry window has ended, then retire them under the platform's instructions. Do not independently extend revoked-key validity.
Application suspension/revocation, withdrawn store authorization, or disabled keys can affect calls. On a leak, contact the platform immediately and retain affected business identifiers; deleting local configuration alone is insufficient. Production/sandbox keys cannot be shared or rotated into each other's environments.
9. Errors and troubleshooting
| HTTP / code | Meaning | Recommended handling |
|---|---|---|
| 401 / 10401 | AppId/state/environment/signature/key authentication failure | Check environment, prefix removal, actual rawBody, path, key activation |
| 401 / 70095 | Timestamp expired | Synchronize time; use UTC milliseconds, not seconds |
| 401 / 70096 | Nonce reused | New nonce/timestamp/signature, same business number |
| 403 / 10403 or 70082 | IP/scope/store/resource permission failure | Check egress IP and application/store action intersection; do not repeatedly probe other resources |
| 400 / 70097 | Sensitive field not encrypted as required | Check plaintext fields and P3 packing |
| 400 / 70098 | Sensitive field decryption failed | Check EncryptKey, serial, IV, Tag, full-field AAD |
| 503 / 70099 | Key service temporarily unavailable | Back off and reconcile original business result first |
| 429 / 10429 | Application rate limit | Reduce concurrency, back off with jitter; do not assume Retry-After |
| Nonzero / 70083 | Original order absent, invisible, or not uniquely identifiable | Check AppId, original number, ownership; do not immediately charge again |
| Nonzero / 70084 | Business number conflict | Check changed original payment/amount/content; restore original parameters |
| Nonzero / 70085 | Action not allowed in current state | Query and follow actual state |
| Nonzero / 70086 | Refund exceeds available amount | Reconcile completed/in-progress refunds; do not resubmit |
| Nonzero / 70092 | Application refund limit exceeded | Check accepted refunds and UTC daily limit; contact platform if needed |
Actual responses determine business-error HTTP mappings. Do not determine transaction results from HTTP status alone. Production authentication failures may combine causes. For troubleshooting, provide environment, AppId, requestId, method/path, time, and outOrderNo/payOrderNo or outRefundNo/payRefundNo, never AppSecret, EncryptKey, or sensitive plaintext.
Common issues:
- Signatures never match: check AppSecret prefix inclusion, extra Base64 key decoding, body reserialization after signing, or P1 used to verify P2 responses.
- Collect scope but still 403: check store COLLECT authorization, application/store validity, and egress IP.
- HTTP 200 but customer has not paid: it indicates API handling; confirm payment through queries/notifications.
- Refund accepted but funds not returned: APPROVED/DISPATCHED are not SUCCEEDED; review or channel processing may be pending.
- Query has no checkoutUrl: expected; only creation with hosted checkout configured returns a short-lived URL.
- Notification signature passes but decryption fails: signing key and EncryptKey are independent. Check resource.keySerial and retain old encryption versions for redeliveries.
10. Production acceptance checklist
- Sandbox/production details are separate; AppId, keys, store number, currency confirmed.
- Application and signing/encryption keys are active; required actions and store authorization are effective.
- Notification HTTPS/domain/platform verification complete; receiver does not depend on browser sessions.
- P1/P2/P3/P4 offline vectors pass; modified bodies, wrong keys/AAD, expired messages are rejected.
- Creation, identical-number retries, and conflicting content with the same number tested.
- Enabled payment methods genuinely integrated; success, cancellation, unknown outcomes handled.
- Payment/refund timeouts recover original numbers; no indiscriminate POST retries or new-number duplicate charges.
- Refund limits, partial-refund capabilities, review process confirmed; actual success requires SUCCEEDED.
- Notifications verify/decrypt, persist reliably, ACK duplicates; old-key redelivery, reordering, state conflicts recoverable.
- Closing reads the actual returned state rather than treating HTTP 200 as CLOSED.
- Key rotation, egress IP/notification changes, incident contact process confirmed.
Completing development does not enable every channel. Production rollout depends on platform acceptance for the particular application, store, and payment method.