收银台-下单

Endpoint: POST /aggregate-pay/api/gateway/orderAndPay
Tags: 收单

Description

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_Hosted_Payment_Page进行付款方支付信息收集及处理，需传入参数：Hosted_Checkout
`data.subject`	string	Yes	maxLength: 256	订单标题或产品信息，会展示在用户支付页面，避免使用纯数字。注：巴西钱包Pix不能超过43位
`data.totalAmount`	number	Yes		标价金额，金额的单位为元。各个国家币种支持的小数位详见【交易支持国家/地区与币种】,风控限额详见【风控行业限额】
`data.currency`	string	Yes	maxLength: 3	标价币种，大写字母，参见【交易支持国家/地区与币种】
`data.country`	string	No	maxLength: 2	国家代码，大写字母，参见【交易支持国家/地区与币种】。如指定了paymentMethodType，则国家代码必须上送且和支付方式对应国家匹配。收银台可用国家地区选择策略为：上送国家代码地区>用户历史使用国家代码地区>用户IP所在国家代码地区。（可用国家地区：交易币种对应的国家与签约国家取交集）
`data.userId`	string	Yes	maxLength: 64	商户内部的用户Id，需要保证每个ID唯一性。支付方式绑定后会根据userId进行支付方式推荐
`data.language`	string	No	maxLength: 16	收银台页面语言。【支持的国家与币种】优先级：用户上次使用的语言 > 用户浏览器语言 > 用户ip国家语言 > 商户下单传的语言 > 默认EN
`data.referralCode`	string	No	maxLength: 32	用于更精准的支付方式推荐，如设备ID、设备指纹等。
`data.reference`	string	No	maxLength: 512	商户自定义附加数据，可支持商户自定义并在响应中返回
`data.frontCallbackUrl`	string	Yes	maxLength: 1024	商户指定的跳转URL，用户完成支付后会被跳转到该地址，以http/https开头或者商户应用的scheme地址。详见【结果页跳转说明】
`data.notifyUrl`	string	No	maxLength: 256	服务端回调通知URL，以http/https开头可以通过MerchantDashboard平台配置商户通知地址，详情见【配置异步通知地址】，如果交易中上送，则以交易为准，即优先使用接口中传的url。注：如商户平台未配置通知地址，交易也没上送地址，则无法进行回调通知
`data.expireTime`	string	No		指定关单时间(单位：秒)。 1）expireTime 传值时： - 当expireTime<=30min：则关单时间为30min - 当24hour>=expireTime>=30min：则关单时间为expireTime - 当expireTime>=24hour：则关单时间为24hour 2）expireTime 未传值时： - 取这笔订单发起过的支付方式关单时间的最大值。
`data.mitManagementUrl`	string	No		订阅计划管理地址
`data.subscriptionPlan`	any	No		订阅计划信息
`data.paymentDetail`	object	No		支付信息，非必填。 1、可指定支付方式类型，收银台会拉起该支付方式类型支持的所有目标机构。 2、可指定支付方式类型+目标机构。
`data.paymentDetail.paymentTokenID`	string	No	maxLength: 64	token支付或商家代扣后续支付时，此字段为必填；
`data.paymentDetail.paymentMethodType`	string	No	maxLength: 16	支付方式类型，为空时，拉取所有可用支付方式，参见【收银台支付-支付方式列表】
`data.paymentDetail.targetOrg`	string	No	maxLength: 16	目标机构，可以为空，如果指定目标机构，则paymentMethodType也必须指定。参见【收银台支付-支付方式列表】
`data.paymentDetail.allowedCardOrg`	array[string]	No		指定收银台可使用的卡组
`data.paymentDetail.payAccountInfo`	array[object]	No		支付账号，当指定支付方式和目标机构时，支持上送用户在该目标机构的支付账号信息。参见【收银台支付-支付方式列表】下的支持上送账号类型列
`data.paymentDetail.payAccountInfo[].accountNo`	string	No	maxLength: 32	用户在该支付方式下的目标机构注册的支付账号,详见每个支付方式介绍
`data.paymentDetail.payAccountInfo[].accountNoType`	string	No	maxLength: 255	账号类型：EMAIL，PHONE，ACCOUNT	`EMAIL`, `PHONE`, `ACCOUNT`
`data.paymentDetail.tokenForFutureUse`	boolean	No		true代表用户已授权进行支付信息绑定，用于后续使用，默认为false。
`data.paymentDetail.merchantInitiated`	boolean	No		代表是否MIT交易，不传默认为false。
`data.paymentDetail.mitType`	string	No	maxLength: 16	代扣类型；枚举值：SCHEDULED、UNSCHEDULED
`data.envInfo`	object	No		设备信息
`data.envInfo.deviceId`	string	No		商户设备唯一标识
`data.envInfo.deviceLanguage`	string	No		设备默认语言
`data.envInfo.screenHeight`	string	No		设备高度
`data.envInfo.screenWidth`	string	No		设备宽度
`data.subMerchant`	object	No		二级商户信息平台类商户需要上送子商户信息
`data.subMerchant.subMerchantNo`	string	No	maxLength: 64	二级商户号
`data.goodsDetails`	array[object]	No		商品信息，支持传多个。注：电商场景下需要上送。如果传入该对象，则内层必填字段必须传入
`data.goodsDetails[].goodsId`	string	Yes	maxLength: 64	商品ID
`data.goodsDetails[].goodsName`	string	Yes	maxLength: 128	商品名称
`data.goodsDetails[].quantity`	string	Yes	maxLength: 16	商品数量
`data.goodsDetails[].price`	string	Yes	maxLength: 20	商品价格，商户系统的报价
`data.goodsDetails[].goodsCurrency`	string	No	maxLength: 3	商品报价币种，大写字母，参见【交易支持国家/地区与币种】
`data.goodsDetails[].showUrl`	string	No	maxLength: 128	商品链接地址。注：电商场景下需要上送
`data.goodsDetails[].goodsCategory`	string	No	maxLength: 64	商品类别。注：电商场景下需要上送
`data.shippingInfo`	object	No		邮寄信息注：电商场景下需要上送。如果传入该对象，则内层必填字段必须传入
`data.shippingInfo.firstName`	string	Yes	maxLength: 64	收货人名
`data.shippingInfo.middleName`	string	No	maxLength: 64	收货人中间名
`data.shippingInfo.lastName`	string	Yes	maxLength: 64	收货人姓
`data.shippingInfo.phoneNo`	string	Yes	maxLength: 32	收货人手机号
`data.shippingInfo.email`	string	Yes	maxLength: 255	收货邮箱地址
`data.shippingInfo.address1`	string	Yes	maxLength: 1024	收货地址1
`data.shippingInfo.address2`	string	No	maxLength: 1024	收货地址2
`data.shippingInfo.city`	string	Yes	maxLength: 64	收货地址所在城市
`data.shippingInfo.region`	string	No	maxLength: 64	收货地址所在区域
`data.shippingInfo.state`	string	No	maxLength: 32	收货地址所在州送货到加拿大，美国，英国，澳大利亚时必填
`data.shippingInfo.country`	string	Yes	maxLength: 2	收货地址所在国家
`data.shippingInfo.zipCode`	string	Yes	maxLength: 32	收货地址邮编
`data.billingInfo`	object	No		信用卡账单信息。注：如果传入该对象，则内层必填字段必须传入
`data.billingInfo.firstName`	string	No	maxLength: 64	账单人名
`data.billingInfo.middleName`	string	No	maxLength: 64	账单人中间名
`data.billingInfo.lastName`	string	No	maxLength: 64	账单人姓
`data.billingInfo.phoneNo`	string	No	maxLength: 32	账单人手机号
`data.billingInfo.email`	string	Yes	maxLength: 255	账单邮箱地址
`data.billingInfo.address1`	string	Yes	maxLength: 1024	账单地址1
`data.billingInfo.address2`	string	No	maxLength: 1024	账单地址2
`data.billingInfo.city`	string	Yes	maxLength: 64	账单地址所在城市
`data.billingInfo.region`	string	No	maxLength: 64	账单地址所在区域
`data.billingInfo.state`	string	No	maxLength: 32	账单地址所在州送货到加拿大，美国，英国，澳大利亚时需要上送
`data.billingInfo.country`	string	Yes	maxLength: 2	账单地址所在国家
`data.billingInfo.zipCode`	string	No	maxLength: 16	账单地址邮编
`data.riskParams`	object	No		详见风控业务数据【商户上送信息】

