Skip to content

纯API支付

  • Endpoint: POST /aggregate-pay/api/gateway/orderAndPay(for-auth-caputre-dont-copy-me)
  • Tags: 收单/Auth-Capture

Description

商户希望在自己的收银台上给用户展示支付方式并支付,PayerMax提供纯API(Direct API)的方式接入。 对于Direct API的接口,商户如果自行处理卡号信息,需要具备PCI-DSS认证资质。

Parameters

FieldTypeRequiredDescription
Content-Type (header)stringYes
sign (header)stringYes签名信息请参考技术文档

Request Body

FieldTypeRequiredDescriptionEnum
versionstringYes接口版本 当前值为:1.5
keyVersionstringYes密钥版本 当前值为:1
requestTimestringYes请求时间,符合rfc3339规范,格式:yyyy-MM-dd'T'HH:mm:ss.SSSXXX 时间需要在当前时间两分钟内
appIdstringYes商户应用Id,PayerMax分配给商户应用的唯一标识
merchantNostringNo商户号,商户与PayerMax业务签约时生成的唯一标识
dataobjectYes请求数据体
data.outTradeNostringYes商户订单号,唯一标识商户的一笔交易,不能重复,只能包含字母、数字、下划线且不支持大小写敏感。如:AAA和AAa被认为是相同的。
data.integratestringYes商户自行进行付款方支付信息的收集后,传送给PayerMax进行交易处理,需传入参数:Direct_Payment
data.captureModestringYes请款模式:MANUAL
data.authorizationTypestringNo授权类型:FINAL_AUTH
data.subjectstringYes订单标题或产品信息,会展示在用户支付页面,避免使用纯数字。注:巴西钱包Pix不能超过43位
data.totalAmountnumberYes标价金额,金额的单位为元。各个国家币种支持的小数位详见【交易支持国家/地区与币种】,风控限额详见【风控行业限额
data.currencystringYes标价币种,大写字母,参见【交易支持国家/地区与币种
data.countrystringYes国家代码,大写字母,参见【交易支持国家/地区与币种
data.userIdstringYes商户内部的用户Id,需要保证每个ID唯一性
data.expireTimestringNo指定关单时间(单位:秒)。最小30分钟,最大1天。若传入则以该时间为关单时间。默认30分钟
data.paymentDetailobjectYes支付信息
data.paymentDetail.paymentMethodTypestringYes支付方式类型,参见【纯API支付-支付方式列表】支付方式必填
data.paymentDetail.targetOrgstringNo目标机构除paymentMethodType为CARD外均必填
data.paymentDetail.payAccountInfoarray[object]No支付账号,部分支付方式下的目标机构需要上送用户在该目标机构的支付账号信息。 参见【纯API支付-支付方式列表
data.paymentDetail.payAccountInfo[].accountNostringNo用户在该支付方式下的目标机构注册的支付账号
data.paymentDetail.payAccountInfo[].accountNoTypestringNo账号类型:EMAIL,PHONE,ACCOUNT
data.paymentDetail.cardInfoobjectNo卡信息
data.paymentDetail.cardInfo.cardIdentifierNostringNo卡号
data.paymentDetail.cardInfo.cardHolderFullNamestringNo持卡人姓名
data.paymentDetail.cardInfo.cardExpirationMonthstringNo卡有效期-月,两位月份
data.paymentDetail.cardInfo.cardExpirationYearstringNo卡有效期-年,只取后两位年份
data.paymentDetail.cardInfo.cvvstringNo卡cvv,Visa和MasterCard为3位数字,AEMX为4位数字
data.paymentDetail.cardInfo.storedstringNo代表该笔卡支付交易是否已存卡。 已存卡:Y 未存卡:不填或者其他值
data.paymentDetail.cardInfo.dynamic3DSstringNo动态3ds(参数不区分大小写) do3DS:为此订单执行3DS Secure no3DS:不为此订单执行3DS Secure ext3DS:使用外部3DS结果,适用于已经对接了其他3DS服务的商户,指定该值时,则必须同时传入info3DSecure对象 未传或传入其他值,由PayerMax判断是否发起3ds
data.paymentDetail.buyerInfoobjectYes用户基本信息
data.paymentDetail.buyerInfo.firstNamestringNo用户名 注:巴西HIPERCAR、ELO卡支付时必传
data.paymentDetail.buyerInfo.middleNamestringNo用户中间名
data.paymentDetail.buyerInfo.emailstringNo用户邮箱 注:巴西HIPERCAR、ELO卡支付时必传
data.paymentDetail.buyerInfo.lastNamestringNo用户姓 注:巴西HIPERCAR、ELO卡支付时必传
data.paymentDetail.buyerInfo.phoneNostringNo用户手机号 注:土耳其卡支付时必传
data.paymentDetail.buyerInfo.phoneNoRegionstringNo手机号区号 注:土耳其卡支付时必传
data.paymentDetail.buyerInfo.idTypestringNo证件类型
data.paymentDetail.buyerInfo.idNostringNo证件号
data.paymentDetail.buyerInfo.taxTypestringNo税类型,参见【各国税类型和税号规则注:巴西国家该字段必须传入CPF
data.paymentDetail.buyerInfo.taxNostringNo税号,参见【各国税类型和税号规则注:巴西国家该字段必填,为巴西身份证号
data.paymentDetail.buyerInfo.addressstringNo用户地址
data.paymentDetail.buyerInfo.citystringNo用户所在城市
data.paymentDetail.buyerInfo.regionstringNo用户所在区域
data.paymentDetail.buyerInfo.zipCodestringNo邮编
data.paymentDetail.buyerInfo.clientIpstringYes用户IP地址,须为标准IPv4或IPv6格式。
data.paymentDetail.buyerInfo.userAgentstringYes用户浏览器信息
data.paymentDetail.paymentTokenIDstringNoPMMax token,授权成功后支付
data.paymentDetail.tokenForFutureUsebooleanNotrue代表用户已授权进行支付信息绑定,用于后续使用,默认为false
data.paymentDetail.merchantInitiatedbooleanNo代表是否为MIT交易,不传默认为false
data.paymentDetail.mitTypestringNo代扣类型。SCHEDULED, UNSCHEDULED
data.paymentDetail.info3DSecureobjectNo商户使用ext3DS时,上送的外部3DS的信息。注:须提前联系技术支持开通相关功能
data.paymentDetail.info3DSecure.threeDSVersionstringNo3ds版本号
data.paymentDetail.info3DSecure.ecistringNoeci值
data.paymentDetail.info3DSecure.cavvstringNocavv值
data.paymentDetail.info3DSecure.dsTransactionIdstringNodsTransactionId值
data.paymentDetail.info3DSecure.xidstringNoxid值
data.goodsDetailsarray[object]No商品信息,支持传多个。注:电商场景下需要上送。如果传入该对象,则内层必填字段必须传入
data.goodsDetails[].goodsIdstringYes商品ID
data.goodsDetails[].goodsNamestringYes商品名称
data.goodsDetails[].quantitystringYes商品数量
data.goodsDetails[].pricestringYes商品价格,商户系统的报价
data.goodsDetails[].goodsCurrencystringNo商品报价币种,大写字母,参见【交易支持国家/地区与币种
data.goodsDetails[].showUrlstringNo商品链接地址。注:电商场景下需要上送。
data.goodsDetails[].goodsCategorystringNo商品类别。注:电商场景下需要上送。
data.subMerchantobjectNo二级商户信息 平台类商户需要上送子商户信息
data.subMerchant.subMerchantNostringNo二级商户号
data.shippingInfoobjectNo邮寄信息。注:电商场景下需要上送。如果传入该对象,则内层必填字段必须传入
data.shippingInfo.firstNamestringYes收货人名
data.shippingInfo.middleNamestringNo收货人中间名
data.shippingInfo.lastNamestringYes收货人姓
data.shippingInfo.phoneNostringYes收货人手机号
data.shippingInfo.emailstringYes收货邮箱地址
data.shippingInfo.address1stringYes收货地址1
data.shippingInfo.citystringYes收货地址所在城市
data.shippingInfo.regionstringNo收货地址所在区域
data.shippingInfo.statestringNo收货地址所在州 送货到加拿大,美国,英国,澳大利亚时必填
data.shippingInfo.countrystringYes收货地址所在国家
data.shippingInfo.zipCodestringYes收货地址邮编
data.shippingInfo.address2stringNo收货地址2
data.shippingInfo.address3stringNo收货地址3
data.billingInfoobjectNo信用卡账单地址信息。注:如果传入该对象,则内层必填字段必须传入
data.billingInfo.firstNamestringNo账单人名
data.billingInfo.middleNamestringNo账单人中间名
data.billingInfo.lastNamestringNo账单人姓
data.billingInfo.phoneNostringNo账单人手机号
data.billingInfo.emailstringYes账单邮箱地址
data.billingInfo.address1stringYes账单地址1
data.billingInfo.citystringYes账单地址所在城市
data.billingInfo.countrystringYes账单地址所在国家
data.billingInfo.regionstringNo账单地址所在区域
data.billingInfo.statestringNo账单地址所在州 送货到加拿大,美国,英国,澳大利亚时需要上送
data.billingInfo.zipCodestringNo账单地址邮编
data.billingInfo.address2stringNo账单地址2
data.billingInfo.address3stringNo账单地址3
data.envInfoobjectNo设备信息
data.envInfo.deviceIdstringNo商户设备唯一标识
data.envInfo.deviceLanguagestringNo设备默认语言
data.envInfo.screenHeightstringNo设备高度
data.envInfo.screenWidthstringNo设备宽度
data.languagestringNo收银台页面语言。【支持的国家与币种】 优先级:用户上次使用的语言 > 用户浏览器语言 > 用户ip国家语言 > 商户下单传的语言 > 默认EN
data.riskParamsobjectNo详见风控业务数据:【商户上送信息】,该部分信息通常作为定制风控的补充信息,如未开通定制风控可不填。
data.terminalTypestringYes设备终端,WEB,WAP,APP
data.osTypestringNo设备操作系统,当设备终端为Wap和App时,设备操作系统可以为ANDROID或IOS
data.referencestringNo商户自定义附加数据,可支持商户自定义并在响应中返回
data.frontCallbackUrlstringNo商户指定的跳转URL,用户完成支付后会被跳转到该地址,以http/https开头或者商户应用的scheme地址,纯API支付下frontCallbackUrl是必填的,用于支持需要跳转外部的异步交易
data.notifyUrlstringNo服务端回调通知URL,以http/https开头 可以通过MerchantDashboard平台配置商户通知地址,详情见【配置异步通知地址】,如果交易中上送,则以交易为准,即优先使用接口中传的url。注:如商户平台未配置通知地址,交易也没上送地址,则无法进行回调通知
data.subscriptionPlanobjectNo
data.subscriptionPlan.subscriptionNostringYes通过PayerMax创建订阅计划后生成的订阅单号,激活订阅计划时必传

