curl -X POST "${BASE_URL}/api/v2/trans/directPay" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "amount": "25.50",
  "merchant_order_no": "BB-20300101-001",
  "currency": "AUD",
  "trans_func": 3,
  "first_name": "Emily",
  "last_name": "Carter",
  "card": {
    "card_number": "4111111111111111",
    "expiration_month": "12",
    "expiration_year": "2030",
    "security_code": "123"
  },
  "notify_email": false,
  "notify_sms": false
}'

{
  "code": 0,
  "message": "ok",
  "data": {
    "business_id": "7294815",
    "merchant_id": "48290713",
    "order_number": "b1893452400000741",
    "merchant_order_no": "BB-20300101-001",
    "trans_func": 3,
    "complete_date": "01/01/2030 10:00:00",
    "currency": "AUD",
    "amount": "25.50",
    "html": "",
    "card_token": "",
    "status": 1,
    "code": 0,
    "remark": "Approved",
    "sign_type": "SHA256",
    "sign": "fc6d0b575bb56a05607a71a8b78fecae9ba07275626bde9d0afed3f959c3910b"
  }
}

交易

单笔直连支付

按交易操作选择参数

所有操作均须提供 trans_func、merchant_id、amount、merchant_order_no 和 currency；在此基础上按下表填写条件必填参数。已有客户模式也须遵守这些要求。

trans_func	操作	额外必填参数
1	创建 Token，不扣款	`card.card_number`、`card.expiration_month`、`card.expiration_year`、`card.security_code`、`first_name`、`last_name`
2	Token 支付	`card_token`、`first_name`、`last_name`
3	卡号支付	`card.card_number`、`card.expiration_month`、`card.expiration_year`、`card.security_code`、`first_name`、`last_name`
4	创建收银台	`return_url`
5	银行账户支付	`bank_account.bsb`、`bank_account.account_no`、`bank_account.account_name`；不得提供非空 `card`

is3ds=1 时还须提供 return_url。process_date 仅适用于操作 2、3、5，须严格晚于业务时区的今天，且不得与 is3ds=1 同用。各字段的类型、长度及取值范围见请求参数。

支持创建支付 Token、Token 支付、卡号支付、收银台及银行账户支付。is3ds=1 时不能预约；仅当响应 data.html 非空时，才须展示该 HTML 引导客户完成验证。html 为空时请按响应状态处理，勿假定一定出现验证页面。trans_func=5 时不得提交非空 card。预约日期须严格晚于服务业务时区的当天。data.sign 为响应签名，示例签名按各支付场景的签名规则，使用公开演示密钥 bb_docs_demo_signing_key_2030 离线计算；3DS 待验证响应的 html 不参与签名计算。示例签名不能用于实际交易。支付失败时顶层 code=1，data 不包含交易详情。

扣款被拒绝或 3DS 验证失败时，顶层 code=1，data=[]；错误原因见 message。此时不要按成功响应读取 data.status。

所有示例均为格式示例，客户、订单、卡及账户数据须替换为测试环境获准使用的数据。BASE_URL 为服务根域名，不附加 /api/v2；ACCESS_TOKEN 为 /oauth/token 返回的 access_token。日期示例为 2030 年，执行时请改为满足当前日期限制的实际日期。

POST

api

trans

directPay

curl -X POST "${BASE_URL}/api/v2/trans/directPay" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "amount": "25.50",
  "merchant_order_no": "BB-20300101-001",
  "currency": "AUD",
  "trans_func": 3,
  "first_name": "Emily",
  "last_name": "Carter",
  "card": {
    "card_number": "4111111111111111",
    "expiration_month": "12",
    "expiration_year": "2030",
    "security_code": "123"
  },
  "notify_email": false,
  "notify_sms": false
}'

{
  "code": 0,
  "message": "ok",
  "data": {
    "business_id": "7294815",
    "merchant_id": "48290713",
    "order_number": "b1893452400000741",
    "merchant_order_no": "BB-20300101-001",
    "trans_func": 3,
    "complete_date": "01/01/2030 10:00:00",
    "currency": "AUD",
    "amount": "25.50",
    "html": "",
    "card_token": "",
    "status": 1,
    "code": 0,
    "remark": "Approved",
    "sign_type": "SHA256",
    "sign": "fc6d0b575bb56a05607a71a8b78fecae9ba07275626bde9d0afed3f959c3910b"
  }
}

