支付/预授权

注意

关于预授权:
Ps:预授权完成最好在3个工作日内完成，否则万事达卡会被加收0.033欧元+0.28%的手续费，同时，超过3天的预授权拒付是无法申诉的。

流程说明

请求参数对象说明

payerInfo

参数	必选	类型	说明
paymentMethod	Y	string	目前固定为 credit_card
authorizationMethod	Y	string	cvv （普通交易） threeds2.0 (3D) AuthorizationMethod（用户授权方式：cvv/threeds1.0/threeds2.0）：这个字段生产环境传cvv，当客户的卡需要3ds时我们会动态转成3d。只是对接测试的时候可以根据自己需要的场景切换 cvv/threeds2.0。 threeds1.0现在我们不支持传，3d一般都走2.0流程,即使客户的卡只支持1.0，我们也会自动降级的
billingAddress	Y	Json String	账单地址（请根据交易类型：实物类交易/虚拟类交易传参）
firstName	N	String(56)	持卡人名（如果为空，则UseePay会用账单/收货地址姓名填充）
lastName	N	String(56)	持卡人名（如果为空，则UseePay会用账单/收货地址姓名填充）
threeDS2RequestData	N		3ds请求参数

threeDS2RequestData对象参数说明

参数	必选	类型	说明	备注
deviceChannel	Y	string	max=12 1.app 2. browser
acceptHeader	conditional	string	max=12 浏览器 accept header 的值	deviceChannel=browser时，必填
colorDepth	conditional	string	max=2 用户浏览器的颜色深度，单位是位/像素。可接受的值：1、4、8、15、16、24、30、32、48	deviceChannel=browser时，必填
javaEnabled	conditional	string	max=6 用户浏览器是否支持 Java 执行：true\false	deviceChannel=browser时，必填
javaScriptEnabled	cond	string	用户浏览器是否支持 javaScript 执行：true\false。如果不传，默认为支持	deviceChannel=browser时，必填
language	Conditional	string	用户浏览器语言	deviceChannel=browser时，必填
screenHeight	Conditional	string	max=10 用户浏览器屏幕高度，单位是位/像素	deviceChannel=browser时，必填
screenWidth	Conditional	string	max=10 用户浏览器屏幕高度，单位是位/像素	deviceChannel=browser时，必填
timeZoneOffset	Conditional	string	max=10 用户浏览器时间与 UTC 时间之差，单位是分钟	deviceChannel=browser时，必填
userAgent	Conditional	string	max=10 用户浏览器代理	deviceChannel=browser时，必填
challengeWindowSize	Optional	string	max=16 3ds挑战窗口大小,可接受的值:1. 250x400 2. 390x400 3. 500x600 4. 500x600 5. full_screen
challengeIndicator	Optional	string	max=64 3ds挑战偏好设置,可接受的值:1. no_preference: Don't have any preferences related to the Challengeflow 2. no_challenge_requested: I prefer that a Challenge flow does not take place 3. preference: A request for the Challenge flow to take place 4. mandate: A Challenge flow must take place to fulfill a mandate

{
    "deviceChannel": "browser",
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
    "colorDepth": 24,
    "javaEnabled": "false",
    "language": "zh-HK",
    "screenHeight": 1080,
    "screenWidth": 1920,
    "timeZoneOffset": -480,
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36"
}

billingAddress 账单地址信息（实物类交易）

参数	必选	类型	说明
email	Y	string	收货邮箱
firstName	Y	string	收货人名
lastName	Y	string	收货人姓
phoneNo	N	string	收货手机号
street	Y	string	收货街道地址
houseNo	N	string	收货街道地址和门牌号当street存在时可以不填
postalCode	Y	string	邮编，如果该国家或地区由邮编必须传，否则可以不传
city	Y	string	城市
state	Y	string	省/州/地区, 需满足 ISO 3166-2
country	Y	string	国家，ISO 两位大写英文国家代码, 需满足 ISO 3166-1

billingAddress 账单地址信息（虚拟类交易）

参数	必选	类型	说明
email	Y	string	买家邮箱
firstName	N	string	收货人名
lastName	N	string	收货人姓
phoneNo	N	string	收货手机号
street	N	string	收货街道地址
houseNo	N	string	收货街道地址和门牌号当street存在时可以不填
postalCode	N	string	邮编，如果该国家或地区由邮编必须传，否则可以不传
city	N	string	城市
state	N	string	省/州/地区, 需满足 ISO 3166-2
country	N	string	国家，ISO 两位大写英文国家代码, 需满足 ISO 3166-1

orderInfo 订单信息

参数	必选	类型	说明
subject	Y	string	订单标题
goodsInfo	Y	array	商品信息, 请参考 goodsInfo
shippingAddress	Y	object	收货地址, 请参考 shippingAddress

goodsInfo 商品信息