Responses

200 — ## 错误码

分类结果码结果描述
SYSTEM_ERRORSystem is busy, please try again later.系统错误;请联系PayerMax
REQ_TIME_OVER_TIMErequestTime effective in two minutes请求时间与服务端偏差超过2分钟,请检查requestTime后重新发起
TOO_MANY_REQUESTExceed request limitation, please retry later触发接口并发限流,请稍后重试
SIGN_VERIFY_FAILEDThe signature verify failed.签名错误;请核实签名
MERCHANT_INVALIDThe merchant has been offline.无效商户
MERCHANT_APP_INVALIDSignature key is not configured.无效商户APP
REQUEST_TIMEOUTRequest timeout or didn't get result, If you have finished to pay, pls wait for the result.请求超时;请联系PayerMax
UNEXPECTED_ERRORNo 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_INVALIDAmount is incorrect.无效的金额
COUNTRY_INVALIDNo country support, pls re-pay.无效的国家;可参考支持的国家和币种
CURRENCY_INVALIDcurrency is invalid,because currency is not defined.无效的币种;可参考支持的国家和币种
CONTRACT_INVALIDMerchant has no activated contract, please check the contract status.无效合约;请检查合约有效性
CONTRACT_INVALIDMerchant has not signed the contract in ${value}.指定的国家/地区未签约;请检查合约有效性
CONTRACT_INVALIDMerchant has not signed the ${paymentMethod} payment method.指定的支付方式未签约;请检查合约有效性
CONTRACT_INVALIDMerchant has not signed the ${targetOrg} target origination correspondingly, although you have signed the ${paymentMethod} payment method.指定的目标机构未签约;请检查合约有效性
CONTRACT_INVALIDMerchant has not signed the ${currency} currency correspondingly, although you have signed the ${paymentMethod} payment method.指定的支付方式有签约,但所指定的币种未签约;请检查合约有效性
CONTRACT_INVALIDMerchant has not signed the ${currency} currency correspondingly, although you have signed the ${paymentMethod} payment method and the ${targetOrg} target origination.指定的目标机构有签约,但所指定的币种未签约;请检查合约有效性
PAYMENT_METHOD_NOT_EXISTThe payment method does not exist.支付方式不存在;请更换其他支付方式
PAYMENT_METHOD_SUSPENDThe payment method already suspend, plz try other payment methods.支付方式暂不可用;请更换其他支付方式
AMOUNT_LIMIT_MINIMUMThe order amount is lower than the minimum limit of the payment method.最小金额限制
AMOUNT_LIMIT_MAXIMUMThe order amount exceeds the maximum limit of the payment method.最大金额限制
AMOUNT_LIMITThe amount doesn't match the payment method requirement.金额限制
ORDER_REPEATThe order number repeat.订单重复
ONBOARD_ERRORPlease complete the merchant onboarding, then refresh the page.商户未报备;请先完成报备
PAYMENT_PROCESSINGThe payment is processing, pls check the result.支付处理中;请稍后重试
PARTICIPANT_INVALIDInvalid participant.无效分账参与方
BALANCE_INSUFFICIENTInsufficient balance to pay, please confirm payment account available balance.余额不足
OTP_VERIFY_LIMITOTP verification exceeds limit.OTP验证超过限制
OTP_VERIFY_FAILEDOTP verification failed.OTP验证失败
OVER_VERIFY_LIMITExceeded the number of verifications.超过验证次数
BARCODE_REFRESH_LIMITOver barcode refresh times.Barcode刷新限制
BARCODE_REFRESH_FAILEDBarcode refresh failed.Barcode刷新失败
CARD_INVALIDMake sure the card number is correct.无效卡号
CARD_EXPIRE_DATE_INVALIDInvalid card number validity period无效卡号有效期
CARD_HOLDER_NAME_INVALIDInvalid cardholder name无效持卡人姓名
CVV_INVALIDCvv is incorrect, pls check.无效CVV
UNSUPPORT_CARDThis card don't support, please change another card.卡不支持
ACCOUNT_INVALIDYour account is invalid or not active, please confirm and re-enter.无效账号
PHONE_NUM_INVALIDThe phone number is invalid, pls check and re-enter.无效的电话号码
UPI_INVALIDUPI is incorrect.无效UPI
PIN_VERIFY_LIMITPin verification exceeds limitPin验证超过限制
PIN_INVALIDPin is invalidPin无效
BANKCODE_INVALIDInvalid bank card number.无效银行卡号
ID_NUM_INVALIDInvalid ID number无效的证件号
EMAIL_INVALIDYour email is invalid, or your account is not active, please confirm and re-enter.无效的Email
DOCUMENT_INVALIDInvalid document.无效的文档
TCK_INVALIDTC Kimlik No. is incorrect.无效的TC Kimlik No.
DATE_INVALIDThe data format is error, please check.无效的日期
PAYEE_NAME_INVALIDYour name is invalid, or does not match, please confirm and re-enter.无效的付款人姓名
REMARK_INVALIDInvalid remark无效的remark
CNIC_INVALIDThe CNIC is incorrect, pls confirm and re-enter.无效的CNIC
ACCOUNT_BLOCKEDPayer account/card blocked or frozen. Pls confirm payment account/card status.账号被锁定/冻结
PAYMENT_CANCELEDpayment canceled.用户在第三方支付取消
PAYMENT_TOKEN_ID_INVALIDPaymentTokenID is invalid. Please confirm if it has been authorized and boundpaymentTokenId不合法,请检查输入是否正确,或已经解绑
MER_CONFIG_ERRORMerchant config error. Please contact us to check your dynamic3DS configuration.商户未开通动态3d功能
AUTH_NOT_SUPPORTThe contract does not enable the Auth-Capture.合约未开通Auth-capture功能
PRE_AUTH_NOT_SUPPORTThe merchant does not support the PRE_AUTH.商户未开通PRE_AUTH功能
ACCOUNT_VALIDATION_INVALIDPlease complete the account verification firstly.账户未完成验证,请先完成账户验证
PAYMENT_PROCESSING_BANKTRANSFERThe 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_FALLBACKYour account balance is insufficient to cover the amount. Please check your account balance.账户余额不足,请检查账户余额
ONLY_ONE_AUTH_CHANNEL_ALLOWEDonly one authorization channel is allowed仅允许一个授权渠道
ISSUER_PAYMENT_REJECTEDTransaction failed at issuer end due to risk control. Please try using a different card or contact your issuer for more detail.交易被发卡行风控拒绝,请更换银行卡或联系发卡行
AMOUNT_LIMITThe amount exceeds user amount limit.用户金额限制
AMOUNT_LIMITThe amount exceeds the limit for per transaction limit.单笔交易金额限制
AMOUNT_LIMITThe amount exceeds the limit for the day.日交易金额限制
CARD_INVALIDExpired card.卡已过期
CARD_INVALIDCard scheme is not supported.卡组织不支持
CARD_INVALIDOnly support the card which issue by local bank, pls change local card.仅支持本地银行卡
OTP_VERIFY_FAILEDOTP verify failed.OTP验证失败
PAYMENT_METHOD_NOT_EXISTBank temporarily not available, please retry later.银行暂时不可用,请稍后重试
PAYMENT_METHOD_SUSPENDThe payment method is in maintenance, please try again later.支付方式维护中,请稍后重试
PAYMENT_FAILEDTransaction declined.交易被拒绝
PAYMENT_FAILEDThere is no channel to support the payment.无可用支付渠道
PAYMENT_FAILEDPayment was not completed on time.支付超时未完成
PAYMENT_FAILEDProvider failed to process.支付失败
AUTHENTICATE_FAILEDYour payment was declined due to authentication failure. Please try using a different card or contact your issuer for more detail.授权失败
AUTH_EXPIREDThe authorization has expired, pls rebind.授权过期
AUTH_FAILEDAuthorization failed.授权失败或不存在
RISK_FAILEDThis transaction was automatically blocked due to identified risk.该交易因存在确认性风险被拦截
RISK_FAILEDThe payment has reached the security limit. Please advise the user to try another payment method or attempt the transaction again later.用户支付已达到安全限额/限次,建议用户尝试其他支付方式
RISK_FAILEDThe payment has exhibited suspicious activity. We suggest that the user use a local card or disable their VPN before trying again.检测到支付行为异常,建议用户使用本地银行卡或关闭VPN后重试
RISK_FAILEDThe 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_REJECTEDDevice IP restriction,please make sure your VPN is turned off when making the payment for security reason.设备IP受限,请关闭VPN后重试
PAYMENT_REJECTEDTransaction failed at processor end due to risk control.Please try using a different payment method/card.nan
RISK_BLACK_LIST_FAILEDThe payment was declined due to high risk with the payment.此笔交易命中商户自身侧黑名单,黑名单详情可登录MMC查询
ISSUER_PAYMENT_REJECTEDTransaction failed at issuer end due to risk control. Please contact your payment method issuer for more detail.交易被发卡行拒绝,详情请用户咨询发卡行确认
FieldTypeRequiredDescription
codestringYes返回码,’APPLY_SUCCESS’代表成功。只代表接口请求成功,不代表订单状态。
msgstringYes返回描述,’Success.’。只代表接口请求成功,不代表订单状态。
dataobjectNo返回数据体
data.outTradeNostringYes商户订单号
data.tradeTokenstringYesPayerMax流水号
data.statusstringYes交易状态,详见【交易状态
data.redirectUrlstringNo跳转地址 部分支付方式需要跳转外部完成支付

Enum Reference

data.paymentDetail.mitType

  • SCHEDULED
  • UNSCHEDULED

此页面的内容有帮助吗?

感谢您帮助改进 PayerMax 产品文档!

Last updated:

Released under the MIT License.