# 支付回调 API

> Shoplazza 支付应用回传支付与退款结果的回调 API：完成支付、异步通知的请求参数与响应说明。

支付回调 API 允许支付服务商将支付和退款状态更新到 Shoplazza。

支付应用会使用两类回调：

* **完成支付**：同步回调，用于顾客完成跳转支付、iframe 支付，或完成需要 3DS 验证的信用卡直接支付后。Shoplazza 会返回一个跳转 URL，将顾客带到支付完成页。
* **支付和退款通知**：异步回调，用于向 Shoplazza 通知支付和退款的最终结果。

如果 Shoplazza 没有收到成功响应，支付应用必须按照重试策略重试请求。

## 完成支付

需要 `write_payment_info` 访问权限。

当顾客在第三方页面完成支付，或完成 3DS 验证后，使用 Complete Payment API。此阶段不需要返回最终支付结果，目的是继续顾客侧支付流程。

### 请求头

| Header | 说明 |
| --- | --- |
| `Access-Token` | 鉴权后返回的 OAuth 授权 token。 |
| `Shoplazza-Shop-Domain` | 店铺的 Shoplazza 系统域名。 |
| `Shoplazza-Hmac-Sha256` | 按签名方法计算得到的签名。 |
| `Content-Type` | 固定为 `application/json`。 |

### 请求参数

| Key | 是否必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `app_id` | 是 | string | 支付应用 ID。 |
| `payment_id` | 是 | string | 支付 ID。 |
| `amount` | 是 | number | 订单金额。 |
| `currency` | 是 | string | 币种代码。 |
| `transaction_no` | 是 | string | 第三方支付交易号。 |
| `type` | 是 | string | 支付类型，例如 `sale` 或 `authorization`。 |
| `test` | 是 | boolean | 请求是否为测试模式。 |
| `status` | 是 | string | 支付状态，固定为 `paying`。 |
| `extension` | 否 | object | 自定义扩展字段。 |
| `timestamp` | 是 | string | ISO 8601 时间戳。 |

### 成功响应

```json
{
  "redirect_url": "https://developer.myshoplaza.com/checkout/12345"
}
```

## 支付和退款通知

需要 `write_payment_info` 访问权限。

使用通知回调异步通知 Shoplazza 最终支付或退款结果。支付和退款共享相同请求格式，仅 `type` 和 `status` 取值不同。

### 请求头

| Header | 说明 |
| --- | --- |
| `Access-Token` | 鉴权后返回的 OAuth 授权 token。 |
| `Shoplazza-Shop-Domain` | 店铺的 Shoplazza 系统域名。 |
| `Shoplazza-Hmac-Sha256` | 按签名方法计算得到的签名。 |
| `Content-Type` | 固定为 `application/json`。 |

### 请求参数

| Key | 是否必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `app_id` | 是 | string | 支付应用 ID。 |
| `payment_id` | 是 | string | 支付 ID。 |
| `amount` | 是 | number | 支付或退款金额。 |
| `currency` | 是 | string | 币种代码。 |
| `status` | 是 | string | 支付状态（`paid`、`failed`）或退款状态（`refund_success`、`refund_failed`）。 |
| `transaction_no` | 是 | string | 第三方支付交易号。 |
| `type` | 是 | string | 支付通知使用 `sale`，退款通知使用 `refund`。 |
| `message` | 否 | string | 失败信息，交易失败时必填。 |
| `error_code` | 条件必填 | string | 错误码，`status` 为 `failed` 时必填。 |
| `test` | 是 | boolean | 请求是否为测试模式。 |
| `extension` | 否 | object | 自定义扩展字段。 |
| `timestamp` | 是 | string | ISO 8601 时间戳。 |

### 成功响应

Shoplazza 收到通知后返回 HTTP `200`。

```json
{}
```