Example: 1

正常示例

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "P1642410352195",
    "subject": "MacPro14 and Mouse",
    "totalAmount": 4,
    "currency": "USD",
    "country": "US",
    "userId": "test1111",
    "language": "en",
    "reference": "reference查询和回调返回",
    "frontCallbackUrl": "http://www.frontCallbackUrl.example.com",
    "notifyUrl": "http://www.notifyUrl.example.com",
    "integrate": "Hosted_Checkout",
    "expireTime": "1800",
    "mitManagementUrl": "http://your.subscription.com",
    "subscriptionPlan": {
      "subject": "subject",
      "description": "PMMAX周期首期扣款",
      "totalPeriods": 12,
      "periodRule": {
        "periodUnit": "M",
        "periodCount": 1
      },
      "periodAmount": {
        "amount": 20,
        "currency": "USD"
      },
      "trialPeriodConfig": {
        "trialPeriodCount": 1,
        "trialPeriodAmount": {
          "amount": 10,
          "currency": "USD"
        }
      },
      "trialConfig": {
        "trialAmount": {
          "amount": 4,
          "currency": "USD"
        },
        "trialDays": 7
      }
    },
    "paymentDetail": {
      "paymentMethodType": "",
      "targetOrg": "",
      "payAccountInfo": [
        {
          "accountNo": "fasdf@example.com",
          "accountNoType": "EMAIL"
        },
        {
          "accountNo": "0999998781111111",
          "accountNoType": "PHONE"
        },
        {
          "accountNo": "FASDFDF",
          "accountNoType": "ACCOUNT"
        }
      ]
    },
    "envInfo": {
      "deviceId": "eYOIkvFpZzztg00Yu6USdprBQZCWxDhiUAHCiK&K/cH9mT6wMaMOzAKe",
      "deviceLanguage": "zh_CN",
      "screenHeight": 768,
      "screenWidth": 1024
    },
    "goodsDetails": [
      {
        "goodsId": "D002",
        "goodsName": "Jaz",
        "quantity": "2",
        "price": "500",
        "goodsCurrency": "IDR",
        "showUrl": "http://www.example.com",
        "goodsCategory": "clothes"
      }
    ],
    "shippingInfo": {
      "firstName": "zhang",
      "middleName": "shang",
      "lastName": "feng",
      "phoneNo": "13009090980",
      "email": "test@example.com",
      "address1": "er xian qiao",
      "address2": "chenghua road",
      "city": "chengdu",
      "region": "wuhou",
      "state": "sichuan",
      "country": "ID",
      "zipCode": "000000"
    },
    "billingInfo": {
      "firstName": "James",
      "middleName": "middleName",
      "lastName": "Smith",
      "email": "James@example.com",
      "phoneNo": "903124360628",
      "address1": "GOLGELI SOKAK NO.34, 06700",
      "address2": "GOLGELI SOKAK NO.34, 06700",
      "city": "GAZIOSMANPASA/ANKAR",
      "region": "region",
      "state": "state",
      "country": "TR",
      "zipCode": "06700"
    },
    "riskParams": {
      "registerName": "lily",
      "regTime": "2023-07-01 12:08:34",
      "liveCountry": "VN",
      "payerAccount": "987654XXX",
      "payerName": "lily",
      "taxId": "1234567890"
    }
  }
}

