# Bayarcash API文档和sandbox

> Bayarcash API v3入门：sandbox和正式环境的base URL、怎样在request附上PAT，以及API错误的意思。
>
> Source: https://docs.bayarcash.com/zh/developers/

Bayarcash API让你自己的网站或App创建付款、查询交易，以及管理FPX Direct Debit的授权（mandate）。所有新的开发都请使用**API v3**。完整的参考文档在[api-reference.bayarcash.com](https://api-reference.bayarcash.com)。

## 使用哪个API版本

Bayarcash有两个API版本：

| 版本 | 状态 | 什么时候使用 |
|---|---|---|
| v3 | 当前版本 | 所有新的集成。新功能（在你自己的页面上使用DuitNow QR、idempotency、付款人身份验证、交易搜索）只有v3才有。 |
| v2 | 已停用（deprecated） | 只在你已经在用它时使用。它不会再有新功能。请计划迁移到v3。 |

## Sandbox和正式环境

先在sandbox开发和测试。在sandbox里不会产生真实交易。这两个环境是分开的：每个环境都有自己的商家后台（merchant dashboard）、自己的账号和自己的key。

| 环境 | API base URL | 商家后台 |
|---|---|---|
| Sandbox | `https://api.console.bayarcash-sandbox.com/v3` | [console.bayarcash-sandbox.com](https://console.bayarcash-sandbox.com) |
| 正式环境（production） | `https://api.console.bayar.cash/v3` | [console.bayar.cash](https://console.bayar.cash) |

正式上线时，把base URL改为正式环境的，并换上你的正式key。一个环境的key永远不能在另一个环境使用。

要在sandbox测试：

1. 登录[sandbox商家后台](https://console.bayarcash-sandbox.com)，复制它的Personal Access Token、Portal Key和API Secret Key。见[找到你的API key](/zh/api-keys/)。
2. 把你的request发送到sandbox base URL。在SDK中，调用sandbox选项，例如`useSandbox()`（见[选择Bayarcash SDK](/zh/sdks/)）。在插件中，勾选它的sandbox设置，例如[WooCommerce](/zh/woocommerce/#在sandbox测试)中的**Sandbox Mode**。
3. 创建一笔付款，然后付款。不会产生真实交易。
4. 测试成功后，改用正式环境的base URL和你的正式key。

如果只想快速测试，可以使用共享的sandbox账号。它的登录页面上就有显示：

- **Email:** `sandbox@bayarcash.com`
- **Password:** `sandbox@bayarcash.com`

其他开发者也使用同一个账号，而且Bayarcash每天午夜12:00会重设这个账号的所有资料。如果要自己的sandbox账号，请在[sandbox登录页面](https://console.bayarcash-sandbox.com/login)选择**Register**。

## 你需要什么

每个v3集成都会用到商家后台里的这些项目：

| 项目 | 作用 |
|---|---|
| Personal Access Token（PAT） | 在每个API request中证明你的身份。 |
| Portal key | 指定由你的哪个portal接收付款。 |
| API Secret Key | 用checksum签署request和验证callback。它本身从不单独发送。 |

token和secret key只能保存在你的服务器上。绝对不要把它们放在手机App、浏览器JavaScript或公开的repository里。

## 为每个request进行身份验证

在每个request的`Authorization` header中，把你的Personal Access Token作为bearer token发送：

```http
Authorization: Bearer <your Personal Access Token>
Accept: application/json
```

例如，要检查你的token是否有效，可以在sandbox列出你的portal：

```bash
curl https://api.console.bayarcash-sandbox.com/v3/portals \
  -H "Authorization: Bearer $BAYARCASH_PAT" \
  -H "Accept: application/json"
```

## 付款怎样进行

通过API的一般付款流程如下：

1. 你的服务器用portal key、订单号码、金额、付款人姓名和电邮，以及你的`callback_url`和`return_url`，创建一个**payment intent**。
2. Bayarcash回复一个`url`。把你的顾客重定向到那里付款。
3. 付款到达最终状态时，Bayarcash会从服务器到服务器，向你的`callback_url`发送**callback**。验证它的checksum，然后更新订单。
4. Bayarcash把顾客送回你的`return_url`，向他们显示结果。

应该信任的是callback。见[验证callback和checksum](/zh/callbacks-and-checksum/)。

## API错误

API会以HTTP状态码回复。以下是[API参考文档](https://api-reference.bayarcash.com)中的状态码：

| 状态码 | 意思 | 怎么做 |
|---|---|---|
| 403 | 这个项目不允许这个request，例如已付款的payment intent，或无法执行这个操作的渠道 | 先检查这个项目的状态。阅读response中的`message` |
| 404 | 找不到这个项目 | 检查ID，并确认你使用的环境（sandbox或正式环境）和这个项目相同 |
| 409 | 使用相同`Idempotency-Key`的request仍在处理中 | 稍等，然后再发送一次request |
| 422 | 某个field无效、项目状态不对，或同一个`Idempotency-Key`被用于不同的field | 阅读response中的`errors`，然后修正request |
| 429 | request太多 | 等待`Retry-After` header中的时间，然后再发送 |
| 500 | Bayarcash无法处理这个request（“Error processing request.”） | 见下文 |

如果你收到**HTTP 500**：

1. 不要马上再创建付款。先检查第一个request是否已经创建了payment intent或交易。
2. 如果第一个request带有`Idempotency-Key`，就用同一个key再发送一次。这样Bayarcash不会创建第二笔付款。
3. 如果错误持续，请联系Bayarcash。提供endpoint、request的时间和response body。绝对不要发送你的Personal Access Token或API Secret Key。

## 小贴士

- **如果你的编程语言有SDK，就使用SDK**。它会替你处理base URL、bearer token、checksum和callback验证。见[选择Bayarcash SDK](/zh/sdks/)。
- **创建payment intent时，发送`Idempotency-Key` header**。如果request超时，你可以用同一个key再发送一次，不会创建第二笔付款。key在24小时后过期。
- **保存每个交易ID，并在根据callback处理订单前先检查它**。同一个callback可能不止到达一次，这样可以避免同一个订单被处理两次。

## 常见问题

### 我的token在正式环境可以用，但sandbox说它无效。为什么？

Sandbox和正式环境各自发出不同的token。正式环境的Personal Access Token不能用在sandbox API，sandbox的token也不能用在正式环境。请从各自的商家后台获取每个token。

### 我还应该用API v2吗？

不用。API v2已停用（deprecated），不会再有新功能。所有新的集成都请用v3。大多数SDK默认仍是v2，所以请把它们切换到v3（见选择Bayarcash SDK (/zh/sdks/)）。

### 哪里可以找到完整的endpoint和field列表？

在API参考文档api-reference.bayarcash.com (https://api-reference.bayarcash.com)。这个Help Centre解释概念，参考文档则列出每个endpoint、field和response。