Disbursement Request

• Endpoint: POST /aggregate-pay/api/gateway/paymentOrderPay
• Tags: Disbursement Service

Description

This interface is an API payment interface. Please pay attention to the following matters when returning parameters of this interface, otherwise there may be a risk of capital loss:

1. When "code": "APPLY_SUCCESS" and "status": "PENDING" is returned, it means the order is successfully placed. Please refer to the callback or query interface status for the order status;
2. When "code": "ORDER_REPEAT", it means that the outTradeNo has been ordered. Please wait for the callback or query interface to confirm the order status. Each order must be made to ensure that the outTradeNo is unique;
3. In other scenarios, please check the parameters and reinitiate without changing outTradeNo, and pay attention to resetting requestTime;

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: 63	Merchant Order Id, a unique identifier for a merchant transaction, must not be duplicated and can only contain letters, numbers, and underlines.
data.country	string	Yes	maxLength: 2	Country code, using capital letters, please refer:【Supported countries and currencies】.
data.chargeOption	string	No		Whether charge bearer mode of fees is required, please refer: 【Disbursement Application Template and Filling Specifications】
data.clearingRail	string	No		Enumerated values: SWIFT, SEPA, LOCAL, corresponding to the contracted payment methods SWIFT, SEPA, and Local Banks, respectively. Please provide the value based on the actual payment method being used, please refer: 【Disbursement Application Template and Filling Specifications】
data.userId	string	No	maxLength: 64	The user ID of the merchant, needs to ensure the uniqueness of each user.
data.sourceAccount	string	No	maxLength: 3	Currency code of the deduction account, in uppercase letters.
data.destinationCurrency	string	No	maxLength: 3	Specify the receiving  currency by referring to the 【Payment Method Types List】. If the receiving  currency is indicated in the payment method, please specify it. If not indicated, the receiving currency is limited to the local currency and no specification is required.
data.trade	object	Yes		Transaction Information.
data.trade.amount	string	Yes	maxLength: 12	The transaction amount should be submitted according to the Decimal separator place supported by the currencies of each country. Note: Indonesia, Vietnam, South Korea, and Chile do not support decimal amounts in local currency.
data.trade.currency	string	Yes	maxLength: 3	Transaction currency, uppercase letters.
data.payeeInfo	object	Yes		Payee Information.
data.payeeInfo.paymentMethodType	string	Yes	maxLength: 64	Payment method types, please refer:【Payment Method Types List】.
data.payeeInfo.targetOrg	string	No	maxLength: 64	Target organization, please refer:【Payment Method Types List】.
data.payeeInfo.payeeType	string	No		Payee type (PERSONAL/CORPORATION), default to PERSONAL
data.payeeInfo.accountInfo	object	Yes		Payee account information
data.payeeInfo.accountInfo.accountNo	string	Yes	maxLength: 128	Payee account, fill in the corresponding account number according to the payment method.
data.payeeInfo.accountInfo.accountType	string	No		The type of receiving account is regulated differently in different countries and payment methods.
data.payeeInfo.accountInfo.checkDigit	string	No		Verification number of payee’s account.
data.payeeInfo.bankInfo	object	No		Receiving bank information
data.payeeInfo.bankInfo.bankCode	string	No	maxLength: 64	It is used to identify the bank code of the payee under a specific financial institution, and the filling specifications are different in different countries, refer to 【Disbursement Application Template and Filling Instructions】以及【List of supported bank ranges】.
data.payeeInfo.bankInfo.bankName	string	No	maxLength: 255	Name of payee’s bank.
data.payeeInfo.bankInfo.bankBranch	string	No	maxLength: 64	Payee’s bank branch number/branch number.
data.payeeInfo.bankInfo.bankCity	string	No	maxLength: 255	City where the recipient’s bank is located.
data.payeeInfo.bankInfo.corAccountNo	string	No	maxLength: 128	Agent account number of the payee’s bank(correspondent account).
data.payeeInfo.name	object	No		The name of the payee, which supports English, spaces, commas, dashes, and dots, and can be filled in according to different standards in different countries and payment methods.
data.payeeInfo.name.firstName	string	No	maxLength: 64	First name of payee.
data.payeeInfo.name.middleName	string	No	maxLength: 64	The payee’s Middle name is separated by spaces when there are multiple Middle name.
data.payeeInfo.name.lastName	string	No	maxLength: 64	Family name of payee.
data.payeeInfo.name.fullName	string	No	maxLength: 512	Full name of payee.
data.payeeInfo.document	object	No		Receiving document information.
data.payeeInfo.document.documentType	string	No	maxLength: 16	The type of the payee’s personal identity certificate, the optional types are different in different countries, please refer: 【Disbursement Application Template and Filling Specifications】
data.payeeInfo.document.documentId	string	No	maxLength: 64	Payee’s personal identification number. The Option type varies in different countries, please refer: 【Disbursement Application Template and Filling Specifications】
data.payeeInfo.document.documentIssueDate	string	No	maxLength: 10	The effective date of the payee’s personal identification number, the optional type is different in different countries, the format is "yyyy-MM-dd".
data.payeeInfo.document.documentExpireDate	string	No	maxLength: 10	The expiration date of the payee’s personal identification number, the optional type is different in different countries, the format is "yyyy-MM-dd".
data.payeeInfo.address	object	No		Receiving address information.
data.payeeInfo.address.address	string	No	maxLength: 512	Address of payee.
data.payeeInfo.address.city	string	No	maxLength: 255	City of payee.
data.payeeInfo.address.state	string	No	maxLength: 255	State.
data.payeeInfo.address.zipCode	string	No	maxLength: 32	Postal code of payee.
data.payeeInfo.payeePhone	string	No	maxLength: 64	The recipient’s mobile phone number is filled in according to different standards in different countries and payment methods.
data.payeeInfo.birthDate	string	No	maxLength: 10	Payee’s date of birth, in the format of "yyyy-MM-dd".
data.payeeInfo.email	string	No	maxLength: 64	Mailbox of payee.
data.payeeInfo.payeeNationality	string	No	maxLength: 2	payee Nationality, CN, US etc country code
data.payeeInfo.payeeGender	string	No	maxLength: 1	payee Gender, F or M, (F=Female，M=Male)
data.payeeInfo.payeeBirthCountry	string	No	maxLength: 2	payee BirthCountry, CN, US etc country code
data.payerInfo	object	No		Payer Information.
data.payerInfo.name	object	No		The name of the payer, which supports English, spaces, commas, dashes, and dots, and can be filled in according to different standards in different countries and payment methods.
data.payerInfo.name.firstName	string	No		First name of payer.
data.payerInfo.name.middleName	string	No		The payer’s Middle name is separated by spaces when there are multiple Middle name.
data.payerInfo.name.lastName	string	No		Family name of payer.
data.payerInfo.name.fullName	string	No		Full name of payer.
data.payerInfo.subMerchantNo	string	No	maxLength: 64	Sub merchant account. Unique identification of sub merchants in your system.
data.payerInfo.businessLegalName	string	No	maxLength: 70	Payment company registered name.
data.payerInfo.registrationCountry	string	No		The country where the payment company is registered, a 2-digit uppercase country code.
data.payerInfo.merchantCategoryCode	string	No		Payment company industry classification, enumeration value, DIGITAL_GOODS_MEDIA: digital entertainment products-media; DIGITAL_GOODS_APPLICATION: digital products-application software; TRAVEL_AGENCIES_AND_TRAVEL_RELATED_SERVICES: travel agencies; COURIER_SERVICES_AIR_AND_GROUND_AND_FREIGHT_FORWARDERS: express services-air, land and freight forwarders; ADVERTISING_SERVICES: advertising business; TELECOMMUNICATION_SERVICE: telecommunications services; COMPUTER_NETWORKS_AND_INFORMATION_SERVICES: computer network/information services; MISCELLANEOUS_GENERAL_MERCHANDISE: e-commerce-miscellaneous department stores.
data.payerInfo.payerId	string	No	maxLength: 70	Payment company's institution/platform merchant number.
data.riskParams	object	No		Risk control business data.
data.riskParams.registerName	string	No		Registered Account Holder Name
data.riskParams.registerNo	string	No		The user’s registration ID on the merchant’s website/app
data.riskParams.nickName	string	No		The user’s nickname on the merchant’s website/app
data.riskParams.thirdAccountNoType	string	No		Third Party Account Type: Enum value Facebook, Google, AppleID, Others.
data.riskParams.thirdAccountNo	string	No		Third-party account identification.
data.riskParams.bindEmail	string	No		Account binding email.
data.riskParams.bindPhoneNo	string	No		Account bound mobile phone number.
data.riskParams.accountLevel	string	No		Account level.
data.riskParams.vipLevel	string	No		VIP level.
data.riskParams.regTime	string	No		Account registration time, format："yyyy-MM-dd HH:mm:ss".
data.riskParams.lastLoginTime	string	No		Last login/active time, format: "yyyy-MM-dd HH:mm:ss".
data.riskParams.liveCountry	string	No		Current residential address (country dimension), such as CN.
data.riskParams.taxId	string	No		User Tax ID
data.riskParams.cumPayoutAmount	string	No		On the merchant side, the user’s cumulative successful withdrawal amount in the past three months (USD)
data.riskParams.cumPayoutTxn	string	No		The user’s cumulative number of successful withdrawals on the merchant side in the past three months
data.riskParams.accountBalance	string	No		The user is on the merchant side, and the current balance of the user account (gold coins/diamonds)
data.riskParams.expressMerchantID	string	No		For platform merchants, sellers registered on the platform register an account.
data.expiryDays	string	No		The validity days of the withdrawal code are currently only valid in FawryCash. It supports inputing integers in range of 1 to 15 (1=24Hours), and defaults to 7 if other values are not input.
data.remark	string	No		Postscript or remarks for disbursement, allows format of English, numbers, dash lines, spaces and dots; Due to channel constraints, this field may undergo special processing, such as ultra long truncation or filling in default values.
data.reference	string	No	maxLength: 255	A pass-through parameter, which will be returned the same in the notification callback API. This field is primarily to hold customized data from merchant.
data.notifyUrl	string	No	maxLength: 255	The backend callback address for merchants to receive payment results, starting with http/https.
data.notifyEmail	string	No	maxLength: 64	Recipient notification email. Currently, only certain payment methods, such as FAWRY, send withdrawal code emails.
data.notifyPhone	string	No	maxLength: 64	Recipient notification phone number.
data.purpose	string	No	maxLength: 32	Disbursement purpose,enumeration value, ISUBIL:Pay to utilities (i.e. water, electricity, gas bills); EPTOUR:Tourism; EPTKAG:Pay for travel tickets or travel agency fees; ISPAYR:Pay Salary; ISPAYRA:Pay Agent Salary; ISGDDS:Goods Trade; ISSCVE:Purchase and Sale of Services; ISSUPP:Supplier Payment; ISLOGS:Logistics and Transportation Service Payment; INCEN:Incentive/Promotion/User Acquisition Activity; GAME:Gaming Equipment, Game Coins, and Other Game Items; SAMENM:Same Name Business Account Transfer; PAYCMSN:Reimbursement/Benefit Distribution/Commission Distribution; SAMENMC:Legal Person/Shareholder/Director Personal Account; AGOPEXP:Agency operating expenses; ADEXP:Advertising expenses;RFND:Refund;SMCNTST:Sub merchant settlement;LGTEP:Logistics expenses;GOODPAY:Goods payment;SINVEST:Investment in shares;FINVEST:Fund investment;TAXPAY:Tax payment;LOANPAY:Payment of loans; OTHER:Other;