Example: 2

全量收银台

json

{
  "requestTime": "2025-06-26T20:11:30.528+08:00",
  "keyVersion": "1",
  "data": {
    "country": "DE",
    "frontCallbackUrl": "http://www.frontCallbackUrl.example.com",
    "subject": "MacPro14 and Mouse",
    "userId": "orderAndPayUserId5WPGcZilgw",
    "integrate": "Hosted_Checkout",
    "totalAmount": "100",
    "outTradeNo": "orderAndPayOutTradeNo1750939890528nSYEkJJibb",
    "notifyUrl": "http://www.notifyUrl.example.com",
    "currency": "EUR"
  },
  "appId": "d27183b7f2ea4822aa722d9efa8e7a8b",
  "version": "1.4",
  "merchantNo": "SDP01010115045982"
}

Example: 3

指定支付方式

json

{
  "requestTime": "2025-06-26T20:11:28.677+08:00",
  "keyVersion": "1",
  "data": {
    "country": "DE",
    "frontCallbackUrl": "http://www.frontCallbackUrl.example.com",
    "subject": "MacPro14 and Mouse",
    "userId": "orderAndPayUserIdmbfs36NuP4",
    "integrate": "Hosted_Checkout",
    "totalAmount": "100",
    "paymentDetail": {
      "paymentMethodType": "PAY_LATER"
    },
    "outTradeNo": "orderAndPayOutTradeNo1750939888677H6qrN2dcNb",
    "notifyUrl": "http://www.notifyUrl.example.com",
    "currency": "EUR"
  },
  "appId": "d27183b7f2ea4822aa722d9efa8e7a8b",
  "version": "1.4",
  "merchantNo": "SDP01010115045982"
}

Example: 4

指定目标机构

json

{
  "requestTime": "2025-06-26T20:11:26.911+08:00",
  "keyVersion": "1",
  "data": {
    "country": "DE",
    "frontCallbackUrl": "http://www.frontCallbackUrl.example.com",
    "subject": "MacPro14 and Mouse",
    "userId": "orderAndPayUserId9KvboN9MjK",
    "integrate": "Hosted_Checkout",
    "totalAmount": "100",
    "paymentDetail": {
      "targetOrg": "KLARNA",
      "paymentMethodType": "PAY_LATER"
    },
    "outTradeNo": "orderAndPayOutTradeNo1750939886911ALoVwQnZVz",
    "notifyUrl": "http://www.notifyUrl.example.com",
    "currency": "EUR"
  },
  "appId": "d27183b7f2ea4822aa722d9efa8e7a8b",
  "version": "1.4",
  "merchantNo": "SDP01010115045982"
}

