Pre-Authorization

curl --request POST \ --url https://gate.dev.payloco.com/gateway/v1/payments/open/api/preAuth \ --header 'Content-Type: application/json' \ --header 'signature: <api-key>' \ --data ' { "charset": "UTF-8", "version": "2.0.0", "transType": "PAY", "accessType": "s2s", "signType": "RSA", "memberId": "2023010558663764", "merchantId": "2023010558663764", "threeDsType": "2.0", "deviceChannel": "string", "transChannel": "WEIXIN", "transTimeout": "string", "carrierId": "carrierId", "currency": "USD", "transAmt": "20.01", "goodsName": "Iphone15", "dcc": "DCC", "notifyUrl": "http://example.com", "redirectUrl": "http://www.gogole.com", "merchantOrderId": "20230424141154", "customerIp": "18.277.26.154", "payMode": "QRCODE", "payMethodInfo": { "cardNo": "444433******1111", "expirationMonth": "01", "expirationYear": "2026", "cvv": "123", "firstName": "Bren", "lastName": "Qiu", "phone": "18817536697" }, "merchantOrderTime": "2019-08-24T14:15:22Z", "osType": "IOS", "merchantRegion": "US", "authCode": "133788758877188822", "appId": "wxd678efh567hg6787", "openId": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o", "reqReserved": "reqReserved", "reserved": "reserved", "buyerId": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o", "address": { "zipCode": "344104", "region": "US", "city": "ShangHai", "state": "ShangHai", "phone": "18817536697", "email": "string", "address1": "Lou Lan street", "address2": "Lou Lan street 2" }, "customer": { "address": { "zipCode": "344104", "region": "US", "city": "ShangHai", "state": "ShangHai", "phone": "18817536697", "email": "string", "address1": "Lou Lan street", "address2": "Lou Lan street 2" }, "certificate": { "number": "string", "type": "string" } }, "subMerchantId": "string", "userAgent": "string", "goods": [ { "referenceGoodsId": "M1006", "goodsName": "Sample Product", "goodsCategory": "1001", "goodsQuantity": "100", "goodsUnitAmount": "100.01" } ], "store": { "storeTerminalId": "0001" }, "browserInfo": { "acceptHeader": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36", "javaEnabled": "true", "language": "en-US", "colorDepth": "160", "screenHeight": "1024", "screenWidth": "648", "browserTz": "string", "browserIp": "8.8.8.8", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36" } } '

{ "isSuccess": true, "errCode": "00000003", "errMessage": "Processing", "status": "PENDING", "traceId": "33fae7b7aed1233f", "data": { "orderId": "TR1658354573473091584", "merchantNo": "2023010558663764", "merchantOrderId": "string", "currency": "USD", "transAmt": "100.01", "payMethodResponse": { "isRedirect": "yes", "redirectMethod": "get", "termUrl": "string", "redirectParam": {}, "codeUrl": "weixin://wxpay/bizpayurl?pr=waUjCuPzz" } } }

Authorizations

signature

string

header

required

Request Signing

Request signing is used to verify the integrity of messages between the platform and merchants. Signing occurs in two scenarios:

The merchant server signs requests sent to the PayLoco open platform;
The PayLoco platform signs asynchronous notifications sent to merchants. PayLoco requires RSA private key signing and RSA public key verification. Developers must use the merchant private key to sign outgoing requests (scenario 1) and the PayLoco public key to verify incoming notifications (scenario 2).

Signing rules:

Sign request.body using the merchant private key (SHA256WithRSA: compute SHA-256 hash, then RSA-encrypt with private key to produce the digital signature);

Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
// When computing SHA256withRSA, convert byte stream with UTF-8 encoding to avoid incorrect signatures for Chinese parameters
signature.update(request.body);
byte[] signedHash = signature.sign();

Base64-encode the signed result;

String signature = Base64.getEncoder().encodeToString(signedHash);

Place the encoded value in the signature request header. Note: signing applies to request.body. When request.body is empty (e.g. query requests), no signature is required.

Body

application/json

charset

string

default:UTF-8

required

Data encoding [utf-8]

Example:

"UTF-8"

version

string

required

API version. Current version is 2.0.0. Must be 2.0.0.

Example:

"2.0.0"

transType

enum<string>

default:PAY

required

Transaction Type

Use PAY for payment transactions

Use VCC for VCC card transactions

Available options:

PAY,

CREDIT_CARD,

3D_PREAUTH_VOIDS,

3D_PREAUTH_COMPLETION,

REFUND,

VOIDS,

QUERY,

