Velora API

中文

English

中文

English

Appearance

创建交易（Create Payment） ​

商户调用本接口发起一笔支付（创建交易）。系统将根据金额、支付方式、国家/终端等路由到合适通道，并通过统一结构返回 result（返回码与说明）与 data（含 status，以及按需返回的 action 跳转信息或 amount 金额等）。

请求说明 ​

  • 方法：POST
  • 路径：/api/v1/payin/createPayment
  • Content-Type：application/json
  • 鉴权：参考 接入准备 中参数以及签名算法说明，按照要求携带必须的鉴权信息

一、请求字段（Request Body） ​

顶层字段 ​

字段名类型长度 / 限制必填说明
merchantOrderIdstring≤ 64 字符是商户订单号（商户维度唯一）
amountobject—是支付金额，见 amount
countrystring2 字符，ISO-3166是二位国家/地区代码，如 CN
transInitiatorobject—是发起交易的终端信息，见 transInitiator
paymentMethodobject—是支付方式，见 paymentMethod
userInfoobject—条件必填用户信息；需要支持 Payermax 渠道时须上送该结构体，见 userInfo
notifyUrlstring≤ 256 字符，URL是支付结果异步回调地址
returnUrlstring≤ 256 字符，URL否用户支付完成后的跳转地址
descriptionstring≤ 256 字符否订单描述

amount 对象 ​

字段名类型长度 / 限制必填说明
valuestring数值大于 0，字符串长度 ≤ 12是具体金额（最小货币单位，如 cents），须与币种匹配；与币种规则不符的金额（例如日元场景下送小数形式）将直接前置拒绝
currencystring3 字符，ISO-4217是币种，如 USD、PHP

支持的国家与币种对应关系见 国家币种说明。

transInitiator 对象 ​

字段名类型长度 / 限制必填说明
terminalTypestring枚举是发起支付的终端类型：WEB、WAP、APP
deviceTypestring枚举条件必填Android、iOS。当 paymentMethod.type 为 e-wallet 且 terminalType 为 WAP 或 APP 时必送
browserInfoobject—条件必填卡交易，且非商户自带 3DS 结果场景时必送，见 browserInfo

browserInfo 对象 ​

（置于 transInitiator.browserInfo，条件见上。）

字段名类型长度 / 限制必填说明
acceptHeaderstring≤ 2048是用户浏览器的 Accept 请求头值
colorDepthstring2 字符是浏览器色深，枚举：1、4、8、15、16、24、32、48
javaEnabledboolean—是浏览器是否启用 Java
languagestring≤ 8是如 navigator.language，例：en-GB
screenHeightstring≤ 6是屏幕高度（像素）
screenWidthstring≤ 6是屏幕宽度（像素）
timeZoneOffsetstring≤ 5是UTC 与浏览器本地时间的时差，分钟

paymentMethod 对象 ​

字段名类型必填说明
typestring是支付类型，枚举：card、e-wallet、qr、onlineBanking、bankTransfer。详见 支付类型说明
e-walletobject条件必填当 type 为 e-wallet 时必须存在，见下表
qrobject条件必填当 type 为 qr 时必须存在，见下表
onlineBankingobject条件必填当 type 为 onlineBanking 时必须存在，见下表
bankTransferobject条件必填当 type 为 bankTransfer 时必须存在，见下表
cardobject条件必填当 type 为 card 时必须存在，见下表
threeDSobject条件必填当 type 为 card 时须携带，用于 3DS 策略，见 threeDS

JSON 中表示电子钱包子对象时，键名需使用 "e-wallet"（带引号）。

paymentMethod.e-wallet 对象 ​

字段名类型必填说明
paymentBrandstring是枚举值见 支付品牌说明

paymentMethod.qr 对象 ​

字段名类型必填说明
paymentBrandstring是枚举值见 支付品牌说明

paymentMethod.onlineBanking 对象 ​

字段名类型必填说明
paymentBrandstring是枚举值见 支付品牌说明

paymentMethod.bankTransfer 对象 ​

字段名类型必填说明
paymentBrandstring是枚举值见 支付品牌说明

paymentMethod.card 对象 ​