Example: 5

指定卡组

json

{
  "requestTime": "2025-06-26T20:11:25.294+08:00",
  "keyVersion": "1",
  "data": {
    "country": "SA",
    "frontCallbackUrl": "http://www.frontCallbackUrl.example.com",
    "subject": "MacPro14 and Mouse",
    "userId": "orderAndPayUserIdxCfwTf7Sng",
    "integrate": "Hosted_Checkout",
    "totalAmount": "100",
    "paymentDetail": {
      "paymentMethodType": "CARD",
      "allowedCardOrg": [
        "VISA"
      ]
    },
    "outTradeNo": "orderAndPayOutTradeNo1750939885294iO0CZJ1WaM",
    "notifyUrl": "http://www.notifyUrl.example.com",
    "currency": "SAR"
  },
  "appId": "d27183b7f2ea4822aa722d9efa8e7a8b",
  "version": "1.4",
  "merchantNo": "SDP01010115045982"
}

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
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.	商户未报备；请先完成报备
PARTICIPANT_INVALID	Invalid participant.	无效分账参与方
PAYMENT_METHOD_NOT_EXIST	Bank temporarily not available, please retry later.	银行暂时不可用，请稍后重试
PAYMENT_METHOD_SUSPEND	The payment method is in maintenance, please try again later.	支付方式维护中，请稍后重试

Field	Type	Required	Constraints	Description
`code`	string	Yes		返回码，’APPLY_SUCCESS’代表成功。只代表接口请求成功，不代表订单状态。
`msg`	string	Yes		返回描述，’Success.’ 。只代表接口请求成功，不代表订单状态。
`data`	object	Yes		返回数据体
`data.redirectUrl`	string	Yes	maxLength: 1024	跳转地址
`data.outTradeNo`	string	Yes	maxLength: 64	商户订单号
`data.tradeToken`	string	Yes	maxLength: 64	PayerMax流水号
`data.status`	string	Yes	maxLength: 32	交易状态，详见【交易状态】

Response Example: 1

成功示例

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "redirectUrl": "https://cashier-n.payermax.com/index.html#/cashier/home?merchantId=020213827212251&merchantAppId=3b242b56a8b64274bcc37dac281120e3&country=ID&tradeToken=TOKEN20220117091121294138752&language=en&token=IHjqkZ8%2F%2FFcnfDPxWTvJFOrulUAKfXFUkxHJSiTdlnjnX1G6AOuTiSl6%2BN05EzxTaJkcSsSyGh5a1q%2FACwWN0sDD%2FgwY5YdWu3ghDcH2wqm%2BJIcEh0qZqo%2BQFnXp65bvkLZnY7VO7HwZGzyrpMBlPhfRCQxwBbc6lJcSYuPf%2Fe8%3D&amount=10000¤cy=IDR&frontCallbackUrl=https%3A%2F%2Fwww.payermax.com",
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "status": "PENDING"
  }
}

Response Example: 2

异常示例

json

{
  "data": {
    "redirectUrl": "http://jtce.nz/fideg",
    "outTradeNo": "Lorem ut in culpa dolor",
    "tradeToken": "eu cupidatat magna proident",
    "status": "enim quis eiusmod occaecat"
  },
  "code": "14",
  "msg": "amet in elit"
}

Response Example: 3

异常示例2

json

{
  "data": {
    "redirectUrl": "http://jnsmsvoxlg.hn/whfocvhoq",
    "outTradeNo": "tempor dolore in cillum voluptate",
    "tradeToken": "elit velit",
    "status": "aliquip in ut"
  },
  "code": "10",
  "msg": "ut reprehenderit Ut"
}

Enum Reference

`data.paymentDetail.payAccountInfo[].accountNoType`

EMAIL
PHONE
ACCOUNT

收银台-下单 ​

Description ​

Parameters ​

Parameter Examples ​

Request Body ​

Example: 1 ​

Example: 2 ​

Example: 3 ​

Example: 4 ​

Example: 5 ​

Responses ​

200 ​

错误码 ​

Response Example: 1 ​

Response Example: 2 ​

Response Example: 3 ​

Enum Reference ​

data.paymentDetail.payAccountInfo[].accountNoType ​

收银台-下单

Description

Parameters

Parameter Examples

Request Body

Example: 1

Example: 2

Example: 3

Example: 4

Example: 5

Responses

200

错误码

Response Example: 1

Response Example: 2

Response Example: 3

Enum Reference

`data.paymentDetail.payAccountInfo[].accountNoType`