前置组件支付

• Endpoint: POST /aggregate-pay/api/gateway/orderAndPay(for-drop-dont-copy-me)
• Tags: 收单/前置组件Drop-In

Parameters

Field	In	Type	Required	Constraints	Description
Content-Type	header	string	Yes
sign	header	string	Yes		签名信息请参考技术文档

Parameter Examples

• Content-Type: "application/json"
• sign: "FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Request Body

Content-Type: application/json

Field	Type	Required	Constraints	Description	Enum
version	string	Yes	maxLength: 8	接口版本 当前值为：1.5
keyVersion	string	Yes	maxLength: 8	密钥版本 当前值为：1
requestTime	string	Yes	maxLength: 32	请求时间，符合rfc3339规范，格式：yyyy-MM-dd'T'HH:mm:ss.SSSXXX 时间需要在当前时间两分钟内
appId	string	Yes	maxLength: 64	商户应用Id，PayerMax分配给商户应用的唯一标识
merchantNo	string	No	maxLength: 32	商户号，商户与PayerMax业务签约时生成的唯一标识
data	object	Yes		请求数据体
data.outTradeNo	string	Yes	maxLength: 64	商户订单号，唯一标识商户的一笔交易，不能重复，只能包含字母、数字、下划线且不支持大小写敏感。如：AAA和AAa被认为是相同的。
data.integrate	string	Yes	maxLength: 16	商户自行进行付款方支付信息的收集后，传送给PayerMax进行交易处理,需传入参数：Direct_Payment
data.subject	string	Yes	maxLength: 256	订单标题或产品信息，会展示在用户支付页面，避免使用纯数字。注：巴西钱包Pix不能超过43位
data.totalAmount	number	Yes		标价金额，金额的单位为元。各个国家币种支持的小数位详见【交易支持国家/地区与币种】,风控限额详见【风控行业限额】
data.currency	string	Yes	maxLength: 3	标价币种，大写字母，参见【交易支持国家/地区与币种】
data.country	string	Yes	maxLength: 2	国家代码，大写字母，参见【交易支持国家/地区与币种】
data.userId	string	Yes	maxLength: 64	商户内部的用户Id，需要保证每个ID唯一性。
data.expireTime	string	No		指定关单时间(单位：秒)。最小30分钟，最大1天。若传入则以该时间为关单时间。默认30分钟
data.referralCode	string	No	maxLength: 32	用于更精准的支付方式推荐，如设备ID、设备指纹等。
data.mitManagementUrl	string	Yes		商户管理订阅计划地址
data.subscriptionPlan	object	No
data.subscriptionPlan.subscriptionNo	string	No	maxLength: 64	订阅单号，PayerMax管理订阅计划时必传，商户管理订阅计划时不传
data.subscriptionPlan.subject	string	No		订阅主题，商户管理订阅计划时必传
data.subscriptionPlan.description	string	No		订阅描述，商户管理订阅计划时必传
data.subscriptionPlan.totalPeriods	string	No		总期数，商户管理订阅计划时必传
data.subscriptionPlan.firstPeriodStartDate ⚠️	string	No		首期扣款时间，商户管理订阅计划时必传
data.subscriptionPlan.periodRule	object	No		订阅扣款规则，商户管理订阅计划时必传
data.subscriptionPlan.periodRule.periodUnit	string	Yes		扣款周期：月（M），D(日)，W（周），Y（年）扣款，商户管理订阅计划时必传
data.subscriptionPlan.periodRule.periodCount	string	Yes		扣款频率，商户管理订阅计划时必传
data.subscriptionPlan.periodAmount	object	No		扣款金额，商户管理订阅计划时必传
data.subscriptionPlan.periodAmount.amount	number	Yes		扣款金额，商户管理订阅计划时必传
data.subscriptionPlan.periodAmount.currency	string	Yes		扣款币种，商户管理订阅计划时必传
data.subscriptionPlan.trialPeriodConfig	object	No		优惠期规则
data.subscriptionPlan.trialPeriodConfig.trialPeriodCount	string	Yes		优惠期数
data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount	object	Yes		优惠期扣款金额
data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.amount	number	No		优惠期扣款金额
data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.currency	string	No		优惠期扣款币种
data.subscriptionPlan.trialConfig	object	No		试用期参数
data.subscriptionPlan.trialConfig.trialAmount	object	Yes		试用期金额信息
data.subscriptionPlan.trialConfig.trialAmount.amount	number	Yes		试用期金额
data.subscriptionPlan.trialConfig.trialAmount.currency	string	Yes		试用期币种
data.subscriptionPlan.trialConfig.trialDays	string	Yes		试用天数
data.subscriptionPlan.prices	array[object]	Yes		价格和坐席列表
data.subscriptionPlan.prices[].priceId	string	Yes		价格ID
data.subscriptionPlan.prices[].quantity	string	Yes		坐席或数量
data.paymentDetail	object	Yes		支付信息
data.paymentDetail.buyerInfo	object	Yes		用户基本信息
data.paymentDetail.buyerInfo.clientIp	string	Yes		用户IP地址，须为标准IPv4或IPv6格式。
data.paymentDetail.buyerInfo.userAgent	string	Yes		用户浏览器信息
data.paymentDetail.paymentToken	string	No		前置组件场景，用于支付的token
data.paymentDetail.sessionKey	string	No		前置组件场景，sessionKey
data.paymentDetail.tokenForFutureUse	boolean	No		true代表用户已授权进行支付信息绑定，用于后续使用，默认为false
data.paymentDetail.merchantInitiated	boolean	No		代表是否为MIT交易，不传默认为false
data.paymentDetail.mitType	string	No		代扣类型。	SCHEDULED, UNSCHEDULED
data.subMerchant	object	No		二级商户信息 平台类商户需要上送子商户信息
data.subMerchant.subMerchantNo	string	No	maxLength: 64	二级商户号
data.language	string	No	maxLength: 16	收银台页面语言。【支持的国家与币种】 优先级：用户上次使用的语言 > 用户浏览器语言 > 用户ip国家语言 > 商户下单传的语言 > 默认EN
data.terminalType	string	Yes	maxLength: 3	设备终端，WEB，WAP，APP
data.osType	string	No		设备操作系统，当设备终端为Wap和App时，设备操作系统可以为Andriod或IOS
data.frontCallbackUrl	string	Yes	maxLength: 1024	商户指定的跳转URL，用户完成支付后会被跳转到该地址，以http/https开头或者商户应用的scheme地址，纯API支付下frontCallbackUrl是必填的，用于支持需要跳转外部的异步交易
data.notifyUrl	string	No	maxLength: 256	服务端回调通知URL，以http/https开头 可以通过MerchantDashboard平台配置商户通知地址，如果交易中上送，则以交易为准。注：如商户平台未配置通知地址，交易也没上送地址，则无法进行回调通知