字段名类型长度 / 限制必填说明
cardNumberstring≤ 19是卡号；送 card 结构时必送
cvcstring≤ 4否卡背安全码
expiryDatestring≤ 4是有效期，格式 MMYY
holderNamestring≤ 50否持卡人姓名

threeDS 对象 ​

（置于 paymentMethod.threeDS。）

字段名类型必填说明
threeDSStrategystring是Force：强制 3DS（对应 inner）；None：不做 3DS（对应 none）；External：商户自有 3DS 结果

userInfo 对象 ​

字段名类型长度 / 限制必填说明
merchantUserIdstring≤ 128 字符否商户侧用户唯一标识，用于风控、支付工具绑定、复购识别、争议追踪
phoneNumberstring≤ 32 字符否用户手机号
shopperIPstring≤ 64否用户 IP
userAgentstring≤ 2048否HTTP User-Agent 头内容
emailstring≤ 254否用户邮箱
billingAddressobject—否账单地址；若渠道将地址用于身份校验，按渠道要求可能需要上送，见 billingAddress
nameobject—否用户姓名，见 name

billingAddress 对象 ​

（置于 userInfo.billingAddress。若上送该对象，下列标「是」的字段须填写完整。）

字段名类型长度 / 限制必填说明
addressstring≤ 1024否账单详细地址
citystring≤ 50是城市
countrystring2 字符是ISO-3166 二位国家代码，如 CN
postalCodestring≤ 16否邮政编码
stateOrProvincestring≤ 3否州/省，ISO 3166-2
emailstring≤ 254是用户邮箱

name 对象 ​

（置于 userInfo.name。）

字段名类型长度 / 限制必填说明
firstNamestring≤ 64否名
lastNamestring≤ 64否姓

二、请求示例 ​

电子钱包（e-wallet） ​

terminalType 为 WEB 时无需上送 deviceType。paymentMethod.type 为 e-wallet 且 terminalType 为 WAP 或 APP 时必须上送 deviceType（Android 或 iOS）。需要支持 Payermax 渠道时须上送 userInfo。

json
{
  "merchantOrderId": "M202512180001",
  "amount": {
    "value": "1099",
    "currency": "HKD"
  },
  "country": "HK",
  "transInitiator": {
    "terminalType": "APP",
    "deviceType": "Android"
  },
  "paymentMethod": {
    "type": "e-wallet",
    "e-wallet": {
      "paymentBrand": "gcash"
    }
  },
  "userInfo": {
    "merchantUserId": "user_10001",
    "phoneNumber": "7151923499",
    "shopperIP": "112.198.100.1",
    "userAgent": "Mozilla/5.0 (Linux; Android 13; SM-S911B)",
    "email": "example@gmail.com"
  },
  "notifyUrl": "https://merchant.com/webhook/payment",
  "returnUrl": "https://merchant.com/pay/result",
  "description": "MU ticket 2025-12-18"
}

卡支付（card，含 browserInfo 与 threeDS） ​

json
{
  "merchantOrderId": "ORDER_20260330_153728_AO1002",
  "amount": {
    "value": "20",
    "currency": "PHP"
  },
  "country": "PH",
  "transInitiator": {
    "terminalType": "WEB",
    "browserInfo": {
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "colorDepth": "24",
      "javaEnabled": false,
      "language": "zh-CN",
      "screenHeight": "1440",
      "screenWidth": "2560",
      "timeZoneOffset": "480"
    }
  },
  "paymentMethod": {
    "type": "card",
    "card": {
      "cardNumber": "36563",
      "cvc": "123",
      "expiryDate": "1026",
      "holderName": "Bhns Josn",
      "threeDS": {
        "threeDSStrategy": "None"
      }
    }
  },
  "notifyUrl": "https://xxxxxxx/api/v1/payin/test/webhook/notify",
  "returnUrl": "https://www.baidu.com",
  "description": "Test Order – Payment Testing",
  "userInfo": {
    "merchantUserId": "user_20001",
    "phoneNumber": "7151923499",
    "shopperIP": "178.49.15.251",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15) Gecko/20100101 Firefox/122.0",
    "email": "jane.brown307@example.com",
    "billingAddress": {
      "city": "New York",
      "country": "US",
      "email": "jane.brown307@example.com",
      "address": "123 Broadway Ave",
      "postalCode": "10001",
      "stateOrProvince": "NY"
    },
    "name": {
      "firstName": "Jane",
      "lastName": "Brown"
    }
  }
}

