Skip to main content

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 referece 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: 12


  • totalAmount 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.


    • oneTimePayment Boolean

      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 succesful.

      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: 1


    • sharingIdentityType String Required

      The fund can be transfered 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.

      TOTOK_UID. Transfer through Totok member id.

      Maximum length: 20


    • sharingIdentity 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-585812345

      For MEMBER_ID, example value: 100006514321

      Maximum length: 20


    • sharingMemo String Required

      Add some description to this operation.


    • sharingAmount Money Required

      The amount you plan to split to this id.


  • 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 secondery 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 Dtails
      • 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 Dtails
      • 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 the code and msg for 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 referece number of the request. Used to track every request.

      Example value: M965739182419

      Maximum length: 64


    • orderNo 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, payerMid represents 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, payerFeeAmount represents the actual amount of the transaction fee.


      • payeeFeeAmount Money

        If the order transaction fee is set to be charged from the payee, payeeFeeAmount represents the actual amount of the transaction fee.


      • payChannel String Required

        The payment channel used by the payer. The possible values areBANKCARD, 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 attibutes are:

        brand String Required

        The card issuer. The possible values are:

        MASTERCARD >VISA >AE >DISCOVER >JC


        cardId 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 Card

        CC. Credit Card


        expMonth 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 amout 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


    • 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: 1


      • sharingMid String Required

        If the sharingIdentityType and sharingIdentity passed in the request can correspond 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.


    • 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 wad made on a terminal or virtual device, the device id can be passed for transaction data statistic. 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: 200


    • failCode 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 Boolean 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.


    • deepLink String

      Appears only in EWALLET payment 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 DIRECTPAY payment 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 AUTODEBIT and QRPAY payment scene don't have interactionParams.


Response sample

Http Header
{
"sign": "JzWjVQ245trg3p0CyuwUUHN+Ck40q/HDaMvhqueHDP8YHqC/Uw3c9VWCw4gKsNbk+CRShjT+bvKkck8Fc3aAiRK8wIVQz6eu95sPkJgZp5A0P+tfMH/44F+3CrejtbEIkrHdSwhy98Tv9TYs9QFe7Yni/vEJ8P4OU6FZJOi8LGOMF6Nc8+S5qftc7qLA17cNJ7NJYC+EW8suGe/NmGA9c5NMK5BwHTHzXYOjXwXLx8mw4M3hiirl0wtVym3hrOmbkujYZCH56h8uOVF0FbHGu5uoq61NuniJitLLs9qyiEprQzUe8oWsJnHKXeGAgEr//fLXIXgYsRYb7AWoJzs6Eg=="
}

Http Body
{
"head": {
"applyStatus": "SUCCESS",
"code": "0",
"msg": "SUCCESS",
"traceCode": "1127"
},
"body": {
"acquireOrder": {
"merchantOrderNo": "M965739182419",
"orderNo": "131404956265007836",
"status": "CREATED",
"product": "Basic Payment Gateway",
"totalAmount": {
"currency": "AED",
"amount": 1.01
},
"payeeMid": "200000000888",
"expiredTime": 1581412155966,
"notifyUrl": "http://www.yoursite.com",
"subject": "Your subject",
"requestTime": 1581404955966,
"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"
}
},
"paySceneCode": "PAYPAGE",
"interActionParams": {
"tokenUrl": "https://paypage.payby.com?BIZ_TYPE=202&ft=dd89cd1b-627c-475c-b60c-8ae3a8faa4d8&t=1581404956715"
}
}
}
}