参数	必选	类型	说明
id	Y	string	sku id
name	Y	string	商品名
body	Y	string	商品描述
quantity	Y	number	商品数量
price	Y	string	商品价格,必须大于0，单位为对应货币的最小货币单位参考货币单位一节
url	N	string	商品链接
image	N	string	商品图片

[
    {
        "id": "商品编号",
        "name": "商品名称",
        "body": "商品描述",
        "category": "商品类目",
        "categoryTree": "商品类目树，不同级别类目使用”|”分割",
        "brand": "商品品牌",
        "quantity": 1,
        "price": 1234,
        "url": "商品url",
        "sku": "商品sku",
        "image": "商品图片url"
    }
]

shippingAddress 收货地址（注：实物类交易必传，虚拟类交易非必传）

参数	必选	类型	说明
email	Y	string	收货邮箱
phoneNo	N	string	收货手机号
firstName	Y	string	收货人名
lastName	Y	string	收货人姓
street	Y	string	收货街道地址
houseNo	N	string	收货街道地址和门牌号当street存在时可以不填
postalCode	Y	string	邮编，如果该国家或地区由邮编必须传，否则可以不传
city	N	string	城市
state	Y	string	省/州/地区, 需满足 ISO 3166-2
country	Y	string	国家，ISO 两位大写英文国家代码, 需满足 ISO 3166-1

{
    "email": "haile1y@useepay.com",
    "phoneNo": "123123",
    "firstName": "Victor",
    "lastName": "Yang",
    "street": "Heathcoat House, 20 Savile Row",
    "postalCode": "W1S 3PR",
    "city": "London",
    "state": "LND",
    "country": "GB"
}

userInfo

参数	必选	类型	说明
userId	N	string	max=128 用户id
ip	Y	string	max=128 IPv4或IPv6
email	Y	string	max=128用户邮箱
phoneNo	N	string	max=32 用户手机号

请求参数

Header 参数

Content-Type

string

必需

示例值:

application/x-www-form-urlencoded

Body 参数application/x-www-form-urlencoded

amount

string

必需

支付金额参考通用对象参数和规范说明

示例值:

100

appId

string

必需

提交审核的网站，需与商户后台网站审核值一致 (128)

示例值:

www.pay.com

autoRedirect

string

可选

是否302跳转 true/ false 默认 true

示例值:

false

country

string

可选

示例值:

currency

string

必需

货币单位

示例值:

USD

deviceInfo

string

可选

参考对象模型deviceInfo

示例值:

{"fingerPrintId":"设备指纹id","mac":"设备mac地址"}

echoParam

string

可选

maxlength:256 回声参数，Response 中将会原样返回

示例值:

echoParam

merchantNo

string

商户号 (16)

必需

示例值:

500000000007362

notifyUrl

string

可选

maxlength:512 异步通知地址推荐传输

示例值:

http://gatewaytest.useepay.com/notifyV2u0

orderInfo

string

必需

订单信息。请参考文档上方的对象参数说明

示例值:

{"subject":"order title","goodsInfo":[{"id":"商品编号","name":"商品名称","body":"商品描述","category":"商品类目","categoryTree":"商品类目树，不同级别类目使用”|”分割","brand":"商品品牌","quantity":1,"price":1234,"url":"商品url","sku":"商品sku","image":"商品图片url"}],"shippingAddress":{"email":"haile1y@useepay.com","phoneNo":"123123","firstName":"Victor","lastName":"Yang","street":"Heathcoat House, 20 Savile Row","postalCode":"W1S 3PR","city":"London","state":"LND","country":"GB"}}

payerInfo

string

必需

付款方信息，请参考参数说明

示例值:

{"authorizationMethod":"cvv","threeDS2RequestData":{"deviceChannel":"browser","acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9","colorDepth":24,"javaEnabled":"false","language":"zh-HK","screenHeight":1080,"screenWidth":1920,"timeZoneOffset":-480,"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36","threeDSMethodCallbackUrl":"http://star-saas.mynatapp.cc:80/api/UseePayReturn?tradeNo=166614926624432064&type=1"},"billingAddress":{"houseNo":"El Gallo Giro(https://gallogiro.com/)","email":"hai1ley@useepay.com","phoneNo":"1235854433","firstName":"amber","lastName":"Yang","stlogreet":"7148 Pacific Blvd, Huntington Park, CA","postalCode":"90225","city":"Huntington Park","state":"CA","country":"MX","street":"street"}}

redirectUrl

string

必需

maxlength=512重定向请求的跳转地址

示例值:

http://192.168.1.56:8005/redirectV2u0

sign

string

必需

签名值，签名方法请参加签名指导章节根据签名算法计算出签名

示例值:

286cdd569189dbb512619bf12945a508

signType

string

必需

maxlength:4 签名类型(MD5/RSA)

