Revoke order

In the case that the merchant does not receive a response of payment order and wants to cancel the order, the merchant can request a revoke of the payment order. If the payment order is unsuccessful, the payment order will be Cancelled. If successful, a refund will be initiated, and the payment order will be tagged as Revoked.

API URL

UAT: https://uat.test2pay.com/sgs/api/acquire2/revokeOrder

Production: https://api.payby.com/sgs/api/acquire2/revokeOrder

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

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

You can use either merchantOrderNo or orderNo to specify an order. But you can't use the two parameters at the same time.

merchantOrderNo String Required
The merchant's reference 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

Request sample

Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "RXF8WmC67QSnr62l3oU33fjpUvAo6Yrgvk05c/vYLtmHRGMoAH4qSnap2pto3mY7KgyP5wkNUsyQXJ/ZwbfccSONLb5zA7Z7q74IsOwdJw3BKXxVWr4tfjkA02Pfcp0cZWjE/Y8jTcbtgdc5VI90LNmkgPWbrSlDbNW8p3NlhnKg+Xfl95SgMBPF9afttsU/2a5jLnZXSVcXoSthxpJ6XkZwd45+jhOjBguT+IC8uLVSNRvwDisRGgf9PYv39OH6ITEhbY2sgjkdzBZBOZlt7awy2vkMEsePsuafwrNhuz7xzjj55PzNzk8+zCUu/791OhC/eFUyGimtDw5mX9cyQw=="
}

Http Body
{
    "requestTime": 1581406091642,
    "bizContent": {
        "merchantOrderNo": "M818494241569"
    }
}

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 reference 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 attributes 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 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: 1
  
  sharingMid 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 true in 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: 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 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

Response sample

Http Header
{
    "sign": "nDdClX1tAyV3qcX/Epay6AXFNRGSsWd8ysWO9SgwPrNTetSePLA9C39mGp6qRbjJeqXLEnYLwSkBu5eKdtyVX3tflGLiV2kvRjVfYpTCjXdVL2Pcnv2w+ghjHe2jL988iklk7q5AjAgdtXNphpHcTes9pk6W3bVCbvijH6at0fExUtZ91L1LrnPGELT1IJm/lFW3w4KLh0Gxs7FzDPI9RDfUemObNlRzV8kCtkWahwPgs/hBnS69GyYDKN7ihQX2UiLuP239wl6IA+VG/ZZKHPhLs8bbuOS+LKWORIp6jRt+JsAx7c/Ot1RNyOnHKxPRKJ8bVTohEp39yUz/HwG8oA=="
}

Http Body
{
  "head": {
    "applyStatus": "SUCCESS",
    "code": "0",
    "msg": "SUCCESS"
  },
  "body": {
    "acquireOrder": {
      "merchantOrderNo": "M965739182419",
      "orderNo": "131404956265007836",
      "status": "FAILURE",
      "paymentInfo": {
        "paidAmount": {
          "currency": "AED",
          "amount": 1.01
        },
        "paidTime": 1581405372000,
        "payerMid": "100000001104",
        "payeeFeeAmount": {
          "currency": "AED",
          "amount": 0.5
        },
        "payerFeeAmount": {
          "currency": "AED",
          "amount": 0
        },
        "payChannel": "BALANCE"
      },
      "product": "Basic Payment Gateway",
      "totalAmount": {
        "currency": "AED",
        "amount": 1.01
      },
      "payeeMid": "200000000888",
      "expiredTime": 1581412155966,
      "notifyUrl": "http://www.yoursite.com",
      "subject": "Your subjet",
      "requestTime": 1581404955966,
      "accessoryContent": {
        "amountDetail": {},
        "goodsDetail": {},
        "terminalDetail": {}
      },
      "paySceneCode": "PAYPAGE",
      "revoked": "true"
    }
  }
}

Revoke order

API URL​

Request​

Http Header​

Http Body​

Request sample​

Response​

Http Header​

Http Body​

Response sample​

API URL

Request

Http Header

Http Body

Request sample

Response

Http Header

Http Body

Response sample