> ## 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 2024-03-31_zh-CN.yaml post /v2/payments/open/api/checkout
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/checkout:
parameters: []
post:
tags:
- 收单
summary: 收银台-下单
operationId: post-v2-payments-open-api-checkout
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/PayCheckout'
examples:
Cashier Example:
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
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
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PayCheckoutResponse'
examples:
Example 1:
value:
code: '00000003'
message: 处理中
traceId: 33fae7b7aed1233f
data:
status: SUCCESS
merchantId: '2023010558663764'
merchantOrderId: '167812677182888888'
orderId: TR1658354573473091584
currency: USD
totalAmount: '10.01'
nextAction:
method: GET
type: redirect
url: >-
https://checkout1.uat.payloco.com/standalone/checkout?intent_id=int1973308631638400&client_secret=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnQxOTczMzA4NjMxNjM4NDAwIiwiaWF0IjoxNzg1ODMwMTE0LCJleHAiOjE3ODY4MzAxMTQsImtleSI6IjA1NmM3YjQxLWJmNTAtNDk1Mi1iZjdlLTZkYzNiOTFmYzM2OSIsInRhcmdldE9yZyI6IiIsImNvdW50cnlfY29kZSI6IklEIiwib3JkZXJBbW91bnQiOiIxMDAwMC4wMCIsIm9yZGVyQ3VycmVuY3kiOiJJRFIiLCJtZXJjaGFudElkIjoiODUxMjczMDAwMDcyIiwibWVyY2hhbnRPcmRlcklkIjoiMTc4NTgzMDEwOTI2NSIsInR4bk9yZGVySWQiOiJpbnQxOTczMzA4NjMxNjM4NDAwIn0.6njUs7zNuL3HFvGTS6Y_TwyoKZWJ9se9PF-hDaDQRvA&mode=payment¤cy=IDR&timeOut=10000000&targetOrg=&appVersion=v1.938.2
components:
schemas:
PayCheckout:
title: PayCheckout
x-stoplight:
id: q85genv8sjqss
allOf:
- $ref: '#/components/schemas/BaseRequest'
- type: object
properties:
data:
type: object
description: 请求数据体
required:
- merchantOrderId
- integrate
- subject
- totalAmount
- currency
- country
- paymentDetail
- terminalType
properties:
merchantOrderId:
type: string
description: >-
商户订单号，唯一标识商户的一笔交易，不能重复，只能包含字母、数字、下划线且不支持大小写敏感。如：AAA和AAa被认为是相同的。
maxLength: 64
example: ORD202604231532478921
integrate:
description: 商户自行进行付款方支付信息的收集后，传送给Payloco进行交易处理,需传入参数：Cashier
example: Cashier
enum:
- Cashier
- Direct
- DropIn
- PayLink
- Token
default: Cashier
captureMode:
type: string
description: 请款模式：MANUAL
example: MANUAL
subject:
type: string
description: 订单标题或产品信息，会展示在用户支付页面，避免使用纯数字。注：巴西钱包Pix不能超过43位
maxLength: 256
example: Iphone 16
totalAmount:
type: string
description: >-
付款的主要金额，金额的单位为元（例如，65.40 USD 代表 65.40 美元,1000 JPY
代表1000日元）。各个国家币种支持的小数位详见[ISO4217](https://www.iso.org/standard/64758.html)币种的字母码
example: '10.01'
currency:
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:
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
description: 商户内部的用户Id，需要保证每个ID唯一性。
maxLength: 64
example: U123333333
expireTime:
type: string
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
description: 支付信息
properties:
paymentMethodType:
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:
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:
description: 支付账号，部分支付方式下的目标机构需要上送用户在该目标机构的支付账号信息。
type: array
items:
$ref: '#/components/schemas/PayAccountInfo'
cardInfo:
type: object
description: 卡信息
properties:
cardIdentifierNo:
type: string
description: 卡号
maxLength: 19
example: '4111111111111111'
x-stoplight:
id: x1oplvxxtnorx
cardHolderFullName:
type: string
description: 持卡人姓名
maxLength: 64
example: John Tan
x-stoplight:
id: tqmu2tbtp8g14
cardExpirationMonth:
type: string
description: 卡有效期-月，两位月份
maxLength: 2
example: '12'
cardExpirationYear:
type: string
description: "卡有效期-年，只取后两位年份\t"
maxLength: 2
example: '28'
cvv:
type: string
description: 卡cvv，Visa和MasterCard为3位数字，AEMX为4位数字
maxLength: 4
example: '123'
stored:
type: string
description: |-
代表该笔卡支付交易是否已存卡。
已存卡：Y
未存卡：不填或者其他值
maxLength: 4
example: 'true'
dynamic3DS:
type: string
description: >-
动态3ds（参数不区分大小写）
do3DS：为此订单执行3DS Secure
no3DS：不为此订单执行3DS Secure
ext3DS：使用外部3DS结果，适用于已经对接了其他3DS服务的商户，指定该值时，则必须同时传入info3DSecure对象
未传或传入其他值，由Payloco判断是否发起3ds
maxLength: 64
example: 'true'
buyerInfo:
type: object
description: 用户基本信息
properties:
firstName:
type: string
description: >-
用户名 注：巴西HIPERCAR、ELO卡支付时必传
maxLength: 64
example: John
middleName:
type: string
description: 用户中间名
maxLength: 64
example: Michael
email:
type: string
description: >-
用户邮箱 注：巴西HIPERCAR、ELO卡支付时必传
maxLength: 255
example: john.tan@example.com
lastName:
type: string
description: >-
用户姓 注：巴西HIPERCAR、ELO卡支付时必传
maxLength: 64
example: Tan
phoneNo:
type: string
description: 用户手机号 注：土耳其卡支付时必传
maxLength: 32
example: '+6591234567'
phoneNoRegion:
type: string
description: 手机号区号 注：土耳其卡支付时必传
maxLength: 16
example: '+65'
idType:
type: string
description: 证件类型
maxLength: 32
example: PASSPORT
idNo:
type: string
description: 证件号
maxLength: 64
example: E12345678
taxType:
type: string
description: "税类型，参见【[各国税类型和税号规则]\t\n注：巴西国家该字段必须传入CPF"
maxLength: 32
example: CPF
taxNo:
type: string
description: |-
税号，参见[各国税类型和税号规则]
注：巴西国家该字段必填，为巴西身份证号
example: 123.456.789-09
address:
type: string
description: 用户地址
maxLength: 1024
example: '10 Anson Road, #25-08 International Plaza'
city:
type: string
description: 用户所在城市
maxLength: 64
example: Singapore
region:
type: string
description: 用户所在区域
maxLength: 64
example: Central
zipCode:
type: string
description: 邮编
maxLength: 32
example: '079903'
clientIp:
type: string
description: 用户IP地址，须为标准IPv4或IPv6格式。
example: 203.0.113.42
userAgent:
type: string
description: 用户浏览器信息
example: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS
X) AppleWebKit/605.1.15
paymentTokenID:
type: string
description: Payloco token，授权成功后支付
example: ptok_9f1c2e7a6b5d4c3a8e0f1b2c3d4e5f6a
tokenForFutureUse:
type: boolean
description: true代表用户已授权进行支付信息绑定，用于后续使用，默认为false
merchantInitiated:
type: string
description: 代表是否为MIT交易，不传默认为false
example: 'false'
mitType:
description: 代扣类型。
enum:
- SCHEDULED
- UNSCHEDULED
info3DSecure:
type: object
properties:
threeDSVersion:
type: string
description: 3ds版本号
example: 2.2.0
eci:
type: string
description: eci值
example: '05'
cavv:
type: string
description: cavv值
example: AAABBBCCCDDDEEE111222333
dsTransactionId:
type: string
description: dsTransactionId值
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
xid:
type: string
description: xid值
example: MDAwMDAwMDAwMDAwMDAwMDAwWDEyMw==
carrierId:
type: string
description: 发生交易的网站域名或者APP名称
example: qiye
goodsDetails:
type: array
description: >-
商品信息，支持传多个。注意：电商场景下需要上送。如果传入该对象，则内层必填字段必须传入
items:
type: object
properties:
goodsId:
type: string
description: 商品ID
example: SKU_1000001
goodsName:
type: string
description: 商品名称
example: Wireless Bluetooth Earbuds
quantity:
type: string
description: 商品数量
example: '2'
price:
type: string
description: 商品价格，商户系统的报价
example: '59.99'
goodsCurrency:
type: string
description: 商品报价币种，大写字母
example: USD
showUrl:
type: string
description: 商品链接地址。注：电商场景下需要上送。
example: https://example.com/product/sku_1000001
goodsCategory:
type: string
description: 商品类别。注：电商场景下需要上送。
example: Electronics
subMerchant:
type: object
description: 二级商户信息 平台类商户需要上送子商户信息
properties:
subMerchantNo:
type: string
description: 二级商户号
example: SM202604270001
shippingInfo:
type: object
description: >-
邮寄信息 注：电商场景下需要上送。如果传入该对象，则内层必填字段必须传入
properties:
firstName:
type: string
description: 收货人中间名
example: John
middleName:
type: string
description: 收货人中间名
lastName:
type: string
description: 收货人姓
example: John
phoneNo:
type: string
description: 收货人手机号
example: '+6598765432'
email:
type: string
description: 收货邮箱地址
example: john.tan@example.com
address1:
type: string
description: 收货地址1
example: 10 Anson Road
city:
type: string
description: 收货地址所在城市
example: Singapore
region:
type: string
description: 收货地址所在区域
example: Central
state:
type: string
description: 收货地址所在州 送货到加拿大，美国，英国，澳大利亚时必填
country:
type: string
description: 收货地址邮编
example: SG
zipCode:
type: string
description: 收货地址邮编
example: '079903'
address2:
type: string
description: 收货地址2
example: '#25-08 International Plaza'
address3:
type: string
description: 收货地址3
billingInfo:
type: object
description: 信用卡账单信息。注：如果传入该对象，则内层必填字段必须传入
properties:
firstName:
type: string
description: 账单人名
example: John
middleName:
type: string
description: 账单人中间名
example: Michael
lastName:
type: string
description: 账单人姓
example: Tan
phoneNo:
type: string
description: 账单人手机号
example: '+6591234567'
email:
type: string
description: 账单邮箱地址
example: john.tan@example.com
address1:
type: string
description: 账单地址1
example: 10 Anson Road
city:
type: string
description: 账单地址所在城市
example: Singapore
country:
type: string
description: 账单地址所在国家
example: SG
region:
type: string
description: 账单地址所在区域
example: Central
state:
type: string
description: 账单地址所在州 送货到加拿大，美国，英国，澳大利亚时需要上送
zipCode:
type: string
description: 账单地址邮编
example: '079903'
address2:
type: string
description: 账单地址2
example: '#25-08 International Plaza'
address3:
type: string
description: 账单地址3
envInfo:
type: object
description: 设备信息
properties:
deviceId:
type: string
description: 商户设备唯一标识
example: a3f5c9e2-7b4d-4c1a-9f6e-2d8b7a1c0e5f
deviceLanguage:
type: string
description: 设备默认语言
example: en-US
screenHeight:
type: string
description: 设备高度
example: '956'
screenWidth:
type: string
description: 设备宽度
example: '440'
userAgent:
type: string
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
description: |-
收银台页面语言。
优先级：用户上次使用的语言 > 用户浏览器语言 > 用户ip国家语言 > 商户下单传的语言 > 默认EN
example: EN
riskParams:
type: object
description: 详见风控业务数据：[商户上送信息]，该部分信息通常作为定制风控的补充信息，如未开通定制风控可不填。
terminalType:
description: 设备终端，WEB，WAP，APP
example: APP
enum:
- WEB
- WAP
- APP
default: APP
osType:
type: string
description: 设备操作系统，当设备终端为Wap和App时，设备操作系统可以为ANDROID或IOS
example: ANDROID
reference:
type: string
description: 商户自定义附加数据，可支持商户自定义并在响应中返回
example: goods reference
frontCallbackUrl:
type: string
description: >-
商户指定的跳转URL，用户完成支付后会被跳转到该地址，以http/https开头或者商户应用的scheme地址，纯API支付下frontCallbackUrl是必填的，用于支持需要跳转外部的异步交易
example: https://www.google.com
format: uri
notifyUrl:
type: string
description: >-
服务端回调通知URL，以http/https开头
可以通过MerchantDashboard平台配置商户通知地址，如果交易中上送，则以交易为准，即优先使用接口中传的url。注：如商户平台未配置通知地址，交易也没上送地址，则无法进行回调通知
example: https://www.google.com
format: uri
subscriptionPlan:
type: object
description: 订阅计划信息
properties:
subscriptionNo:
type: string
description: |
通过Payloco创建订阅计划后生成的订阅单号，激活订阅计划时必传
example: SUB_202604270001
x-User: null
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: '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
PayCheckoutResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: object
required:
- status
- merchantId
- merchantOrderId
properties:
status:
description: 交易状态
enum:
- SUCCESS
- PENDING
- FAILED
- CLOSED
merchantId:
type: string
description: 商户号
example: '2023010558663764'
merchantOrderId:
type: string
description: 商户订单号
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
nextAction:
$ref: '#/components/schemas/NextCheckoutAction'
description: 商家下一步行动
x-stoplight:
id: x3tf88jue3sd6
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'
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
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
NextCheckoutAction:
title: NextCheckoutAction
x-stoplight:
id: l7ljlss2mml1f
type: object
properties:
method:
enum:
- GET
- POST
description: 当操作类型为重定向（redirect）时使用的重定向方法。可选值为 GET 或 POST。
type:
enum:
- render_qrcode
- call_sdk
- redirect
- redirect_iframe
- request_pin
description: >-
下一步操作类型。可选值包括：render_qrcode、call_sdk、redirect、redirect_iframe 或
request_pin。
example: redirect
default: redirect
url:
type: string
description: 重定向网址
example: >-
https://checkout1.payloco.com/standalone/checkout?intent_id=int1973308631638400&client_secret=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJpbnQxOTczMzA4NjMxNjM4NDAwIiwiaWF0IjoxNzg1ODMwMTE0LCJleHAiOjE3ODY4MzAxMTQsImtleSI6IjA1NmM3YjQxLWJmNTAtNDk1Mi1iZjdlLTZkYzNiOTFmYzM2OSIsInRhcmdldE9yZyI6IiIsImNvdW50cnlfY29kZSI6IklEIiwib3JkZXJBbW91bnQiOiIxMDAwMC4wMCIsIm9yZGVyQ3VycmVuY3kiOiJJRFIiLCJtZXJjaGFudElkIjoiODUxMjczMDAwMDcyIiwibWVyY2hhbnRPcmRlcklkIjoiMTc4NTgzMDEwOTI2NSIsInR4bk9yZGVySWQiOiJpbnQxOTczMzA4NjMxNjM4NDAwIn0.6njUs7zNuL3HFvGTS6Y_TwyoKZWJ9se9PF-hDaDQRvA&mode=payment¤cy=IDR&timeOut=10000000&targetOrg=&appVersion=v1.938.2
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
````