示例值:

MD5

terminalType

string

必需

终端类型 WEB/H5/APP

示例值:

WEB

transactionExpirationTime

string

必需

maxlength:6 交易过期时间(单位为分钟)

示例值:

1880

transactionId

string

必需

商户订单号 (max 64)

示例值:

202412240321366

transactionType

string

必需

传 pay / authorization
pay: 支付 authorization：预授权

示例值:

pay

userInfo

string

必需

消费者信息，请参考参数说明

示例值:

{"userId":"victor1","ip":"103.25.65.178","email":"dynam1ic_3d@useepay.com"}

version

string

必需

maxlength=5 目前固定为 1.0

示例值:

1.0

gatewaySource

string

可选

建站平台，如果是自建站则不需要传输

示例值:

SHOPIFY、SHOPLINE、SHOPYY、SHOPBASE、funpinpin等

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://pay-gateway1.uat.useepay.com/cashier' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'amount=100' \
--data-urlencode 'appId=www.pay.com' \
--data-urlencode 'autoRedirect=false' \
--data-urlencode 'country=JP' \
--data-urlencode 'currency=USD' \
--data-urlencode 'deviceInfo={"fingerPrintId":"设备指纹id","mac":"设备mac地址"}' \
--data-urlencode 'echoParam=echoParam' \
--data-urlencode 'merchantNo=500000000007362' \
--data-urlencode 'notifyUrl=http://gatewaytest.useepay.com/notifyV2u0' \
--data-urlencode 'orderInfo={"subject":"order title","goodsInfo":[{"id":"商品编号","name":"商品名称","body":"商品描述","category":"商品类目","categoryTree":"商品类目树，不同级别类目使用”|”分割","brand":"商品品牌","quantity":1,"price":1234,"url":"商品url","sku":"商品sku","image":"商品图片url"}],"shippingAddress":{"email":"haile1y@useepay.com","phoneNo":"123123","firstName":"Victor","lastName":"Yang","street":"Heathcoat House, 20 Savile Row","postalCode":"W1S 3PR","city":"London","state":"LND","country":"GB"}}' \
--data-urlencode 'payerInfo={"authorizationMethod":"cvv","threeDS2RequestData":{"deviceChannel":"browser","acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9","colorDepth":24,"javaEnabled":"false","language":"zh-HK","screenHeight":1080,"screenWidth":1920,"timeZoneOffset":-480,"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36","threeDSMethodCallbackUrl":"http://star-saas.mynatapp.cc:80/api/UseePayReturn?tradeNo=166614926624432064&type=1"},"billingAddress":{"houseNo":"El Gallo Giro(https://gallogiro.com/)","email":"hai1ley@useepay.com","phoneNo":"1235854433","firstName":"amber","lastName":"Yang","stlogreet":"7148 Pacific Blvd, Huntington Park, CA","postalCode":"90225","city":"Huntington Park","state":"CA","country":"MX","street":"street"}}' \
--data-urlencode 'redirectUrl=http://192.168.1.56:8005/redirectV2u0' \
--data-urlencode 'sign=286cdd569189dbb512619bf12945a508' \
--data-urlencode 'signType=MD5' \
--data-urlencode 'terminalType=WEB' \
--data-urlencode 'transactionExpirationTime=1880' \
--data-urlencode 'transactionId=202412240321366' \
--data-urlencode 'transactionType=pay' \
--data-urlencode 'userInfo={"userId":"victor1","ip":"103.25.65.178","email":"dynam1ic_3d@useepay.com"}' \
--data-urlencode 'version=1.0'

返回响应

🟢200成功(autoRedirect=false)

application/json

Body

amount

string

金额

必需

redirectUrl

string

收银台地址

必需

当resultCode=received时存在

resultCode

string

业务返回码

必需

判断交易是否成功 received 表示收银台请求被成功接受，可以返回redirectUrl给消费者

sign

string

签名

必需

验证签名

errorCode

string

错误返回码

必需

用于展示给消费者具体的错误信息，可参考错误码页面

transactionId

string

商户订单号

必需

errorMsg

string

错误返回信息

必需

token

string

token

可选

当resultCode=received时存在

transactionType

string

交易类型

必需

pay/authorization

reference

string

业务流水号

可选

UseePay的业务流水号

echoParam

string

可选

signType

string

签名类型

必需

currency

string

币种

可选

merchantNo

string

商户号

必需

示例

