Drop-In Payment

• Endpoint: POST /aggregate-pay/api/gateway/orderAndPay/(for-drop-dont-copy-me)
• Tags: Collection Service/DropIn Payment

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		API version. Current value: 1.5
keyVersion	string	Yes		Signature Algorithm Version, Current value: 1
requestTime	string	Yes		Request time, compliant with rfc3339 specification, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX The time must be within two minutes of the current time
appId	string	Yes		Merchant AppId，The unique identifier assigned to the merchant app by PayerMax
merchantNo	string	No	maxLength: 32	Merchant Id, the unique identifier generated when the merchant signs the contract with PayerMax
data	object	Yes		Request data body.
data.outTradeNo	string	Yes	maxLength: 64	Merchant order id, which uniquely identifies a transaction of the merchant, cannot be repeated, and can only contain letters (Case sensitivity not supported), numbers, and underlines.For example, AAA and AAa are considered the same.
data.integrate	string	Yes	maxLength: 16	The merchant collects the payer's payment information by itself and sends it to PayerMax for transaction processing. Incoming parameter: Direct_Payment
data.subject	string	Yes	maxLength: 256	Order title or product information, which will be displayed on the user payment page, please avoid using pure numbers.  Note: it cannot exceed 43 digits for Brazil Pix.
data.totalAmount	number	Yes		The order amount is passed in by the merchant. The decimal point supported by the currency of each country.See【Supported Country/Region and Currency】,Risk control limit list.See【Risk control limit list】
data.currency	string	Yes	maxLength: 3	Currency code, capital letter see【Supported Country/Region and Currency】
data.country	string	Yes	maxLength: 2	Country code, capital letters，If the passed country code does not match the currency, the cashier will be displayed in the region corresponding to the currency code. If a payment method is specified, the country must be sent, see【Supported Country/Region and Currency】
data.userId	string	Yes	maxLength: 64	The user ID of the merchant, needs to ensure the uniqueness of each user ID. After the payment method is bound, the payment method will be recommended according to the userId.
data.expireTime	string	No	maxLength: 16	Define the payment duration in seconds, If the order has not been completed within the duration, it will be closed. The range is 1800~86400.
data.referralCode	string	No	maxLength: 32	Used for more accurate payment method recommendations, such as device ID, device fingerprint, etc.
data.mitManagementUrl	string	No		merchant subscription plan management address
data.subscriptionPlan	object	No		subscription plan info
data.subscriptionPlan.subscriptionNo	string	No		PayerMax subscription plan management order number
data.subscriptionPlan.subject	string	No		subscription topic, required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.description	string	No		subscription description, required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.totalPeriods	string	No		total subscription periods. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.periodRule	object	No		subscription rules
data.subscriptionPlan.periodRule.periodUnit	string	No		subscription deduction cycle, deduct by month (M), day (D), week (W), year (Y). Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.periodRule.periodCount	string	No		subscription deduction frequency. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.periodAmount	object	No		fixed period deduction amount. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.periodAmount.amount	number	Yes		fixed period deduction amount. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.periodAmount.currency	string	Yes		fixed period deduction currency. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.firstPeriodStartDate ⚠️	string	No		First deduction time of subscription plan. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.trialPeriodConfig	object	No		discount period rules
data.subscriptionPlan.trialPeriodConfig.trialPeriodCount	string	Yes		discount period count.
data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount	object	Yes		discount deduct amount.
data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.amount	number	No		discount deduct amount. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.trialPeriodConfig.trialPeriodAmount.currency	string	No		discount deduct currency. Required when payment method is APPLEPAY or GOOGLEPAY and merchant manages subscription plan
data.subscriptionPlan.trialConfig	object	No		Subscription trial for n days information
data.subscriptionPlan.trialConfig.trialAmount	object	Yes		Trial fee information
data.subscriptionPlan.trialConfig.trialAmount.amount	number	Yes		Trial fee
data.subscriptionPlan.trialConfig.trialAmount.currency	string	Yes		Trial currency
data.subscriptionPlan.trialConfig.trialDays	number	Yes		Trial days
data.paymentDetail	object	Yes		Payment method information.
data.paymentDetail.tokenForFutureUse	boolean	No		true means that the user has been authorized to bind payment information for subsequent use, the default is false
data.paymentDetail.sessionKey	string	No		It is used as a sessionKey for Drop-In payment.
data.paymentDetail.paymentToken	string	No	maxLength: 64	It is used as a token for Drop-In payment.
data.paymentDetail.buyerInfo	object	Yes		buyer information.
data.paymentDetail.buyerInfo.clientIp	string	Yes		The user's IP address. Must be in standard IPv4 or IPv6 format.
data.paymentDetail.buyerInfo.userAgent	string	Yes		User browser information.
data.paymentDetail.merchantInitiated	boolean	No		Indicates whether it is a MIT transaction. If not passed, it defaults to false.
data.paymentDetail.mitType	string	No		mit type	SCHEDULED, UNSCHEDULED
data.subMerchant	object	No		Submerchant Information, Platform merchants need to submit sub-merchant information.
data.subMerchant.subMerchantNo	string	No	maxLength: 64	Submerchant ID.
data.language	string	No	maxLength: 16	Cashier page language.【Supported Country/Region and Currency】 The priority is: the language last used by the user > the language of the user's browser > the country language of the user's IP > the language of the merchant's order > Default EN
data.terminalType	string	Yes	maxLength: 3	Device terminal, WEB, WAP, APP.
data.osType	string	No		Device operating system, when the device terminal is Wap and App, the device operating system can be ANDROID or IOS.
data.frontCallbackUrl	string	Yes	maxLength: 1024	The redirect URL specified by the merchant, the user will be redirected to this address after completing the payment, starting with http/https or the scheme address of the merchant’s application. FrontCallbackUrl is mandated for API-only payment to support callback transactions that need to redirect to external links.
data.notifyUrl	string	No	maxLength: 256	Server-side callback notification URL, starting with http/https The merchant notification address can be configured through the MerchantDashboard platform. If the transaction is uploaded, the transaction shall prevail.Note: If the merchant platform does not configure a notifyUrl and the transaction does not have a sending notifyUrl, callback notification cannot be made.

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://frontCallbackUrl.example.com",
    "subject": "GoGeal PTE. LTD.",
    "outTradeNo": "123456789",
    "notifyUrl": "http://notifyUrl.example.com",
    "currency": "HKD",
    "userId": "3ff0495692d152be96d84dbc9352dc57",
    "integrate": "Direct_Payment",
    "terminalType": "WEB"
  }
}

