Bayarcash API文档和sandbox

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

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

更新于 2026年10月21日

Bayarcash API让你自己的网站或App创建付款、查询交易，以及管理FPX Direct Debit的授权（mandate）。所有新的开发都请使用API v3。完整的参考文档在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
正式环境（production）	`https://api.console.bayar.cash/v3`	console.bayar.cash

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

要在sandbox测试：

登录sandbox商家后台，复制它的Personal Access Token、Portal Key和API Secret Key。见找到你的API key。
把你的request发送到sandbox base URL。在SDK中，调用sandbox选项，例如useSandbox()（见选择Bayarcash SDK）。在插件中，勾选它的sandbox设置，例如WooCommerce中的Sandbox Mode。
创建一笔付款，然后付款。不会产生真实交易。
测试成功后，改用正式环境的base URL和你的正式key。

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

Email: sandbox@bayarcash.com
Password: sandbox@bayarcash.com

其他开发者也使用同一个账号，而且Bayarcash每天午夜12:00会重设这个账号的所有资料。如果要自己的sandbox账号，请在sandbox登录页面选择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发送：

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

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

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

付款怎样进行

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

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

应该信任的是callback。见验证callback和checksum。

API错误

API会以HTTP状态码回复。以下是API参考文档中的状态码：

状态码	意思	怎么做
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：

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

小贴士

如果你的编程语言有SDK，就使用SDK。它会替你处理base URL、bearer token、checksum和callback验证。见选择Bayarcash SDK。
创建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）。

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

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

这篇文章对你有帮助吗？