{
  "amount": "1234",
  "redirectUrl": "https://checkout1.uat.useepay.com/v2?accessToken=eAFlVVtvG0UU_ivR9AVQ7OzsJb48kTgNjZQEIyetqqYP493JepTdnWV2Nq5lIsFL20iJUgRFSBVS1ZciIVXACwgK_S-ojssTf4FzZnedbesoludcv3PmO2emRPEsjzTpTsmhUJneZTEnXXJT-FoqskwitpDdZkkIEp-pYG-S8ox07xCWphFP2YTcXSYh03zMJgOZKx9j7A-uX--v3QaXPONqTx7xZCs5lOA2NUF24SdxbQs-H5kP_ioTDPwRN0CORcaqpBjBuFDLdimlnuO0PNqmLdrpuJ0OmMVc-SOW6K0A7DyMV3xazqoNasVDkWmu9gGPMTk2ZVpWi5xAAVBHzBO9w_VIBlhegbMqdko0lA2BF0WjU1I07C2ZVAEkMLVOyVBEkUjCDZ75SqTY1S4J86ImJUog4_G4CembvoxRkyvFE38ClvuDDRCEEgAVAcmd6QERMQv5AekekNnj-7Nvvpo9-Xt--iBX0QFZPiCf59ACoSdgQOGYKuEXxtRuOq4xQdR1_0fn8-c_G40IavL5y-9mF78ZuQ-3G0o12VO87jn_5c_5kxeXT7_-7-XZ69_PZ4_O5n88nz38qZC__uvV_Nsf__nyhy_gf_bw_uz0VxNsKANEV8G_vLh486pIX6WpaYtQxi87ymsKc4ICh4olddTQkPnpmXEwLVnkMaeTu1VDS66_efFsdv748umDf599D6qKQ5-aS0Qi2ZbtWJ7tWZS2LIuCTXHBqKMWLZTUoa3VdrtD26DXgChbi2GsCKjdSoJMAlHGIk5OlonIeiz5LBf-UR8mqEsmMFPAwpFMuJmNDxzb-XDJa3sN13UcUPGYiQgMC9o2JzCQH8Ns4QCWzGFR1JPJoQgr9rGApcB4cLIQxlBqLeNbgB8kAw5E40s9GOglQIDcBxMcoJBvw1cOJAMzLNhXnBXUFYlAKx4PeRDwYDMKMTZKkmBPxLwnI0Pxa5ubrmvmOYx1D905qoGSnm23YX69NswmUDvWOzIQh5NSu9pyOo7jea7ntaBFgJNipwYjOe7JPNGBHOMSwIzRFUZYDHBzTCR70DxQX4OrsjfQKEakxbQXx9qGqAtKMhgR4oHJhDgsiEWyBmGgxev6_egozqGlSV_c43A1NlhCI2De-zKKsCTYIx5unkAo7mOpVUszqGgtTdeZuuFBJuzylajv10TrsEHgiNDQAo_vLpTKe71-v5UDXvBIRkG5qhbi4-Nakk0pC55UoT7BnRPA1qqlNrJ3wmzLEBd5FdWMDV7boqJbfJgJvShbM6XfIoq7hn9Y3CTZlRpaD0tAyKTYw2VozeM0Ag7h2nYdmLDyXF7bLh_fkLDag5LHfaTuldW-wgauHOMjYGYTAcgc59NutxG6VpNt6bOqzzBVO-VbMiiwW-QERra6xyLgSOs0666slC-f5plu1uaxkjdQsVK53rRzTFitGfMOvf9U4Su7K7fzUdIbcf-IdA9ZlPHl4u2BIit0WwFMbcXWKiYug2YGS3Eo71WAsMbyAY1l2o1ZKroIKeuurnJGWdtqHLLhsEEpDxps6FqNIeUdywoct80pOfkflOHNfA%3D%3D",
  "resultCode": "received",
  "sign": "9080da2b45be15a7d5535e4afd15be3c",
  "errorCode": "0000",
  "transactionId": "202305250117001",
  "errorMsg": "Approved or completed successfully",
  "token": "mop:mapi:redis:66ea1a80-fabb-11ed-ab40-b1e900d348e1",
  "transactionType": "pay",
  "reference": "1012305251317688918",
  "echoParam": "echoParam",
  "reserved": "reserved",
  "signType": "MD5",
  "currency": "USD",
  "merchantNo": "500000000007362"
}

🔵302成功(autoRedirect=true)

支付/预授权

流程说明#

请求参数对象说明#

payerInfo#

threeDS2RequestData对象参数说明#

billingAddress 账单地址信息（ 实物类交易）#

billingAddress 账单地址信息（ 虚拟类交易）#

orderInfo 订单信息#

goodsInfo 商品信息#

shippingAddress 收货地址 （ 注：实物类交易必传，虚拟类交易非必传）#

userInfo#

请求参数

示例代码

返回响应

流程说明

请求参数对象说明

payerInfo

threeDS2RequestData对象参数说明

billingAddress 账单地址信息（实物类交易）

billingAddress 账单地址信息（虚拟类交易）

orderInfo 订单信息

goodsInfo 商品信息

shippingAddress 收货地址（注：实物类交易必传，虚拟类交易非必传）

userInfo