> ## Documentation Index
> Fetch the complete documentation index at: https://doc2.payloco.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 消费
> 发起消费交易，消费成功时会产生实际扣款
## OpenAPI
````yaml openapi_en.yaml post /v2/payments/open/api/pay
openapi: 3.1.0
info:
version: '2024-03-31'
title: Payloco开放平台接口文档
description: "# Introduction.\n\nWelcome to Payloco.\n\nThe Payloco API is designed to be flexible and give you control in how and when you convert currencies, make payments and manage your accounts.\n\nWe recommend you read through the API Documentation in full to familiarise yourself with the features and workflows associated with the product. Demo account access can also be provided to you, and the Client ID and API key can be generated within Account settings > API keys in the Web Application.\n\nFor any assistance through the integration, your PayLoco Business Development Manager and your allocated PayLoco Client Integration Manager will be able to help guide you.\n# Versioning\n\nPayLoco uses versioning to improve our API contracts without affecting existing users.\n\nWhen we need to introduce a backwards-incompatible change, such as renaming or splitting a field, we will create a new date version which clients can migrate to when ready.\n### What is the latest version?\nThe latest version is `2024-03-31`.\n\n\n\n## 支付方式\n | 支付方式 | 支持国家 | 支付类型 | Tokenization | MIT | 必填参数(端到端支付必填) | 交易币种 |\n| :----: | :----: | :----: | :----: | :----:| :----:| :----: |\n| VISA | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| MasterCard | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| JCB | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| DISCOVER | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| UNION_PAY | 全球 | CREDIT_CARD | ☑️ | ☑️ | cardNo/firstName/lastName/cvv/expireYear/expireMonth | 全币种 |\n| WEIXIN | 中国香港(HK) | QRCODE,MICROPAY,JSAPI,MINIPROGRAM,APP,H5\t | - | - | - | CNY,HKD |\n| UNIONPAY | 中国香港(HK) | WEB,PAN_PRESENT,QRCODE,H5,3DS | - | - | - | CNY,HKD |\n| ALIPAY_CN | 中国(CN) | H5,WEB,APP\t | - | - | - | CNY,USD,HKD|\n| ALIPAY_HK | 中国香港(HK) | H5,WEB,APP\t | - | - | - | HKD,USD|\n| ALIPAY_HK | 中国香港(HK) | H5,WEB,APP\t | - | - | - | HKD,USD|\n| GCASH | 菲律宾(PH)| H5,WEB,BILLS\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP,USD |\n| BPI | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP,USD |\n| MAYA | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP |\n| BILLEASE | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP,USD |\n| Dragonpay | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP |\n| GrabPay_PH | 菲律宾(PH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | PHP |\n| TNG | 马来西亚(MY)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | MYR,USD |\n| BOOST | 马来西亚(MY)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | MYR,USD |\n| GrabPay_MY | 马来西亚(MY)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | MYR |\n| DANA | 印度尼西亚(ID)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR,USD |\n| KAKAOPAY | 韩国(KR)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | KRW,USD |\n| NAVERPAY | 韩国(KR)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | KRW,USD |\n| TOSSPAY | 韩国(KR)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | KRW,USD |\n| TRUEMONEY | 泰国(TH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | THB,USD |\n| RABBIT_LINE_PAY | 泰国(TH)| H5,WEB\t | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | THB,USD |\n| BRAZIL_PIX | 巴西(BR)| H5,QRCODE | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | BRL |\n| Ewallet_PicPay | 巴西(BR)| H5,QRCODE | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | BRL |\n| Khipu | 智利(CL)| H5 | - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | CLP |\n| GrabPay_SG | 新加坡(SG)| H5,WEB\t | - |- | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | SGD,USD |\n| GoPay | 印度尼西亚(ID)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR |\n| OVO | 印度尼西亚(ID)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR |\n| DOKU | 印度尼西亚(ID)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | IDR |\n| Konbini | 日本(JP)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | JPY |\n| PayEasy | 日本(JP)| H5,WEB\t| - | - | countryCode/terminalType/osType
[terminalType必填(WEB,WAP,APP);
terminalType为WAP/APP时osType必填(IOS,ANDROID)] | JPY |"
termsOfService: https://www.payloco.com
contact:
name: 技术支持
email: support@payloco.com
url: https://www.payloco.com
license:
url: https://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
summary: ''
servers:
- url: https://gate.uat.payloco.com/gateway
description: Development server
- url: https://gate.payloco.com/gateway
description: Live server
security:
- signature: []
tags:
- name: 收单
- name: 其他交易类型
- name: 商户管理
- name: 文件下载
- name: 用卡人
- name: 卡管理
- name: 卡交易管理
- name: 收件人
paths:
/v2/payments/open/api/pay:
parameters: []
post:
tags:
- 收单
summary: 消费
description: 发起消费交易，消费成功时会产生实际扣款
operationId: post-v2-payments-open-api-pay
parameters:
- schema:
type: string
example: >-
FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==
in: header
name: signature
required: true
description: 签名
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pay'
examples:
Example 1:
value:
charset: UTF-8
version: 2.0.0
signType: RSA
memberId: '2023010558663764'
merchantId: '2023010558663764'
requestTime: '2024-05-24T14:29:32.682+08:00'
keyVersion: '1'
data:
merchantOrderId: ORD202604231532478921
integrate: Direct
captureMode: MANUAL
subject: Iphone 16
totalAmount: '10.01'
currency: USD
country: US
userId: U123333333
expireTime: '1800'
paymentDetail:
paymentMethodType: WALLET
targetOrg: KLARNA
payAccountInfo:
- accountNo: 125@gmail.com
accountNoType: EMAIL
cardInfo:
cardNo: '4111111111111111'
cardName: John Tan
cardExpirationMonth: '12'
cardExpirationYear: '28'
cvv: '123'
stored: 'true'
dynamic3DS: 'true'
buyerInfo:
firstName: John
middleName: Michael
email: john.tan@example.com
lastName: Tan
phoneNo: '+6591234567'
phoneNoRegion: '+65'
idType: PASSPORT
idNo: E12345678
taxType: CPF
taxNo: 123.456.789-09
address: '10 Anson Road, #25-08 International Plaza'
city: Singapore
region: Central
zipCode: '079903'
clientIp: 203.0.113.42
userAgent: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)
AppleWebKit/605.1.15
paymentTokenID: ptok_9f1c2e7a6b5d4c3a8e0f1b2c3d4e5f6a
tokenForFutureUse: true
merchantInitiated: 'false'
mitType: SCHEDULED
info3DSecure:
threeDSVersion: 2.2.0
eci: '05'
cavv: AAABBBCCCDDDEEE111222333
dsTransactionId: f47ac10b-58cc-4372-a567-0e02b2c3d479
xid: MDAwMDAwMDAwMDAwMDAwMDAwWDEyMw==
carrierId: qiye
goodsDetails:
- goodsId: SKU_1000001
goodsName: Wireless Bluetooth Earbuds
quantity: '2'
price: '59.99'
goodsCurrency: USD
showUrl: https://example.com/product/sku_1000001
goodsCategory: Electronics
subMerchant:
subMerchantNo: SM202604270001
shippingInfo:
firstName: John
middleName: string
lastName: John
phoneNo: '+6598765432'
email: john.tan@example.com
address1: 10 Anson Road
city: Singapore
region: Central
state: string
country: SG
zipCode: '079903'
address2: '#25-08 International Plaza'
address3: string
billingInfo:
firstName: John
middleName: Michael
lastName: Tan
phoneNo: '+6591234567'
email: john.tan@example.com
address1: 10 Anson Road
city: Singapore
country: SG
region: Central
state: string
zipCode: '079903'
address2: '#25-08 International Plaza'
address3: string
envInfo:
deviceId: a3f5c9e2-7b4d-4c1a-9f6e-2d8b7a1c0e5f
deviceLanguage: en-US
screenHeight: '956'
screenWidth: '440'
userAgent: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)
AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0
Mobile/15E148 Safari/604.1
language: EN
riskParams: {}
terminalType: APP
osType: ANDROID
reference: goods reference
frontCallbackUrl: https://www.google.com
notifyUrl: https://www.google.com
subscriptionPlan:
subscriptionNo: SUB_202604270001
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PayResponse'
examples:
Example 1:
value:
code: '00000003'
message: 处理中
traceId: 33fae7b7aed1233f
data:
status: SUCCESS
merchantId: '2023010558663764'
merchantOrderId: '167812677182888888'
orderId: TR1658354573473091584
currency: USD
totalAmount: '10.01'
nextAction:
contentType: application/json
data: {}
method: GET
qrcode: weixin://wxpay/bizpayurl?pr=waUjCuPzz
type: render_qrcode
url: https://www.google.com
components:
schemas:
Pay:
title: Pay
allOf:
- $ref: '#/components/schemas/BaseRequest'
- type: object
properties:
data:
type: object
x-stoplight:
id: rfjnd8jn1tek9
description: 请求数据体
required:
- merchantOrderId
- integrate
- subject
- totalAmount
- currency
- country
- paymentDetail
- terminalType
properties:
merchantOrderId:
type: string
x-stoplight:
id: 75nodpr8nhjai
description: >-
商户订单号，唯一标识商户的一笔交易，不能重复，只能包含字母、数字、下划线且不支持大小写敏感。如：AAA和AAa被认为是相同的。
maxLength: 64
example: ORD202604231532478921
integrate:
x-stoplight:
id: ehxipvqp48f8g
description: 商户自行进行付款方支付信息的收集后，传送给Payloco进行交易处理,需传入参数：Direct
example: Direct
enum:
- Cashier
- Direct
- DropIn
- PayLink
- Token
default: Direct
captureMode:
type: string
x-stoplight:
id: g2ts4t7rjj4ud
description: 请款模式：MANUAL
example: MANUAL
subject:
type: string
x-stoplight:
id: uf13vykw3caff
description: 订单标题或产品信息，会展示在用户支付页面，避免使用纯数字。注：巴西钱包Pix不能超过43位
maxLength: 256
example: Iphone 16
totalAmount:
type: string
x-stoplight:
id: 5b8inzm5imgbt
description: >-
付款的主要金额，金额的单位为元（例如，65.40 USD 代表 65.40 美元,1000 JPY
代表1000日元）。各个国家币种支持的小数位详见[ISO4217](https://www.iso.org/standard/64758.html)币种的字母码
example: '10.01'
currency:
x-stoplight:
id: 4o0k3qigdz68l
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码
eg. USD, CNY, EUR
example: USD
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTN
- BWP
- BYN
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNY
- COP
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRU
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLE
- SLL
- SOS
- SRD
- SSP
- STD
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VES
- VND
- VUV
- WST
- XAF
- XCD
- XOF
- XPF
- YER
- ZAR
- ZMW
- ZWL
country:
x-stoplight:
id: run8ama976od7
description: 国家代码，大写字母
example: US
enum:
- AF
- AX
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CW
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MK
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SZ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- UM
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- US
userId:
type: string
x-stoplight:
id: 81h7pd5ovl5wq
description: 商户内部的用户Id，需要保证每个ID唯一性。
maxLength: 64
example: U123333333
expireTime:
type: string
x-stoplight:
id: 3rgx3ocpixmct
example: '1800'
description: |
指定关单时间(单位：秒)。
1）expireTime 传值时：
- 当expireTime<=30min：则关单时间为30min
- 当24hour>=expireTime>=30min：则关单时间为expireTime
- 当expireTime>=24hour：则关单时间为24hour
2）expireTime 未传值时：
- 除纯API模式和前置组件的card/applepay/googlepay 关单时间为30min外，其他取这笔订单发起过的[支付方式关单时间]()的最大值。
paymentDetail:
type: object
x-stoplight:
id: 4e46yz88htgbg
description: 支付信息
required:
- paymentMethodType
properties:
paymentMethodType:
x-stoplight:
id: iyc4gegedumu4
description: >-
支付方式类型，参见【[支付方式列表](https://doc2.payloco.com/zh/developers/payment-methods)】支付方式必填
example: WALLET
enum:
- WALLET
- CARD
- BANK_TRANSFER
- PAY_LATER
- OTC
- ONE_TOUCH
- NET_BANKING
- GOOGLEPAY
- APPLEPAY
- REALTIME_PAYMENT
- ONE_TOUCH
default: WALLET
targetOrg:
x-stoplight:
id: ju5rbr20gqbdj
description: "目标机构除paymentMethodType为CARD外均必填\t"
enum:
- KLARNA
- PIX
- DANA
- BANKTRANSFER
- JKOPAY
- GASH
- OKMART
- HILIFE
- FAMILYMART
- 7-ELEVEN
- TAIWANMOBILE
- FETNET
- YUSHANEPAYMENT
- YUSHANBANK
- SHOPEEPAY
- PAOTANGPAY
- LINEPAY
- PROMPTPAY_CS
- PROMPTPAY
- SCB_TH
- KRUNGTHAI
- KASIKORN
- BANGKOK
- QRPH
- GCASH
- TRUEMONEY
- SMBILL
- GRABPAY
- TNG
- FPX
- OXXO
- TOSS
- SSGPAY
- SAMSUNGPAY
- PAYCO
- NAVERPAY
- KAKAOPAY
- DOMESTICCARD
- TMONEY
- EGGMONEY
- CULTURELAND
- TOSS
- PAYPAY
- WEBMONEY
- LAWSON
- FAMILYMART
- DAILYYAMAZAKI
- 7-ELEVEN
- PAYEASY
- KLARNA
- SHOPEEPAY
- OVO
- GOPAY
- DANA
- CARDPAY
- QRIS
- MINISTOP
payAccountInfo:
x-stoplight:
id: 99vwfwyuyfv3f
description: 支付账号，部分支付方式下的目标机构需要上送用户在该目标机构的支付账号信息。
type: array
items:
$ref: '#/components/schemas/PayAccountInfo'
x-stoplight:
id: 935xvl4fsafba
cardInfo:
type: object
x-stoplight:
id: fhw9erbxzmysu
description: 卡信息
properties:
cardIdentifierNo:
type: string
x-stoplight:
id: vyzmi8fhdfsrr
description: 卡号
maxLength: 19
example: '4111111111111111'
cardHolderFullName:
type: string
x-stoplight:
id: luns0wd5w8d1w
description: 持卡人姓名
maxLength: 64
example: John Tan
cardExpirationMonth:
type: string
x-stoplight:
id: h55p6yi20zaj4
description: 卡有效期-月，两位月份
maxLength: 2
example: '12'
cardExpirationYear:
type: string
x-stoplight:
id: kakp730z2idps
description: "卡有效期-年，只取后两位年份\t"
maxLength: 2
example: '28'
cvv:
type: string
x-stoplight:
id: eby2bw374mimw
description: 卡cvv，Visa和MasterCard为3位数字，AEMX为4位数字
maxLength: 4
example: '123'
stored:
type: string
x-stoplight:
id: fzkkcoax0fx5z
description: |-
代表该笔卡支付交易是否已存卡。
已存卡：Y
未存卡：不填或者其他值
maxLength: 4
example: 'true'
dynamic3DS:
type: string
x-stoplight:
id: yigp23jxyqlv2
description: >-
动态3ds（参数不区分大小写）
do3DS：为此订单执行3DS Secure
no3DS：不为此订单执行3DS Secure
ext3DS：使用外部3DS结果，适用于已经对接了其他3DS服务的商户，指定该值时，则必须同时传入info3DSecure对象
未传或传入其他值，由Payloco判断是否发起3ds
maxLength: 64
example: 'true'
buyerInfo:
type: object
x-stoplight:
id: qwlnwwuou23qh
description: 用户基本信息
properties:
firstName:
type: string
x-stoplight:
id: vj3ple3phmcyd
description: >-
用户名 注：巴西HIPERCAR、ELO卡支付时必传
maxLength: 64
example: John
middleName:
type: string
x-stoplight:
id: 8el57zdxs2sug
description: 用户中间名
maxLength: 64
example: Michael
email:
type: string
x-stoplight:
id: ol0jdbgwxuisv
description: >-
用户邮箱 注：巴西HIPERCAR、ELO卡支付时必传
maxLength: 255
example: john.tan@example.com
lastName:
type: string
x-stoplight:
id: lq2zaj7cqx9g0
description: >-
用户姓 注：巴西HIPERCAR、ELO卡支付时必传
maxLength: 64
example: Tan
phoneNo:
type: string
x-stoplight:
id: a9vw6oha6o6cc
description: 用户手机号 注：土耳其卡支付时必传
maxLength: 32
example: '+6591234567'
phoneNoRegion:
type: string
x-stoplight:
id: wddldw314i9au
description: 手机号区号 注：土耳其卡支付时必传
maxLength: 16
example: '+65'
idType:
type: string
x-stoplight:
id: 1o3jkahvb5u0f
description: 证件类型
maxLength: 32
example: PASSPORT
idNo:
type: string
x-stoplight:
id: pbl0158h1oait
description: 证件号
maxLength: 64
example: E12345678
taxType:
type: string
x-stoplight:
id: 7hv2trn94ookg
description: "税类型，参见【[各国税类型和税号规则]\t\n注：巴西国家该字段必须传入CPF"
maxLength: 32
example: CPF
taxNo:
type: string
x-stoplight:
id: bco4s997cv6h2
description: |-
税号，参见[各国税类型和税号规则]
注：巴西国家该字段必填，为巴西身份证号
example: 123.456.789-09
address:
type: string
x-stoplight:
id: gxfk4p7ms2t14
description: 用户地址
maxLength: 1024
example: '10 Anson Road, #25-08 International Plaza'
city:
type: string
x-stoplight:
id: 4uvrf6vx7rb5i
description: 用户所在城市
maxLength: 64
example: Singapore
region:
type: string
x-stoplight:
id: 9xmtccs4gi53k
description: 用户所在区域
maxLength: 64
example: Central
zipCode:
type: string
x-stoplight:
id: w2m1dzlj24wty
description: 邮编
maxLength: 32
example: '079903'
clientIp:
type: string
x-stoplight:
id: lo1tw62t0pbgk
description: 用户IP地址，须为标准IPv4或IPv6格式。
example: 203.0.113.42
userAgent:
type: string
x-stoplight:
id: 7ki5xbyvydjsr
description: 用户浏览器信息
example: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS
X) AppleWebKit/605.1.15
paymentTokenID:
type: string
x-stoplight:
id: z5dc8remtibec
description: Payloco token，授权成功后支付
example: ptok_9f1c2e7a6b5d4c3a8e0f1b2c3d4e5f6a
tokenForFutureUse:
type: boolean
x-stoplight:
id: b3wara71jm0ac
description: true代表用户已授权进行支付信息绑定，用于后续使用，默认为false
merchantInitiated:
type: string
x-stoplight:
id: 09w154vsb6hd9
description: 代表是否为MIT交易，不传默认为false
example: 'false'
mitType:
x-stoplight:
id: eeentg6lo28dn
description: 代扣类型。
enum:
- SCHEDULED
- UNSCHEDULED
info3DSecure:
type: object
x-stoplight:
id: 4l2s8xfjhkz2n
properties:
threeDSVersion:
type: string
x-stoplight:
id: 42i8u468boyy8
description: 3ds版本号
example: 2.2.0
eci:
type: string
x-stoplight:
id: fu560s5vsezg2
description: eci值
example: '05'
cavv:
type: string
x-stoplight:
id: i7myxnpwkfiol
description: cavv值
example: AAABBBCCCDDDEEE111222333
dsTransactionId:
type: string
x-stoplight:
id: 40x7kywh5l41r
description: dsTransactionId值
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
xid:
type: string
x-stoplight:
id: 7izegttvghadu
description: xid值
example: MDAwMDAwMDAwMDAwMDAwMDAwWDEyMw==
carrierId:
type: string
x-stoplight:
id: u5aac0v6nmu4v
description: 发生交易的网站域名或者APP名称
example: qiye
goodsDetails:
type: array
x-stoplight:
id: s0lrtco659at7
description: >-
商品信息，支持传多个。注意：电商场景下需要上送。如果传入该对象，则内层必填字段必须传入
items:
x-stoplight:
id: nrwss60tbxxy1
type: object
properties:
goodsId:
type: string
x-stoplight:
id: ywiyel9nyb8bi
description: 商品ID
example: SKU_1000001
goodsName:
type: string
x-stoplight:
id: 069o58xi8aaxn
description: 商品名称
example: Wireless Bluetooth Earbuds
quantity:
type: string
x-stoplight:
id: g5ezbkefe9tnx
description: 商品数量
example: '2'
price:
type: string
x-stoplight:
id: nrawbvpxqng89
description: 商品价格，商户系统的报价
example: '59.99'
goodsCurrency:
type: string
x-stoplight:
id: cvuik65kdsxq8
description: 商品报价币种，大写字母
example: USD
showUrl:
type: string
x-stoplight:
id: 5m5ihqxwhgt8v
description: 商品链接地址。注：电商场景下需要上送。
example: https://example.com/product/sku_1000001
goodsCategory:
type: string
x-stoplight:
id: fes0v7mvlfawn
description: 商品类别。注：电商场景下需要上送。
example: Electronics
subMerchant:
type: object
x-stoplight:
id: yc47utxxsdq38
description: 二级商户信息 平台类商户需要上送子商户信息
properties:
subMerchantNo:
type: string
x-stoplight:
id: 7h4kqety3of90
description: 二级商户号
example: SM202604270001
shippingInfo:
type: object
x-stoplight:
id: 7n1sn08et1cpk
description: >-
邮寄信息 注：电商场景下需要上送。如果传入该对象，则内层必填字段必须传入
properties:
firstName:
type: string
x-stoplight:
id: ascj5asj6pko6
description: 收货人中间名
example: John
middleName:
type: string
x-stoplight:
id: 2pglsh98jtbn6
description: 收货人中间名
lastName:
type: string
x-stoplight:
id: bbwbab6xkgiee
description: 收货人姓
example: John
phoneNo:
type: string
x-stoplight:
id: dyjp2t0lpekzv
description: 收货人手机号
example: '+6598765432'
email:
type: string
x-stoplight:
id: 6qeb03tc22u06
description: 收货邮箱地址
example: john.tan@example.com
address1:
type: string
x-stoplight:
id: m3sgblxrnfu3b
description: 收货地址1
example: 10 Anson Road
city:
type: string
x-stoplight:
id: gsfibl5ut9r60
description: 收货地址所在城市
example: Singapore
region:
type: string
x-stoplight:
id: jakaqe4yvjmd6
description: 收货地址所在区域
example: Central
state:
type: string
x-stoplight:
id: vmslgt20j9nai
description: 收货地址所在州 送货到加拿大，美国，英国，澳大利亚时必填
country:
type: string
x-stoplight:
id: v5ckmmdddu16q
description: 收货地址邮编
example: SG
zipCode:
type: string
x-stoplight:
id: 1p0ew98m6oy7k
description: 收货地址邮编
example: '079903'
address2:
type: string
x-stoplight:
id: xgnrub1phpie0
description: 收货地址2
example: '#25-08 International Plaza'
address3:
type: string
x-stoplight:
id: c7fyg34lgf1mn
description: 收货地址3
billingInfo:
type: object
x-stoplight:
id: 02eeelsm1le3j
description: 信用卡账单信息。注：如果传入该对象，则内层必填字段必须传入
properties:
firstName:
type: string
x-stoplight:
id: kl7zx1voul9lk
description: 账单人名
example: John
middleName:
type: string
x-stoplight:
id: v2ne82ht6gwe8
description: 账单人中间名
example: Michael
lastName:
type: string
x-stoplight:
id: gsuena1kopdao
description: 账单人姓
example: Tan
phoneNo:
type: string
x-stoplight:
id: nmgsuxg4c18x8
description: 账单人手机号
example: '+6591234567'
email:
type: string
x-stoplight:
id: y4fovgyuafkzu
description: 账单邮箱地址
example: john.tan@example.com
address1:
type: string
x-stoplight:
id: 9qakxptz4zmfb
description: 账单地址1
example: 10 Anson Road
city:
type: string
x-stoplight:
id: iofbpp8iagmbw
description: 账单地址所在城市
example: Singapore
country:
type: string
x-stoplight:
id: 880satk5p2427
description: 账单地址所在国家
example: SG
region:
type: string
x-stoplight:
id: y4rznjnhfeory
description: 账单地址所在区域
example: Central
state:
type: string
x-stoplight:
id: f96dtqees2822
description: 账单地址所在州 送货到加拿大，美国，英国，澳大利亚时需要上送
zipCode:
type: string
x-stoplight:
id: ym6ojf6q4vfs9
description: 账单地址邮编
example: '079903'
address2:
type: string
x-stoplight:
id: ddypp479zp9c8
description: 账单地址2
example: '#25-08 International Plaza'
address3:
type: string
x-stoplight:
id: ub2mit56kh2lr
description: 账单地址3
envInfo:
type: object
x-stoplight:
id: sdjcosm60hsel
description: 设备信息
properties:
deviceId:
type: string
x-stoplight:
id: wkchtd3iqca85
description: 商户设备唯一标识
example: a3f5c9e2-7b4d-4c1a-9f6e-2d8b7a1c0e5f
deviceLanguage:
type: string
x-stoplight:
id: mrgy8lf876g3j
description: 设备默认语言
example: en-US
screenHeight:
type: string
x-stoplight:
id: n2kvrmic9jft6
description: 设备高度
example: '956'
screenWidth:
type: string
x-stoplight:
id: 72sg0cfns6h95
description: 设备宽度
example: '440'
userAgent:
type: string
x-stoplight:
id: 4ghcrzafaktos
example: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)
AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0
Mobile/15E148 Safari/604.1
language:
type: string
x-stoplight:
id: opun2mtngokz0
description: |-
收银台页面语言。
优先级：用户上次使用的语言 > 用户浏览器语言 > 用户ip国家语言 > 商户下单传的语言 > 默认EN
example: EN
riskParams:
type: object
x-stoplight:
id: zk8r3lzec0ldf
description: 详见风控业务数据：[商户上送信息]，该部分信息通常作为定制风控的补充信息，如未开通定制风控可不填。
terminalType:
x-stoplight:
id: nunj02lhf9hm5
description: 设备终端，WEB，WAP，APP
example: APP
enum:
- WEB
- WAP
- APP
default: APP
osType:
type: string
x-stoplight:
id: n4jxw2eyutgxr
description: 设备操作系统，当设备终端为Wap和App时，设备操作系统可以为ANDROID或IOS
example: ANDROID
reference:
type: string
x-stoplight:
id: qedczm8pqftfv
description: 商户自定义附加数据，可支持商户自定义并在响应中返回
example: goods reference
frontCallbackUrl:
type: string
x-stoplight:
id: luabzfc4uvi5a
description: >-
商户指定的跳转URL，用户完成支付后会被跳转到该地址，以http/https开头或者商户应用的scheme地址，纯API支付下frontCallbackUrl是必填的，用于支持需要跳转外部的异步交易
example: https://www.google.com
format: uri
notifyUrl:
type: string
x-stoplight:
id: ubd317dpd35uz
description: >-
服务端回调通知URL，以http/https开头
可以通过MerchantDashboard平台配置商户通知地址，如果交易中上送，则以交易为准，即优先使用接口中传的url。注：如商户平台未配置通知地址，交易也没上送地址，则无法进行回调通知
example: https://www.google.com
format: uri
subscriptionPlan:
type: object
x-stoplight:
id: eyfsoj45qvad3
description: 订阅计划信息
properties:
subscriptionNo:
type: string
x-stoplight:
id: nuyo0tns28alf
description: |
通过Payloco创建订阅计划后生成的订阅单号，激活订阅计划时必传
example: SUB_202604270001
x-User: null
x-stoplight:
id: f24lm04yvo6h0
examples:
- charset: UTF-8
version: 2.0.0
signType: RSA
memberId: '2023010558663764'
merchantId: '2023010558663764'
requestTime: '2024-05-24T14:29:32.682+08:00'
keyVersion: '1'
data:
merchantOrderId: ORD202604231532478921
integrate: Direct
captureMode: MANUAL
subject: Iphone 16
totalAmount: '10.01'
currency: USD
country: US
userId: U123333333
expireTime: '1800'
paymentDetail:
paymentMethodType: WALLET
targetOrg: KLARNA
payAccountInfo:
- accountNo: 125@gmail.com
accountNoType: EMAIL
cardInfo:
cardIdentifierNo: '4111111111111111'
cardHolderFullName: John Tan
cardExpirationMonth: '12'
cardExpirationYear: '28'
cvv: '123'
stored: 'true'
dynamic3DS: 'true'
buyerInfo:
firstName: John
middleName: Michael
email: john.tan@example.com
lastName: Tan
phoneNo: '+6591234567'
phoneNoRegion: '+65'
idType: PASSPORT
idNo: E12345678
taxType: CPF
taxNo: 123.456.789-09
address: '10 Anson Road, #25-08 International Plaza'
city: Singapore
region: Central
zipCode: '079903'
clientIp: 203.0.113.42
userAgent: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)
AppleWebKit/605.1.15
paymentTokenID: ptok_9f1c2e7a6b5d4c3a8e0f1b2c3d4e5f6a
tokenForFutureUse: true
merchantInitiated: 'false'
mitType: SCHEDULED
info3DSecure:
threeDSVersion: 2.2.0
eci: '05'
cavv: AAABBBCCCDDDEEE111222333
dsTransactionId: f47ac10b-58cc-4372-a567-0e02b2c3d479
xid: MDAwMDAwMDAwMDAwMDAwMDAwWDEyMw==
carrierId: qiye
goodsDetails:
- goodsId: SKU_1000001
goodsName: Wireless Bluetooth Earbuds
quantity: '1'
price: '10.01'
goodsCurrency: USD
showUrl: https://example.com/product/sku_1000001
goodsCategory: Electronics
subMerchant:
subMerchantNo: SM202604270001
shippingInfo:
firstName: John
middleName: string
lastName: John
phoneNo: '+6598765432'
email: john.tan@example.com
address1: 10 Anson Road
city: Singapore
region: Central
state: string
country: SG
zipCode: '079903'
address2: '#25-08 International Plaza'
address3: string
billingInfo:
firstName: John
middleName: Michael
lastName: Tan
phoneNo: '+6591234567'
email: john.tan@example.com
address1: 10 Anson Road
city: Singapore
country: SG
region: Central
state: string
zipCode: '079903'
address2: '#25-08 International Plaza'
address3: string
envInfo:
deviceId: a3f5c9e2-7b4d-4c1a-9f6e-2d8b7a1c0e5f
deviceLanguage: en-US
screenHeight: '956'
screenWidth: '440'
userAgent: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)
AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0
Mobile/15E148 Safari/604.1
language: EN
riskParams: {}
terminalType: APP
osType: ANDROID
reference: goods reference
frontCallbackUrl: https://www.google.com
notifyUrl: https://www.google.com
subscriptionPlan:
subscriptionNo: SUB_202604270001
PayResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: object
required:
- status
- merchantId
- merchantOrderId
properties:
status:
x-stoplight:
id: mf24er8zlib3x
description: 交易状态
enum:
- SUCCESS
- PENDING
- FAILED
- CLOSED
merchantId:
type: string
description: 商户号
example: '2023010558663764'
x-stoplight:
id: yef8r7clzqh1e
merchantOrderId:
type: string
description: 商户订单号
x-stoplight:
id: qntuktftorgju
example: '167812677182888888'
orderId:
type: string
description: 交易订单号
example: TR1658354573473091584
currency:
type: string
description: >-
订单币种[ISO4217](https://www.iso.org/standard/46121.html)币种的字母码
eg. USD, CNY, EUR
example: USD
totalAmount:
type: string
description: 交易金额
example: 10.01
x-stoplight:
id: aukkws3iym1g2
nextAction:
$ref: '#/components/schemas/NextAction'
x-stoplight:
id: vmkapvn91zuik
description: 商家下一步行动
x-examples:
Example 1:
isSuccess: true
errCode: '00000003'
errMessage: 处理中
status: PENDING
traceId: 33fae7b7aed1233f
data:
orderId: '1551424900319940608'
merchantNo: '2001000000002036'
merchantOrderId: '20220725123000'
currency: HKD
payMethodResponse:
isRedirect: 'NO'
redirectMethod: GET
termUrl: normalUrl
redirectParam: {}
codeUrl: weixin://wxpay/bizpayurl?pr=waUjCuPzz
transAmt: '3.01'
x-stoplight:
id: p78imd1m8s07h
examples:
- code: '00000003'
message: 处理中
traceId: 33fae7b7aed1233f
data:
status: SUCCESS
merchantId: '2023010558663764'
merchantOrderId: '167812677182888888'
orderId: TR1658354573473091584
currency: USD
totalAmount: '10.01'
nextAction:
contentType: application/json
data: {}
method: GET
qrcode: weixin://wxpay/bizpayurl?pr=waUjCuPzz
type: render_qrcode
url: https://www.google.com
title: ''
BaseRequest:
type: object
x-stoplight:
id: 4hhyl9c4c4skc
x-examples:
Example 1:
charset: UTF-8
version: 2.0.0
transType: string
accessType: PAY
signType: RSA
memberId: stringstri
merchantId: stringstri
required:
- charset
- version
- signType
- memberId
- merchantId
- requestTime
- keyVersion
properties:
charset:
type: string
description: 交互数据的编码【utf-8】
default: UTF-8
examples:
- UTF-8
version:
type: string
description: "接口版本，当前版本为【2.0.0】,目前只能传2.0.0，不能不传\t"
example: 2.0.0
maxLength: 8
signType:
type: string
description: 报文签名类型
example: RSA
memberId:
type: string
description: 机构号
example: '2023010558663764'
merchantId:
type: string
description: 商户号
example: '2023010558663764'
maxLength: 32
requestTime:
type: string
x-stoplight:
id: njc3cd378x9h1
description: >-
请求时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ssSSS+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC
8小时，即北京时间）。例如：2026-05-20T13:29:35.262+08:00表示，北京时间2026年5月20日13点29分35秒。
example: '2026-05-24T14:29:32.682+08:00'
maxLength: 32
keyVersion:
type: string
x-stoplight:
id: k14bjqd1dyfwh
description: 密钥版本 当前值为：1
maxLength: 8
example: '1'
examples:
- charset: UTF-8
version: 2.0.0
signType: RSA
memberId: '2023010558663764'
merchantId: '2023010558663764'
requestTime: '2026-05-24T14:29:32.682+08:00'
keyVersion: '1'
PayAccountInfo:
title: PayAccountInfo
x-stoplight:
id: pvhsyizyrbrhz
type: object
properties:
accountNo:
type: string
x-stoplight:
id: q9fh16rmt6m78
description: 用户在该支付方式下的目标机构注册的支付账号
example: '12345567777789'
accountNoType:
x-stoplight:
id: 7frglmsndhte6
enum:
- EMAIL
- PHONE
- ACCOUNT
example: EMAIL
description: 账号类型：EMAIL，PHONE，ACCOUNT
BaseResponse:
type: object
x-stoplight:
id: 4lloo3c92r1n3
x-examples:
Example 1:
isSuccess: true
errCode: '00000003'
errMessage: 处理中
status: PENDING
traceId: 33fae7b7aed1233f
examples:
- code: '00000000'
message: SUCCESS
traceId: 33fae7b7aed1233f
required:
- code
- message
- traceId
properties:
code:
type: string
description: |
响应状态码，’00000000’代表成功。’00000003’代表受理中,只代表接口请求成功，不代表订单状态。
example: '00000003'
x-stoplight:
id: zocifrrgwx3bv
message:
type: string
description: |+
返回描述，’SUCCESS.’ 。只代表接口请求成功，不代表订单状态。
example: SUCCESS
x-stoplight:
id: smef8x7rur0cy
traceId:
type: string
description: "请求消息唯一标识。traceId为本次调用产生的流水号，接口调用异常，可以提供此流水号用于排查问题。\t"
example: 33fae7b7aed1233f
NextAction:
title: NextAction
x-stoplight:
id: 68kg586g3p6fj
type: object
properties:
contentType:
type: string
x-stoplight:
id: ciossef4fygn3
description: 当请求方法为 POST 时的内容类型。如果未指定，内容类型应为 application/json。
example: application/json
data:
type: object
x-stoplight:
id: 80srw2n6ibr3r
description: 可用于完成此操作的其他数据
method:
x-stoplight:
id: q3q3wp6e9hju0
enum:
- GET
- POST
description: 当操作类型为重定向（redirect）时使用的重定向方法。可选值为 GET 或 POST。
qrcode:
type: string
x-stoplight:
id: o3ul8u5di57dc
description: arcode
example: weixin://wxpay/bizpayurl?pr=waUjCuPzz
type:
x-stoplight:
id: 4rel21zd95312
enum:
- render_qrcode
- call_sdk
- redirect
- redirect_iframe
- request_pin
description: >-
下一步操作类型。可选值包括：render_qrcode、call_sdk、redirect、redirect_iframe 或
request_pin。
example: render_qrcode
default: render_qrcode
url:
type: string
x-stoplight:
id: i5jnxmy91z8uu
description: 重定向网址
example: https://www.google.com
securitySchemes:
signature:
type: apiKey
description: |-
## 加签（Signature）
加签是 Payloco 开放平台与商户之间用于保障报文**完整性**和**防篡改**的安全机制。
### 适用场景
1. **商户请求 Payloco**：商户使用**自身私钥**对请求报文进行加签。
2. **Payloco 返回响应**：商户使用 **Payloco 公钥** 对响应报文进行验签。
### 加签规则（商户请求端）
商户需对 HTTP 请求的 **Body** 进行签名，具体步骤如下：
### 1. 计算签名（SHA256withRSA）
```java
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(merchantPrivateKey);
// 必须使用 UTF-8 编码
byte[] bodyBytes = requestBody.getBytes(StandardCharsets.UTF_8);
signature.update(bodyBytes);
byte[] signedBytes = signature.sign();
```
### 2. 将加签内容进行 Base64 编码；
```java
String signature = Base64.getEncoder().encodeToString(signedHash);
```
### 3. 将编码后的内容放在请求头部 signature 参数中。
```java
POST /v2/payments/open/api/pay HTTP/1.1
Content-Type: application/json
signature: MIIC8jCCAdqgAwIBAgI...
```
name: signature
in: header
````