授权

Authorization

string

header

必填

OAuth2 client_credentials 授权。access_token 到期后重新获取。

请求体

application/json

支付请求。客户标识均不传为无客户模式；同时传 customer_id 和 external_customer_id 时以 customer_id 为准。卡支付只支持 Visa/Mastercard/Amex。金额、姓名、卡号等字段要求仍适用于已有客户；预约只允许 2/3/5。

trans_func

enum<integer>

必填

交易操作：1 建 Token（不扣款）；2 Token 支付；3 卡号支付；4 创建收银台会话；5 银行账户支付。

可用选项:

1,

2,

3,

4,

5

merchant_id

string

必填

业务标识，由 BillBuddy 分配。

Required string length: 1 - 20

amount

必填

支付金额。金额以主货币单位计，例如 10.50 表示 AUD 10.50，最多两位小数。接受数值或数字字符串，最小 0.01、最大 999999.99，两种类型遵守相同范围限制。

必填范围: 0.01 <= x <= 999999.99必须是以下数值的倍数 0.01

merchant_order_no

string

必填

商户订单号。同一商户范围内必须唯一；重复调用不会重新返回已有成功订单。

Required string length: 1 - 60

currency

string

必填

货币代码，如 AUD。支付服务能否处理该币种还取决于商户渠道配置。

Required string length: 3

card

object

信用卡信息。

Show child attributes

card_token

string | null

BillBuddy 返回的支付 Token。有客户时 Token 必须属于该客户。 trans_func=2 时必填。

Maximum string length: 255

first_name

string | null

名字。 trans_func 为 1/2/3 时必填。

Maximum string length: 50

last_name

string | null

姓氏。 trans_func 为 1/2/3 时必填。

Maximum string length: 50

string<email> | null

邮箱。

Maximum string length: 100

phone

string | null

联系电话。

Maximum string length: 50

address

string | null

地址。

Maximum string length: 100

city

string | null

城市。

Maximum string length: 50

state

string | null

州或省。

Maximum string length: 100

postcode

string | null

邮编。

Maximum string length: 4

country_iso2

string | null

国家两字母代码，如 AU。

Required string length: 2

is3ds

enum<integer> | null

默认值:0

是否使用 3DS。0 不启用，1 启用，省略按 0 处理。银行账户支付不执行 3DS。是否需要展示验证页面以响应 data.html 为准。

可用选项:

1,

0,

null

return_url

string | null

3DS 验证或收银台完成后的返回地址。 is3ds=1 或 trans_func=4 时必填。请提交有效返回地址，长度限制见 Schema。

Maximum string length: 255

customer_id

string | null

BillBuddy 客户标识，须为当前商户及业务范围内的有效客户。

Maximum string length: 32

external_customer_id

string | null

商户系统的客户引用编号；未传 customer_id 时用于查询客户。同时传两个标识时以 customer_id 为准。

Maximum string length: 64

notify_email

是否允许本交易或订阅相关邮件通知。false 表示禁止，true 表示允许；省略或 null 时使用该业务的 API 邮件通知设置，默认关闭。实际发送受通知偏好和适用规则约束。也兼容 0/1 和字符串 "0"/"1"。

notify_sms

是否允许本交易或订阅相关短信通知。false 表示禁止，true 表示允许；省略或 null 时使用该业务的 API 短信通知设置，默认关闭。实际发送受通知偏好和适用规则约束。也兼容 0/1 和字符串 "0"/"1"。

bank_account

object

银行账户信息。

Show child attributes

process_date

string<date> | null

预约处理日期，YYYY-MM-DD，必须严格晚于服务业务时区的当天；只支持 trans_func 2、3、5，且不能与 is3ds=1 一起使用。建议使用 YYYY-MM-DD。必须晚于服务业务时区的今天。

响应

HTTP 200。成功、业务失败、参数校验失败或业务鉴权失败以响应体 code 区分。

Option 1
Option 2

成功响应。

code

enum<integer>

必填

0 表示接口处理成功；建 Token、收银台、3DS 和 Pending 场景均不表示已完成扣款，请结合 data 判断。

可用选项:

0

message

string

必填

响应说明。

data

object

必填

按交易操作返回支付数据或收银台会话。

Option 1
Option 2

Show child attributes