Example

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-02-25T09:23:06.473+00:00",
  "appId": "6666c8b036a24579974497c2f9800001",
  "merchantNo": "020213834421284",
  "data": {
    "totalAmount": 77.44,
    "country": "HK",
    "expireTime": "7200",
    "paymentDetail": {
      "paymentToken": "332e4cc1af1740aeafe9e7df82aeb5a1",
      "buyerInfo": {
        "clientIp": "59.82.59.92",
        "userAgent": "Chrome"
      },
      "sessionKey": "86409e2c04b44536a484caa5ce3ce0e9"
    },
    "frontCallbackUrl": "http://www.frontcallbackurl.example.com",
    "subject": "GoGeal PTE. LTD.",
    "outTradeNo": "123456789",
    "notifyUrl": "http://www.notifyUrl.example.com",
    "currency": "HKD",
    "userId": "3ff0495692d152be96d84dbc9352dc57",
    "integrate": "Direct_Payment",
    "terminalType": "WEB"
  }
}

Responses

200

错误码

分类	结果码	结果描述
SYSTEM_ERROR	System is busy, please try again later.	系统错误；请联系PayerMax
REQ_TIME_OVER_TIME	requestTime effective in two minutes	请求时间与服务端偏差超过2分钟，请检查requestTime后重新发起
TOO_MANY_REQUEST	Exceed request limitation, please retry later	触发接口并发限流,请稍后重试
SIGN_VERIFY_FAILED	The signature verify failed.	签名错误；请核实签名
MERCHANT_INVALID	The merchant has been offline.	无效商户
MERCHANT_APP_INVALID	Signature key is not configured.	无效商户APP
REQUEST_TIMEOUT	Request timeout or didn't get result, If you have finished to pay, pls wait for the result.	请求超时；请联系PayerMax
UNEXPECTED_ERROR	No further information for the error, plz try it later.	未知错误；请联系PayerMax
PARAMS_INVALID	${field} length must be between ${min} and ${max},but your input value length is ${length}.Make sure all requests length is correct.	无效参数-入参字段长度不符合要求；请参考官网字段描述
PARAMS_INVALID	${field} must be ${type} , but your input is ${valueType}.Make sure all requests type is correct.	无效参数-入参字段类型不正确；请参考官网字段描述
PARAMS_INVALID	${field} is invalid,because ${field} is null.	无效参数-入参字段不能为空；请参考官网字段描述
AMOUNT_INVALID	Amount is incorrect.	无效的金额
COUNTRY_INVALID	No country support, pls re-pay.	无效的国家；可参考支持的国家和币种
CURRENCY_INVALID	currency is invalid,because currency is not defined.	无效的币种；可参考支持的国家和币种
CONTRACT_INVALID	Merchant has no activated contract, please check the contract status.	无效合约；请检查合约有效性
CONTRACT_INVALID	Merchant has not signed the contract in ${value}.	指定的国家/地区未签约；请检查合约有效性
CONTRACT_INVALID	Merchant has not signed the ${paymentMethod} payment method.	指定的支付方式未签约；请检查合约有效性
CONTRACT_INVALID	Merchant has not signed the ${targetOrg} target origination correspondingly, although you have signed the ${paymentMethod} payment method.	指定的目标机构未签约；请检查合约有效性
CONTRACT_INVALID	Merchant has not signed the ${currency} currency correspondingly, although you have signed the ${paymentMethod} payment method.	指定的支付方式有签约，但所指定的币种未签约；请检查合约有效性
CONTRACT_INVALID	Merchant has not signed the ${currency} currency correspondingly, although you have signed the ${paymentMethod} payment method and the ${targetOrg} target origination.	指定的目标机构有签约，但所指定的币种未签约；请检查合约有效性
PAYMENT_METHOD_NOT_EXIST	The payment method does not exist.	支付方式不存在；请更换其他支付方式
PAYMENT_METHOD_SUSPEND	The payment method already suspend, plz try other payment methods.	支付方式暂不可用；请更换其他支付方式
AMOUNT_LIMIT_MINIMUM	The order amount is lower than the minimum limit of the payment method.	最小金额限制
AMOUNT_LIMIT_MAXIMUM	The order amount exceeds the maximum limit of the payment method.	最大金额限制
AMOUNT_LIMIT	The amount doesn't match the payment method requirement.	金额限制
ORDER_REPEAT	The order number repeat.	订单重复
ONBOARD_ERROR	Please complete the merchant onboarding, then refresh the page.	商户未报备；请先完成报备
PAYMENT_PROCESSING	The payment is processing, pls check the result.	支付处理中；请稍后重试
PARTICIPANT_INVALID	Invalid participant.	无效分账参与方
BALANCE_INSUFFICIENT	Insufficient balance to pay, please confirm payment account available balance.	余额不足
OTP_VERIFY_LIMIT	OTP verification exceeds limit.	OTP验证超过限制
OTP_VERIFY_FAILED	OTP verification failed.	OTP验证失败
OVER_VERIFY_LIMIT	Exceeded the number of verifications.	超过验证次数
BARCODE_REFRESH_LIMIT	Over barcode refresh times.	Barcode刷新限制
BARCODE_REFRESH_FAILED	Barcode refresh failed.	Barcode刷新失败
CARD_INVALID	Make sure the card number is correct.	无效卡号
CARD_EXPIRE_DATE_INVALID	Invalid card number validity period	无效卡号有效期
CARD_HOLDER_NAME_INVALID	Invalid cardholder name	无效持卡人姓名
CVV_INVALID	Cvv is incorrect, pls check.	无效CVV
UNSUPPORT_CARD	This card don't support, please change another card.	卡不支持
ACCOUNT_INVALID	Your account is invalid or not active, please confirm and re-enter.	无效账号
PHONE_NUM_INVALID	The phone number is invalid, pls check and re-enter.	无效的电话号码
UPI_INVALID	UPI is incorrect.	无效UPI
PIN_VERIFY_LIMIT	Pin verification exceeds limit	Pin验证超过限制
PIN_INVALID	Pin is invalid	Pin无效
BANKCODE_INVALID	Invalid bank card number.	无效银行卡号
ID_NUM_INVALID	Invalid ID number	无效的证件号
EMAIL_INVALID	Your email is invalid, or your account is not active, please confirm and re-enter.	无效的Email
DOCUMENT_INVALID	Invalid document.	无效的文档
TCK_INVALID	TC Kimlik No. is incorrect.	无效的TC Kimlik No.
DATE_INVALID	The data format is error, please check.	无效的日期
PAYEE_NAME_INVALID	Your name is invalid, or does not match, please confirm and re-enter.	无效的付款人姓名
REMARK_INVALID	Invalid remark	无效的remark
CNIC_INVALID	The CNIC is incorrect, pls confirm and re-enter.	无效的CNIC
ACCOUNT_BLOCKED	Payer account/card blocked or frozen. Pls confirm payment account/card status.	账号被锁定/冻结
PAYMENT_CANCELED	payment canceled.	用户在第三方支付取消
PAYMENT_TOKEN_ID_INVALID	PaymentTokenID is invalid. Please confirm if it has been authorized and bound	paymentTokenId不合法，请检查输入是否正确，或已经解绑
MER_CONFIG_ERROR	Merchant config error. Please contact us to check your dynamic3DS configuration.	商户未开通动态3d功能
ACCOUNT_VALIDATION_INVALID	Please complete the account verification firstly.	账户未完成验证，请先完成账户验证
PAYMENT_PROCESSING_BANKTRANSFER	The previous payment is still processing, please make sure that you have made the bank transfer. Otherwise, please wait for 10 minutes to initiate a new request.	上一笔支付处理中，请确认已完成银行转账，否则请等待10分钟后重试
REQUEST_PARAM_INVALID	[amount.value] must be greater than zero	请求参数无效，金额必须大于零
INSUF_BAL_FALLBACK	Your account balance is insufficient to cover the amount. Please check your account balance.	账户余额不足，请检查账户余额
ONLY_ONE_AUTH_CHANNEL_ALLOWED	only one authorization channel is allowed	仅允许一个授权渠道
ISSUER_PAYMENT_REJECTED	Transaction failed at issuer end due to risk control. Please try using a different card or contact your issuer for more detail.	交易被发卡行风控拒绝，请更换银行卡或联系发卡行
AMOUNT_LIMIT	The amount exceeds user amount limit.	用户金额限制
AMOUNT_LIMIT	The amount exceeds the limit for per transaction limit.	单笔交易金额限制
AMOUNT_LIMIT	The amount exceeds the limit for the day.	日交易金额限制
CARD_INVALID	Expired card.	卡已过期
CARD_INVALID	Card scheme is not supported.	卡组织不支持
CARD_INVALID	Only support the card which issue by local bank, pls change local card.	仅支持本地银行卡
OTP_VERIFY_FAILED	OTP verify failed.	OTP验证失败
PAYMENT_METHOD_NOT_EXIST	Bank temporarily not available, please retry later.	银行暂时不可用，请稍后重试
PAYMENT_METHOD_SUSPEND	The payment method is in maintenance, please try again later.	支付方式维护中，请稍后重试
PAYMENT_FAILED	Transaction declined.	交易被拒绝
PAYMENT_FAILED	There is no channel to support the payment.	无可用支付渠道
PAYMENT_FAILED	Payment was not completed on time.	支付超时未完成
PAYMENT_FAILED	Provider failed to process.	支付失败
AUTHENTICATE_FAILED	Your payment was declined due to authentication failure. Please try using a different card or contact your issuer for more detail.	授权失败
AUTH_EXPIRED	The authorization has expired, pls rebind.	授权过期
AUTH_FAILED	Authorization failed.	授权失败或不存在
RISK_FAILED	This transaction was automatically blocked due to identified risk.	该交易因存在确认性风险被拦截
RISK_FAILED	The payment has reached the security limit. Please advise the user to try another payment method or attempt the transaction again later.	用户支付已达到安全限额/限次，建议用户尝试其他支付方式
RISK_FAILED	The payment has exhibited suspicious activity. We suggest that the user use a local card or disable their VPN before trying again.	检测到支付行为异常，建议用户使用本地银行卡或关闭VPN后重试
RISK_FAILED	The payment was declined due to unusual activity from the user. We recommend changing to a different payment method and attempting the transaction again.	由于交易风险较高，支付已被拒绝，建议用户更换其他支付方式
ISSUER_PAYMENT_REJECTED	Device IP restriction,please make sure your VPN is turned off when making the payment for security reason.	设备IP受限，请关闭VPN后重试
PAYMENT_REJECTED	Transaction failed at processor end due to risk control.Please try using a different payment method/card.	nan
RISK_BLACK_LIST_FAILED	The payment was declined due to high risk with the payment.	此笔交易命中商户自身侧黑名单，黑名单详情可登录MMC查询
ISSUER_PAYMENT_REJECTED	Transaction failed at issuer end due to risk control. Please contact your payment method issuer for more detail.	交易被发卡行拒绝，详情请用户咨询发卡行确认

Field	Type	Required	Constraints	Description	Enum
code	string	Yes		返回码，’APPLY_SUCCESS’代表成功。只代表接口请求成功，不代表订单状态。
msg	string	Yes		返回描述，’Success.’。只代表接口请求成功，不代表订单状态。
data	object	No		返回数据体
data.outTradeNo	string	Yes	maxLength: 64	商户订单号
data.tradeToken	string	Yes	maxLength: 64	PayerMax流水号
data.status	string	Yes	maxLength: 32	交易状态，详见【交易状态】
data.redirectUrl	string	No	maxLength: 1024	跳转地址 部分支付方式需要跳转外部完成支付。如果返回，则为3ds验证链接，需要展示在前端引导用户完成3ds验证

Response Example

{
  "code": "APPLY_SUCCESS",
  "msg": " Success.",
  "data": {
    "outTradeNo": "Test1645780876511",
    "tradeToken": "T2024062702289232000001",
    "status": "SUCCESS"
  }
}

Enum Reference

data.paymentDetail.mitType

• SCHEDULED
• UNSCHEDULED