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

了解路由规则，再阅读与任务匹配的主题目录，如需获取当前端点、schema、枚举值和参数的准确信息，请使用线上OpenAPI地址。

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

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`

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.

API基础URL使用
```
https://api.partners.nextpay.world
```
。
使用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
```
状态。
支付模拟仅可在测试环境使用，用于验证真实支付处理和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
```
是一次性业务完成事件。
注意会有多种格式的错误返回payload。限流通常会返回Problem Details格式的字段，如
```
type
```
、
```
title
```
、
```
status
```
、
```
detail
```
和
```
code
```
，而部分校验或404响应会使用更简单的
```
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

获取当前生效的接口契约。