Example

{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2023-03-08T10:00:00.500+08:00",
  "appId": "6666c83333a24666674497c444a33333",
  "merchantNo": "010213834123456",
  "data": {
    "outTradeNo": "orderorder1650532228089613",
    "country": "ID",
    "userId": "abc123456789",
    "riskParams": {
      "registerName": "lily",
      "regTime": "2023-07-01 12:08:34",
      "liveCountry": "VN",
      "payerAccount": "987654XXX",
      "payerName": "lily",
      "taxId": "1234567890"
    },
    "sourceAccount": "USD",
    "destinationCurrency": "USD",
    "trade": {
      "amount": "100",
      "currency": "IDR"
    },
    "payeeInfo": {
      "paymentMethodType": "WALLET",
      "targetOrg": "DANA",
      "payeeType ": "PERSONAL",
      "accountInfo": {
        "accountNo": "0812323233332",
        "accountType": "",
        "checkDigit": ""
      },
      "bankInfo": {
        "bankCode": "",
        "bankName": "",
        "bankBranch": "",
        "bankCity": "",
        "corAccountNo": ""
      },
      "name": {
        "firstName": "James",
        "middleName": "Shri Williams",
        "lastName": "Kanta",
        "fullName": "James Shri Williams Kanta"
      },
      "document": {
        "documentType": "",
        "documentId": "",
        "documentIssueDate": "",
        "documentExpireDate": ""
      },
      "address": {
        "address": "",
        "city": "",
        "state": "",
        "zipCode": ""
      },
      "payeePhone": "08123456789",
      "birthDate": "1996-09-01",
      "email": "example@gmail.com",
      "payeeNationality": "ID",
      "payeeGender": "M",
      "payeeBirthCountry": "ID"
    },
    "payerInfo": {
      "businessLegalName": "",
      "registrationCountry": "",
      "merchantCategoryCode": "",
      "payerId": ""
    },
    "expiryDays": "3",
    "remark": "this is remark",
    "reference": "this is reference",
    "notifyUrl": "http://example.com/callback/",
    "notifyEmail": "example@gmail.com",
    "notifyPhone": "",
    "purpose": "GAME"
  }
}

Responses

200

Field	Type	Required	Constraints	Description	Enum
code	string	Yes		API response code, ‘APPLY_SUCCESS’ means success. Indicates that the interface request is successful, but does not indicate the order status.
msg	string	Yes		Response description, ‘Success.’
data	object	Yes		Response data body.
data.outTradeNo	string	Yes		Merchant Txn Number.
data.tradeNo	string	Yes		PayerMax transaction serial Order Number.
data.status	string	No		Transaction status.

Response Example: 1

成功示例

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "tradeNo": "20220429052556PO71330000270184",
    "outTradeNo": "ORDER123456",
    "status": "PENDING"
  }
}

Response Example: 2

异常示例

{
  "msg": "The payment account info format is incorrect.",
  "code": "PARAMS_INVALID"
}

Response Example: 3

异常示例2

{
  "msg": "The targetOrg is incorrect.",
  "code": "PARAMS_INVALID"
}