三、应答说明（Response Body） ​

响应体根节点为 result 与 data：

字段名类型长度 / 限制必返说明
resultobject—是支付结果（返回码与说明）
dataobject——支付单数据，结构见下表

result 对象 ​

字段名类型长度 / 限制必返说明
codestring≤ 32 字符是返回码（成功 / 失败等标识），完整释义见 应答码说明
msgstring≤ 255 字符是返回信息说明

data 对象 ​

字段名类型长度 / 限制必返说明
paymentIdstring≤ 64 字符是Velora 平台生成的支付单号
merchantOrderIdstring/否商户订单号
pspstring/否实际承接订单的 PSP 标识
channelOrderIdstring≤ 64 字符否PSP / 渠道侧订单号
statusstringPending / Success / Failed是当前支付状态
amountobject—否支付金额；交易成功或失败时可能返回，见 data.amount
actionobject—否商户侧下一步操作指引，见 data.action

data.amount 对象 ​

字段名类型长度 / 限制必返说明
valuestring数值大于 0，字符串长度 ≤ 12是（随 amount 出现）具体金额（最小货币单位，如 cents）；须与币种规则一致，与规则不符的取值（例如日元场景下小数形式）将不符合约定
currencystring3 字符，ISO-4217是（随 amount 出现）币种，如 USD、PHP

data.action 对象 ​

字段名类型长度 / 限制必返说明
typestring≤ 32否操作类型枚举：Redirect；threeDSRedirect
paymentUrlstring≤ 255，URL否跳转型支付地址；当 action.type 为 Redirect 时返回
redirectUrlstring≤ 1024否3DS 认证地址；当 action.type 为 threeDSRedirect 时返回
expireAtstringISO-8601否失效时间；渠道返回时向下游（商户）透传

四、应答示例 ​

待支付（Pending，Redirect） ​

json
{
  "result": {
    "code": "P0001",
    "msg": "Payment is processing."
  },
  "data": {
    "paymentId": "payin_202512180001",
    "merchantOrderId": "M202512180001",
    "psp": "omnipay",
    "channelOrderId": "OMNI202512180001",
    "status": "Pending",
    "action": {
      "type": "Redirect",
      "paymentUrl": "https://checkout.omnipay.com/pay/abc123",
      "expireAt": "2025-12-18T18:30:00+08:00"
    }
  }
}

待支付（Pending，threeDSRedirect） ​

json
{
  "result": {
    "code": "P0001",
    "msg": "Payment is processing."
  },
  "data": {
    "paymentId": "payin_202512180002",
    "merchantOrderId": "M202512180002",
    "psp": "bankcard_acquirer",
    "channelOrderId": "ACQ202512180002",
    "status": "Pending",
    "action": {
      "type": "threeDSRedirect",
      "redirectUrl": "https://acs.bank.example.com/3ds-challenge",
      "expireAt": "2025-12-18T18:30:00+08:00"
    }
  }
}

支付成功（Success，含 amount） ​

json
{
  "result": {
    "code": "S0000",
    "msg": "Success"
  },
  "data": {
    "paymentId": "payin_202512180003",
    "merchantOrderId": "M202512180003",
    "psp": "wallet_partner",
    "channelOrderId": "WALLET202512180003",
    "status": "Success",
    "amount": {
      "value": "1099",
      "currency": "HKD"
    }
  }
}

创建失败（Failed，示例含 amount） ​

json
{
  "result": {
    "code": "P0012",
    "msg": "Transaction rejected by risk control"
  },
  "data": {
    "paymentId": "payin_202512180006",
    "merchantOrderId": "M202512180006",
    "psp": "risk_gateway",
    "channelOrderId": "RISK202512180006",
    "status": "Failed",
    "amount": {
      "value": "1099",
      "currency": "HKD"
    }
  }
}

业务结果码 result.code 的完整说明见 应答码说明。

相关链接 ​