Create order
Creates an order.
API URL
UAT : https://uat.test2pay.com/sgs/api/acquire2/placeOrder
Production : https://api.payby.com/sgs/api/acquire2/placeOrder
Request
Http Header
Attributes
Content-Language String
The language in which the response message will be used, currently only English is supported.
Example value: en
Maximum length: 10
Content-Type String Required
The media type. Required for operations with a request body. The value is application/<format>, where format is json.
Example value: application/json
sign String Required
Requests should be signed using private-key cryptography. This allows the payment gateway to verify that an incoming request is really from your application.
Partner-Id String Required
The merchant id of your account.
Example value: 200001200101
Maximum length: 12
Http Body
requestTime Timestamp Required
Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.
Example value: 1581493898000
bizContent Object
The attributes are:
merchantOrderNo String Required
The merchant's reference number of the request. Used to track every request.
Example value: M965739182419
Maximum length:
64
subject String Required
Description of this order.
Example value: iPhone
Maximum length:
12totalAmount Money Required
The attributes are:
amount Decimal Required
Allow 12 digits before the decimal point. Allow 2 digits after the decimal point.
Example value: 12.34
- currency String Required
The code to identify the order currency. Currently only AED is supported.
Example value: AED
expiredTime Timestamp
The order expiration time, after which the payment cannot be completed.
The value should not exceed 48 hours after the request time. If no parameter is passed, the default expiration time is 2 hours after the request time.
Example value: 1581493898000
payeeMid String
The payee can be another merchant. If no parameter is passed, the default payee is the merchant itself.
Example value: 200001200101
Maximum length:
12
paySceneCode Enum Required
Payment scene you are going to use. The possible values are
PAYPAGE,INAPP,EWALLET,DYNQR,QRPAY,JSAPI,AUTODEBIT,DIRECTPAY, etc.Select from the drop down to get parameters that need to be passed in different scenarios.
paySceneParams String Attributes
Paypage
(Hosted paypage & iFrame paypage)
PayScene parameters
redirectUrl String
Link that the payer will be redirected once the payer finalizes payments on PayBy's checkout.
Example value: https://www.yoursite.com
Maximum length:
512.customerId String
The payer's id in the merchant's system. If this parameter is used, after the user enters the card details and completes the payment for the first time, PayBy will save the card under the customer id. When another transaction is made, the payer will see the saved card on the PayPage checkout. Then the customer only needs to enter cvv to complete the transaction without entering card number, holder name and card expiration time again. In this scenario, the payer's card information won't be returned to the merchant. The saved cards can only be viewed and managed by the payer on the checkout.
changePayer String
If the user pays with BOTIM / PayBy, whether to bind the payer information to the order after the user scanning the code. If false, if user A does not complete the payment after scanning the QR code, other users can continue to scan the QR code to pay. If true, if user A does not complete the payment after scanning the QR code, other users will fail when they try to scan the QR code to pay. The default value is true.
Default value: True.
oneTimePayment String
When passed true, it means that the merchant requires the order to be paid only once. For example, if an order is not paid successfully the first time, the user will not be allowed to continue trying to pay for the order. When passed false, the order can be paid multiple times before it's successful.
Default value: False.
sharingParamList List
With every payment, you can split the funds between your merchant account and other PayBy member IDs. For example, a payment of 10 AED, if you share 1 AED to A and 2 AED to B, you will get 7 AED.
The attributes of each item in the list are:
sharingIdentitySeqId Money Required
You can pass multiple account ids to split the payment amount, in order to distinguish them, the serial number is needed. Please start with 1, then 2, 3, 4, etc.
Example value:
1sharingIdentityType String Required
The fund can be transferred to the beneficiary through mobile phone number, PayBy member id or BOTIM member id.
The possible values are:
PHONE_NO. Transfer through mobile phone number.MEMBER_ID. Transfer through PayBy member id.
Maximum length:
20sharingIdentity String Required
After selecting the identity type, what value should be passed. The parameter needs to be encrypted when passed, and SHA-256 algorithm is recommended.
For
PHONE_NO, example value: +971-585812345For
MEMBER_ID, example value: 100006514321Maximum length:
20sharingMemo String Required
Add some description to this operation.
sharingAmount Money Required
The amount you plan to split to this id.
withholdAndRemitFee Boolean
Whether this sharing account pay the PayBy transaction fee. If
true, the final amount this sharing account received is : [sharingAmount - PayBy transaction fee].Note :
If there are multiple sharing accounts in this order request, at most one can pass
truein this parameter, otherwise the request will fail.If this parameter is used, when a refund is initiated, only the proportional refund can be made, and the refund amount of each sharing account cannot be specified.
notifyUrl String
To receive asynchronous notifications of order status updates, you can pass the notify URL.
Example value: https://www.yoursite.com
Maximum length:
200
secondaryMerchantId String
If you are a platform and the transaction was made at a merchant under your platform, you can use this parameter to allocate the funds collected. To learn more about this feature please contact PayBy. The secondary merchant id represents the merchant's member id on your platform.
Maximum length:
200
deviceId String
If the transaction wad made on a terminal or virtual device, the device id can be passed for transaction data statistics. Note that this parameter must be passed if you are using the secondary merchant function, this parameter must be passed.
Maximum length:
200
accessoryContent
This can be useful for storing additional information about the order.
Attributes
amountDetail
discountableAmount Money
Discount amount for this order.The money object contains the following parameters.
amount Decimal Required
Allow 12 digits before the decimal point. Allow 2 digits after the decimal point.
Example value: 12.34
currency String Required
The code to identify the order currency. Currently only AED is supported.
Example value: AED
amount Money
The subtotal order amount, before discounts, taxes and tips.
vatAmount Money
The VAT amount for this order.
tipAmount Money
The tip amount for this order.
GoodsDetail
Goods Details
body String
The product’s description.
Example value: New Apple iPhone 13 Pro (128GB) - Sierra Blue
Maximum length:
200.categoriesTree String
A category tree enables you to view all of the rule-based categories in a collection.
Maximum length:
200.goodsCategory String
The category of the product.
Example value: Mobiles, Tablets & More.
Maximum length:
200.goodsId String
Unique identifier for the product.
Maximum length:
200.goodsName String
The product's name.
Example value: iPhone
Maximum length:
200.price Money
The product's unit price.
quantity Decimal
The quantity of the product. Allow 12 digits before the decimal point. Allow 2 digits after the decimal point.
Example value: 12.34
Maximum length:
200.showUrl String
A publicly-accessible webpage for this product.
Example value: https://www.yoursite.com
Maximum length:
200.
TerminalDetail
Terminal Details
operatorId String
ID of the employee who used the device to collect money. The id is generated by the merchant system.
Example value: 200123
Maximum length:
200.storeId String
In which store the customer pays. The id is generated by the merchant system.
Example value: S00001.
Maximum length:
200.terminalId String
The device on which the customer made the payment. The id is generated by the merchant system.
Example value: T00001
Maximum length:
200.merchantName String
In which merchant the customer pays. The name is stored by the merchant system.
Example value: Good Pharmacy
Maximum length:
200.storeName String
In which store the customer made the payment. The name is stored by the merchant system.
Example value: Good Pharmacy- First branch
Maximum length:
200.
reserved String
Merchant's notes for the order.
Example value: June campaign order.
Maximum length:
200
Request sample
Http Header
{
"Content-Language": "en",
"Content-Type": "application/json",
"sign": "IXJI/QicPQotIsIDBcSGIg6jtJUXs1rTuifQFZUNd3KDTl25GKmpYO7OrkaKkTV0shDRitLmkxJCe3Z60zHE2ZSeVczrhwrnmuMG+bX9N22Hw821H6MydsXetYHRnyf5dPbgpmVja582w49grA6jRlVFAVMYdxKJDPSCb2X/IpltvyrLQ1Wt+lqr+fnpYXvyON6/PIZIQIknC8BVddVahxJnaC6HEagvJf6gskz22/DFfPHT1mlMA9pg8qrbh4O7DYZahf8TB3nIzAPc/FHOUZkYYTT2c8m4eLL8740nJVK7D3IOSqSnBAU/iJ2omjPPFvRCCSqzz17pkGsT7AW91w==",
"Partner-Id": "200000000888"
}
Http Body
{
"requestTime": 1581404947666,
"bizContent": {
"merchantOrderNo": "M965739182419",
"subject": "Your subject",
"totalAmount": {
"currency": "AED",
"amount": 1.01
},
"paySceneCode": "PAYPAGE",
"paySceneParams": {
"redirectUrl": "http://www.yoursite.com?orderId=123"
},
"reserved": "order desc",
"notifyUrl": "http://www.yoursite.com",
"accessoryContent": {
"amountDetail": {
"vatAmount": {
"currency": "AED",
"amount": 20.65
},
"amount": {
"currency": "AED",
"amount": 1.09
}
},
"goodsDetail": {
"body": "Gifts",
"categoriesTree": "CT12",
"goodsCategory": "GC10",
"goodsId": "GI1005",
"goodsName": "candy flower",
"price": {
"currency": "AED",
"amount": 10.87
},
"quantity": 2
},
"terminalDetail": {
"operatorId": "OP1000000000000001",
"storeId": "SI100000000000002",
"terminalId": "TI100999999999900",
"merchantName": "candy home",
"storeName": "lovely house"
}
}
}
}
Response
Http Header
sign String Required
When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.
Http Body
head
Attributes
applyStatus Enum Required
The result of the request. The possible values are:
SUCCESS- Application successful.FAIL- Application failed. Check thecodeandmsgfor exact reason.ERROR- Application error. The signature verification failed. Please check whether the private key used for the signature and the public key uploaded on the PayBy portal are one key pair.code String Required
Response Codes.
Example value: 0
msg String
Description of this code.
traceCode String
No special meaning, PayBy internally used to locate the error.
body
Notice :Body is returned only when applystatus = success, and code = 0. If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.
acquireOrder Object
Attributes
requestTime Timestamp Required
Request time passed by the merchant when placing the order.
Example value: 1581493898000
merchantOrderNo String Required
The merchant's reference number of the request. Used to track every request.
Example value: M965739182419
Maximum length:
64orderNo String Required
The PayBy's unique identification number of the order.
Example value: 131658300517875854
status Enum Required
The possible values are:
CREATED. The order has been created.PAID_SUCCESS. The order has been successfully paid.SETTLED. The order has been paid and the fund has been settled to merchant's account.FAILURE. The order has been cancelled or expired.paymentInfo Object
paidAmount Money Required
The amount actually paid by the user. If a discount is used, it will be different from the order amount.
paidTime TimeStamp Required
Payer's successful payment time
Example value: 1581493898000
payerMid String
If the payer uses a BOTIM or Pay By wallet for payment,
payerMidrepresents the payer's member ID in the wallet.Example value: 200001200101
payerFeeAmount Money
If the order transaction fee is set to be charged from the payer,
payerFeeAmountrepresents the actual amount of the transaction fee.payeeFeeAmount Money
If the order transaction fee is set to be charged from the payee,
payeeFeeAmountrepresents the actual amount of the transaction fee.payChannel String Required
The payment channel used by the payer. The possible values are
BANKCARD,INSTALLMENT,EWALLET, etc.
settlementAmount Money Required
The actual funds the payee can receive after deducting transactions fees and amount for other reasons.
- cardInfo
This object may be returned only for `DIRECTPAY` payment scene.The attributes are:
brand String Required
The card issuer. The possible values are:
MASTERCARD>VISA>AE>DISCOVER>JCcardId String
If the payer's card information was requested to be saved for future use., PayBy will return the card's ID.
Example value: 31658300
last4 String Required
Last 4 digits of card number.
Example value: 6345
cardType String Required
The possible values are:
DC. Debit CardCC. Credit CardexpMonth String Required
Two -digit number, representing the card expiry month.
Example value: 01
expYearString Required
Two -digit number, representing last two digits of the card expiry year.
Example value: 22
product String Required
The product name related to the payment scene parameter used in the order. This product name is only used for PayBy internal classification.
Example value: Basic Payment Gateway
totalAmount Money Required
The order amount intended to collect from the payer.
payeeMid String Required
The payee's member ID in PayBy.
Example value: 200001200101
expiredTime TimeStamp Required
The order expiration time, after which the payment cannot be completed.
Example value: 1581493898000
notifyUrl String Required
To receive asynchronous notifications of order status updates, the merchant can pass the notify URL in the request to place order.
Example value: https://www.yoursite.com
sharingInfoList List
If the sharing information is passed in the request, PayBy will return the actual amount received by each sharing account.
The attributes of each item in the list are:
sharingIdentitySeqId Money Required
You can pass multiple account ids to split the payment amount, in order to distinguish them, the serial number is needed. Please start with 1, then 2, 3, 4, etc.
Example value:
1sharingMid String Required
If the sharingIdentityType and sharingIdentity passed in the request can be corresponded to a member id that already exists in the PayBy system, in the response PayBy will return the member id.
sharingMemo String Required
Add some description to this operation.
sharingAmount Money Required
The amount you plan to split to this id.
sharingSettledFeeAmount Money Required
If the withholdAndRemitFee is
true, which means that this sharing account should pay the PayBy transaction fee, the sharingSettledFeeAmount represents the transaction fee PayBy charged in this order.sharingSettledAmount Money Required
The amount this id actually received. If the order is not settled in real-time and a refund occurs before settlement, or this id should pay the PayBy transaction fee, the requested amount will be different from the actual amout received.
withholdAndRemitFee Boolean
The values passed in the request. This parameter means that whether this sharing account pay the PayBy transaction fee. If
true, the final amount this sharing account will receive is : [sharingAmount - PayBy transaction fee].Note that if there are multiple sharing accounts in this order request, at most one can pass
truein this parameter, otherwise the request will fail.
subject String Required
Description of this order.
Example value: iPhone.
accessoryContent String
Used for storing additional information about the order.
paySceneCode Enum Required
Payment scene used to create the order. The possible values are
PAYPAGE,INAPP,EWALLET,DYNQR,QRPAY,JSAPI,AUTODEBIT,DIRECTPAY, etc.paySceneParams String Required
Different payment scenarios need to pass different scenario parameters.
deviceId String
If the transaction was made on a terminal or virtual device, the device id can be passed for transaction data statistics. Note that this parameter must be passed if you are using the secondary merchant function.
secondaryMerchantId String
If you are a platform and the transaction was made at a merchant under your platform, you can use this parameter to allocate the funds collected. To learn more about this feature please contact PayBy. The secondary merchant id represents the merchant's member id on your platform.
Maximum length:
200failCode String
If the order status is
FAILURE, the code to identify the exact reason.Example value: 504
failDes String
If the order status is
FAILURE, the failure reason.Example value: SERVICE_TIMEOUT
revoked String Required
If true, it means that the payment has been made but then cancelled.
reserved String
Merchant's notes for the order.
Example value: June campaign order.
Maximum length:
200
interactionParams
In different payment scenarios, PayBy may return different parameters, allowing the merchant system and PayBy continue to interact to complete the order.
tokenUrl String
Appears only in the following payment scene.
PAYPAGE. A link that redirects the payer to the paypage.INAPP. A link that redirects the payer to the paypage or the chosen E-wallet.DYNQR. A link contains details of the order, the merchant needs to convert it to a QR code and present to the payer.JSAPI. A link that redirects the payer to the checkout within the APP.CASHTOPUP. A link contains details of the order, the merchant needs to convert it to a QR code and present to the payer.PAYANDSIGN. A link that redirects the payer to the checkout within the APP.deepLink String
Appears only in
EWALLETpayment scene.When the payer chooses to open another e-wallet for payment at the merchant's payment page, PayBy will return a link to redirect the payer to the e-wallet's checkout.
threeDSecureDom String
Appears only in
DIRECTPAYpayment scene.If the merchant decides or PayBy's risk control system recognizes that the transaction requires 3DS verification, the 3DS verification link will be returned.
The
AUTODEBITandQRPAYpayment scene don't haveinteractionParams.
Response sample
Http Header
{
"sign": "JzWjVQ245trg3p0CyuwUUHN+Ck40q/HDaMvhqueHDP8YHqC/Uw3c9VWCw4gKsNbk+CRShjT+bvKkck8Fc3aAiRK8wIVQz6eu95sPkJgZp5A0P+tfMH/44F+3CrejtbEIkrHdSwhy98Tv9TYs9QFe7Yni/vEJ8P4OU6FZJOi8LGOMF6Nc8+S5qftc7qLA17cNJ7NJYC+EW8suGe/NmGA9c5NMK5BwHTHzXYOjXwXLx8mw4M3hiirl0wtVym3hrOmbkujYZCH56h8uOVF0FbHGu5uoq61NuniJitLLs9qyiEprQzUe8oWsJnHKXeGAgEr//fLXIXgYsRYb7AWoJzs6Eg=="
}
Http Body
{
"body":{
"acquireOrder":{
"accessoryContent":{
"amountDetail":{
"vatAmount":{
"amount":1,
"currency":"AED"
}
},
"goodsDetail":{
"body":"gifts",
"goodsId":"GI1005",
"goodsName":"candy flower"
},
"terminalDetail":{
"merchantName":"MEPAY"
}
},
"expiredTime":1685959558902,
"merchantOrderNo":"353f55fe-d037-4000-b1fc-9e189c935b13",
"notifyUrl":"http://yoursite.com/api/notification",
"orderNo":"131685952361009035",
"paySceneCode":"PAYPAGE",
"payeeMid":"200000030907",
"product":"Basic Payment Gateway",
"requestTime":1685952358902,
"reserved":"order desc",
"revoked":"false",
"sharingInfoList":[
{
"sharingAmount":{
"amount":1,
"currency":"AED"
},
"sharingIdentitySeqId":1,
"sharingMemo":"cashback",
"sharingMid":"200000050714"
}
],
"status":"CREATED",
"subject":"ipad",
"totalAmount":{
"amount":10,
"currency":"AED"
}
},
"interActionParams":{
"tokenUrl":"https://paypage.payby.com?BIZ_TYPE=202&ft=dd89cd1b-627c-475c-b60c-8ae3a8faa4d8&t=1581404956715"
}
},
"head":{
"applyStatus":"SUCCESS",
"code":"0",
"msg":"SUCCESS",
"success":true,
"traceCode":"619443"
}
}