Responses

200

Field	Type	Required	Constraints	Description	Enum
code	string	Yes		Return code, ‘APPLY_SUCCESS’ means success.It only represents the success of the interface request, not the order status.
msg	string	Yes		Return message, ‘Success.’.It only represents the success of the interface request, not the order status.
data	object	No		Return data body.
data.outTradeNo	string	Yes	maxLength: 64	Merchant order id. order id.
data.tradeToken	string	Yes	maxLength: 64	PayerMax order id.
data.status	string	Yes	maxLength: 32	transaction status.
data.redirectUrl	string	No	maxLength: 1024	redirect link; Some payment methods need to jump to the outside to complete the payment.

Response Example: 1

成功示例

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

Response Example: 2

apm-redirect-response

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "redirectUrl": "https://cashier-n-uat.payermax.com/v2/index.html#/mocks?simulatorType=payment&pmaxUrlMock=1&referenceNo=UPC594700175093987893951000031&merchantId=SDP01010115045982&merchantAppId=d27183b7f2ea4822aa722d9efa8e7a8b&tradeToken=T2025062612594747000086&payRequestNo=20250626121118EP2094594711153204T05&token=8cfe3859f5f04c5783481a26089c6416",
    "outTradeNo": "orderAndPayOutTradeNo1750939878336UokUa96TMY",
    "tradeToken": "T2025062612594747000086",
    "status": "PENDING"
  }
}

Response Example: 3

apm-direct-response

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "vaCode": "TEST***001",
    "outTradeNo": "orderAndPayOutTradeNo1751265358900gHyeC8LHpb",
    "tradeToken": "T2025063006003647012140",
    "status": "PENDING"
  }
}

Response Example: 4

apm-qrcode-response

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "redirectUrl": "https://gopay.co.id/app/merchanttransfer?tref=A120240108055206Yf6o5risurID&amount=15000&activity=GP:RR&callback_url=https%3A%2F%2Fchannel.payermax.com%2Fin-pay-channel%2Fc%2FoutService%2FfrontCallbackV1%2FmidTrans%2FPPC788800170469312633195812771%2Fredirect%3Forder_id%3DPPC788800170469312633195812771",
    "qrCodeUrl": "https://api.midtrans.com/v2/gopay/b54f6b26-c3b8-4756-acb8-4c53097ab8ca/qr-code",
    "outTradeNo": "orderAndPayOutTradeNo17512653582106DuKJbyYzW",
    "tradeToken": "T2025063006734147012136",
    "status": "PENDING"
  }
}

Enum Reference

data.paymentDetail.mitType

• SCHEDULED
• UNSCHEDULED