nextapi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NextPay Partners API

Overview

概述

Use this as the broad integration skill for NextPay Partners API v2. Start with

references/README.md

for routing, then read the topic directory that matches the task, and use the live OpenAPI URL for exact current endpoints, schemas, enums, and parameter details.

将此作为NextPay Partners API v2的通用集成指南。首先查看

references/README.md

了解路由信息，然后阅读与任务匹配的主题目录，并使用实时OpenAPI URL获取当前准确的端点、模式、枚举和参数细节。

Freshness

时效性说明

Treat the markdown references as routing guides, not the source of truth for current wire shapes. Use

https://api.partners.nextpay.world/v2/openapi

when exact fields, enums, endpoint availability, or behavior matter.

将Markdown参考文档视为路由指引，而非当前接口数据结构的权威来源。当需要确切的字段、枚举、端点可用性或行为信息时，请使用

https://api.partners.nextpay.world/v2/openapi

。

Quick Decision Tree

快速决策树

text

Need merchant or account work?
└─ references/core/

Need to collect money?
└─ references/money-in/

Need to disburse money?
└─ references/money-out/

Need webhooks or event delivery?
└─ references/integration/

Need sandbox testing?
└─ references/sandbox/

Need exact wire shapes?
└─ `https://api.partners.nextpay.world/v2/openapi`

text

需要处理商户或账户相关工作？
└─ references/core/

需要收款？
└─ references/money-in/

需要付款？
└─ references/money-out/

需要处理Webhook或事件推送？
└─ references/integration/

需要沙箱测试？
└─ references/sandbox/

需要确切的接口数据结构？
└─ `https://api.partners.nextpay.world/v2/openapi`

Workflow

工作流程

Use
```
https://api.partners.nextpay.world
```
as the API base URL.
Use HTTP Basic Auth with the Client ID as the username and the Client Secret as the password.
Read
```
references/README.md
```
to choose the right resource family before writing code.
Read the matching topic directory under
```
references/
```
for the operational model and endpoint shortlist.
Read targeted sections of
```
https://api.partners.nextpay.world/v2/openapi
```
for exact request bodies, enums, headers, and response fields.
Explain
```
PHP/2
```
whenever it appears. Precision notation means the integer amount stores minor units, so
```
10000
```
means PHP 100.00.

使用
```
https://api.partners.nextpay.world
```
作为API基础URL。
使用HTTP Basic Auth认证，以Client ID作为用户名，Client Secret作为密码。
在编写代码前，先阅读
```
references/README.md
```
以选择合适的资源类别。
阅读
```
references/
```
下对应的主题目录，了解操作模型和端点列表。
查阅
```
https://api.partners.nextpay.world/v2/openapi
```
的目标章节，获取确切的请求体、枚举、请求头和响应字段信息。
当出现
```
PHP/2
```
时需注意：该精确表示法意味着整数金额存储的是最小货币单位，例如
```
10000
```
代表100.00菲律宾比索（PHP）。

Resource Selection

资源选择

Use merchants for legal-entity level onboarding and updates.
Use accounts for balances, postings, and account-to-account transfers.
Use funding methods for reusable receiving instruments.
Use payment intents for one-time collection flows tied to a payment instrument lifecycle.
Use payout requests to initiate disbursements. A payout request can fan out into multiple payouts when rail limits require splitting.
Use payouts to inspect the individual disbursement records created from a payout request.
Use webhooks to register event delivery endpoints and manage
```
active
```
or
```
inactive
```
status.
Use payment simulation only in test environments to exercise the real payment-processing and webhook paths without live provider traffic.

使用merchants资源进行法律实体层面的入驻和信息更新。
使用accounts资源处理余额、过账和账户间转账。
使用funding methods资源管理可重复使用的收款工具。
使用payment intents资源处理与支付工具生命周期绑定的一次性收款流程。
使用payout requests资源发起付款操作。当支付渠道存在限额需要拆分时，一个付款请求可以生成多个付款记录。
使用payouts资源查看由付款请求生成的单个付款记录。
使用webhooks资源注册事件推送端点，并管理其
```
active
```
（激活）或
```
inactive
```
（停用）状态。
仅在测试环境中使用payment simulation（支付模拟）功能，无需真实支付服务商流量即可测试完整的支付处理和Webhook流程。

