虚拟账户 · PGSwift Docs

为特定交易或客户生成的临时唯一银行账号，用于便捷付款。

POST /api/create/va

请求

名称	类型	必填	输入校验	描述
merchant_transaction_id	string	true		商户提供的唯一交易标识符
amount	string	true	数字类型，1–12 位	交易金额的数值表示
currency	string	true	可接受的数值： `"IDR"`	交易使用的货币，仅支持印尼卢比（IDR）
bank_code	string	true	可接受的数值：见下方表格	交易使用的银行代码。
customer_name	string	true	长度在 5–25 个字符之间，允许字符：a–z、A–Z、0–9、-（短横线）、（空格）	与该交易关联的客户姓名
product_name	string	true	长度在 5–25 个字符之间，允许字符：a–z、A–Z、0–9、-（短横线）、（空格）	与该交易关联的产品名称
description	string	false		可选的交易补充信息
success_redirect_url	string	false		付款成功后重定向客户的 URL。也支持移动端深度链接 (Deep Link) URL。

支持的 bank_code 值

bank_code	数字代码	银行
BCA	014	Bank Central Asia
BRI	002	Bank Rakyat Indonesia
BNI	009	Bank Negara Indonesia
MDR	008	Bank Mandiri
PRMT	013	Bank Permata
CIMB	022	CIMB Niaga
BNC	490	Bank Neo Commerce
BDM	011	Bank Danamon
BSI	451	Bank Syariah Indonesia
MUA	147	Bank Muamalat
SNM	153	Bank Sinarmas
OCBC	028	Bank OCBC
FINPAY	—	Finpay
NOBU	503	Bank Nationalnobu
INA	513	Bank Ina Perdana
CIMBS	—	CIMB Niaga Syariah

每家银行既可使用字母代码，也可使用数字代码，两者对应同一渠道；响应和 Webhook 中始终返回字母代码。CIMBS 和 FINPAY 仅接受字母代码。

{
    "merchant_transaction_id": "ICZ10000001",
    "amount": "100000",
    "currency": "IDR",
    "bank_code": "BRI",
    "description": "Lorem Ipsum",
    "customer_name": "John Doe",
    "product_name": "Product Test",
    "success_redirect_url": "https://example.com/success"
}

响应

名称	描述
status	请求状态指示器。成功时为 true，失败时为 false。
message	请求结果消息。请求成功时通常为 "success"。
data.transaction_id	系统生成的唯一交易标识符。
data.va_number	生成的虚拟账户（VA）号码，供客户用于付款。如无虚拟账户号码，此字段可为空。
data.channel	虚拟账户使用的银行或支付渠道。
data.redirect_url	用户重定向链接（如适用）。如无重定向链接，此字段可为 null。
data.expired_at	支付过期时间，服务器时间（UTC+7，无偏移量），格式 `YYYY-MM-DD HH:MM:SS`（例如 `"2025-02-26 19:00:00"`）。如不适用则为 null。
data.expired_at_iso	与 `expired_at` 相同的过期时间，ISO 8601 格式并带偏移量（例如 `"2025-02-26T19:00:00+07:00"`）。所有渠道格式一致。`expired_at` 为 null 时为 null。
data.payment_channel	标准化支付渠道，所有支付类型和服务商使用同一格式：例如 `QRIS`、`VA_BRI`、`BANK_BCA`、`EWALLET_DANA`（支付类型前缀 + 附录中的代码）。无法确定渠道时为 null。建议优先使用此字段而非 `channel`。
data.success_redirect_url	付款成功后重定向客户的 URL。也支持移动端深度链接 (Deep Link) URL。

{
    "status": true,
    "message": "success",
    "data": {
        "transaction_id": "9e536777-2bfa-4161-9931-35f5c4b23faf",
        "payment_channel": "VA_MDR",
        "va_number": "8999817535253527",
        "channel": "MDR",
        "redirect_url": "{host}/checkout/9e536777-2bfa-4161-9931-35f5c4b23faf/va/MDR",
        "success_redirect_url": "https://example.com/success",
        "expired_at": "2025-02-26 19:00:00",
        "expired_at_iso": "2025-02-26T19:00:00+07:00"
    }
}

以下情况会返回 403 响应：

Unknown bank_code — bank_code 不在上方支持列表中。
VA payment for this bank is not configured. — 该银行受支持，但您的账户未开通该银行的虚拟账户。

{
    "status": false,
    "message": "string"
}

请求体校验失败。message 汇总错误信息，errors 按字段列出错误信息。

{
    "status": false,
    "message": "The amount field is required.",
    "errors": {
        "amount": ["The amount field is required."]
    }
}