TRANSFER,

DOWNLOAD,

REGISTRATION,

FILEUPLOAD,

INQUIRYREGISTRATIONSTATUS,

AUTHORIZE,

VCC

accessType

string

default:s2s

required

API access type

Example:

"s2s"

signType

string

required

Message signature type

Example:

"RSA"

memberId

string

required

Institution ID

Example:

"2023010558663764"

merchantId

string

required

Merchant ID

Example:

"2023010558663764"

requestTime

string

required

Request time in RFC3339 format: yyyy-MM-ddTHH:mm:ss.SSSXXX. Must be within 2 minutes of current time.

Example:

"2024-05-24T14:29:32.682+08:00"

transChannel

enum<string>

required

Payment channel

Available options:

WEIXIN,

UNIONPAY,

ALIPAY_CN,

ALIPAY_HK,

GCASH,

BPI,

TNG,

BOOST,

DANA,

KAKAOPAY,

TRUEMONEY,

BRAZIL_PIX,

Ewallet_PicPay,

Khipu,

RABBIT_LINE_PAY,

ALIPAY_INSTORE,

NAVERPAY,

TOSSPAY,

GrabPay_SG,

MAYA,

BILLEASE,

GrabPay_MY,

GoPay,

OVO,

DOKU,

Dragonpay,

Konbini,

PayEasy,

GrabPay_PH

transTimeout

string

required

Order validity duration (integer, unit: minutes)

carrierId

string

required

Domain or APP name where the transaction occurs

Example:

"carrierId"

currency

string

required

Order currency ISO4217 alphabetic code e.g. USD, CNY, EUR

Example:

"USD"

transAmt

string

required

Order amount per ISO 4217 minimum unit e.g. (CNY) 110.86, (JPY) 1110. [For token creation: 0 = token only, non-0 = create token and pay]

Example:

"20.01"

merchantOrderId

string

required

Merchant order ID

Example:

"20230424141154"

payMode

enum<string>

default:QRCODE

required

Transaction mode. See Payment Methods for more details.

Available options:

QRCODE,

MICROPAY,

JSAPI,

MINIPROGRAM,

APP,

H5,

3D,

FIXEDCODE

Example:

"QRCODE"

merchantOrderTime

string<date-time>

required

Merchant order time in RFC3339 format: yyyy-MM-DDTHH:mm:ssSSSXXX. Must be within 2 minutes of current time.

Example:

"2024-07-18T17:03:02.262+08:00"

merchantRegion

string

required

Merchant region

Example:

"US"

threeDsType

string

Required for 3D transactions (example values: 1.0, 2.0)

Example:

"2.0"

deviceChannel

string

Device channel

goodsName

string

商品名称,多个商品用";"隔开

Example:

"Iphone15"

dcc

string

Whether to use DCC. Pass value: dcc

Example:

"DCC"

notifyUrl

string<uri>

Async notification URL

Required string length: 10 - 200

redirectUrl

string

Frontend callback URL

Example:

"http://www.gogole.com"

customerIp

string

User IP address

Example:

"18.277.26.154"

payMethodInfo

object

Show child attributes

osType

string

Mobile OS type (required when payMode is APP)

Example:

"IOS"

authCode

string

Authorization code (required when transChannel is WEIXIN and payMode is MICROPAY)

Example:

"133788758877188822"

appId

string

WeChat public account ID (AppID)

Example:

"wxd678efh567hg6787"

openId

string

In-app user ID (OpenID)

Example:

"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"

reqReserved

string

Merchant extension field

Example:

"reqReserved"

reserved

string

Reserved field

Example:

"reserved"

buyerId

string

Merchant user ID (required when transChannel is BRAZIL_PIX)

Example:

"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"

address

object

Show child attributes

customer

object

Show child attributes

subMerchantId

string

userAgent

string

goods

object[]

Show child attributes

store

Store · object

Show child attributes

browserInfo

object

Show child attributes

Response

200 - application/json

success

boolean

required

Whether the request succeeded

errCode

string

required

Response status code. 00000000 means success; other codes indicate failure. See system error codes.

Example:

"00000003"

errMessage

string

required

Error message

Example:

"处理中"

status

string

required

Order status (see supplementary notes)

Example:

"PENDING"

traceId

string

required

Unique request trace ID. Provide this when reporting issues for troubleshooting.

Example:

"33fae7b7aed1233f"

data

object

Show child attributes

API Documentation

Acquiring

Transfers

Issuing

WEBHOOKS

Authorizations

Request Signing

Signing rules:

Body

Response