Integration Notes

集成注意事项

Prefer idempotency keys on create endpoints that expose
```
X-Idempotency-Key
```
. Idempotency means a retry can avoid creating duplicate side effects.
Do not promise a payment-intent expiry webhook. The spec says expiry is represented by
```
expires_at
```
, so fetch the resource if confirmation is needed.
When event timing matters, read
```
references/integration/webhooks.md
```
.
```
v2.payment_instrument.payment_received
```
is the earliest positive payment signal,
```
v2.payment_instrument.payment_settled
```
is the stronger settlement signal, and
```
v2.payment_intent.succeeded
```
is the one-time business completion event.
Expect mixed error payloads. Rate limits often use Problem Details fields such as
```
type
```
,
```
title
```
,
```
status
```
,
```
detail
```
, and
```
code
```
, while some validation or not-found responses use simpler
```
error
```
and
```
code
```
fields.
Read the live OpenAPI event enum before hard-coding handlers, because the allowed values include both older event names and v2-specific event names.
Use sandbox payment simulation to test success, failure, and idempotent replay behavior. The simulation response can return
```
payment_processed
```
,
```
payment_failed
```
, or
```
already_processed
```
.

对于支持
```
X-Idempotency-Key
```
的创建类端点，建议使用幂等键。幂等性意味着重试请求不会产生重复的副作用。
不要承诺会提供payment-intent过期的Webhook。根据规范，过期信息由
```
expires_at
```
字段表示，若需确认请主动获取该资源信息。
当关注事件时序时，请阅读
```
references/integration/webhooks.md
```
。
```
v2.payment_instrument.payment_received
```
是最早的付款成功信号，
```
v2.payment_instrument.payment_settled
```
是更可靠的清算完成信号，而
```
v2.payment_intent.succeeded
```
是一次性的业务完成事件。
需注意错误响应格式可能不一致。速率限制相关错误通常使用Problem Details字段，如
```
type
```
、
```
title
```
、
```
status
```
、
```
detail
```
和
```
code
```
，而部分验证或资源不存在的响应则使用更简洁的
```
error
```
和
```
code
```
字段。
在硬编码事件处理程序前，请查阅实时OpenAPI的事件枚举值，因为允许的事件名称既包含旧版名称也包含v2专属名称。
使用沙箱支付模拟测试成功、失败和幂等重试行为。模拟响应可能返回
```
payment_processed
```
、
```
payment_failed
```
或
```
already_processed
```
。

Quick Start

快速开始

bash

curl -u "$NEXTPAY_CLIENT_ID:$NEXTPAY_CLIENT_SECRET" \
  https://api.partners.nextpay.world/v2/merchants

bash

curl -u "$NEXTPAY_CLIENT_ID:$NEXTPAY_CLIENT_SECRET" \
  https://api.partners.nextpay.world/v2/merchants

References

参考资料

Read
```
references/README.md
```
first for routing and domain differences.

Read

references/core/

references/money-in/

references/money-out/

references/integration/

, or

references/sandbox/

for topic-specific guidance.

Read
```
references/integration/webhooks.md
```
when webhook event meaning or timing matters.

Read

https://api.partners.nextpay.world/v2/openapi

for the live current contract.

首先阅读
```
references/README.md
```
了解路由和领域差异。

阅读

references/core/

、

references/money-in/

、

references/money-out/

、

references/integration/

或

references/sandbox/

获取特定主题的指导。

当需要了解Webhook事件含义或时序时，阅读
```
references/integration/webhooks.md
```
。

查阅

https://api.partners.nextpay.world/v2/openapi

获取当前的实时接口约定。