Skip to main content

Cancel Order

Overview​

If the payment result is not returned for a long time, you can use this interface to cancel the order. However, PayBy only supports cancellations when the order is in the CREATED status, and the order status will be updated to FAILURE after PayBy processed the cancellation request successfully.

If the order status has been updated to PAID_SUCCESS or SETTLED when the cancellation was initiated, PayBy will reject this request. It is recommended to use Revoke or Refund interface.

API URL​

Request​

Http Header​

Attributes

  • Content-Language String

    • Language in which the response message will be used.
    • Currently, only English is supported.
    • Example value: en
    • Maximum length: 10

  • Content-Type String Required

    • Media type of the request body.
    • Required for operations with a request body.
    • Format: application/<format> (e.g., application/json)
    • Example value: application/json

  • sign String Required

    • Request signature using private-key cryptography.
    • Ensures the payment gateway can verify the request origin.

  • Partner-Id String Required

    • 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

    Note: Use either merchantOrderNo or orderNo to specify an order, but never both 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",
    "sign": "MH8c9++jlzo0WBLJxNcbXxtyuAsE0EJzYtgnOsLDTrkG9rnF+tAf1NCDnJxUla0gQDQA5hjxMHKv42eZYrC/QR4cRvqSsnaUjtfOKbWcPEi4s6EcV/dHN0xPvDh5SPr9yAqrR44JRWzdXtG4P3zre57RbvXrhxZpXAkrwO0nXI4vMuKl1WsKSU0sdVqQx+v5cKXo8rK/iGGypLvH3VDya7m4ESo/GIvVanwyvItOZk/bY+L4KeZ+uuRNTXStYeBc4j4Oq1OrbYb0DwvDOijYl1qUt1pkZb5FWMfj8il0HQvbfhmMWRPsWeUObKJJfHJZNiwdV4SAWoHGtivw3/vu6A==",
    "Partner-Id": "200000000888"
}

// Http Body
{
    "requestTime": 1581422748669,
    "bizContent": {
        "merchantOrderNo": "M172475858661"
    }
}

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. Possible values:
      • SUCCESS: Application successful.
      • FAIL: Application failed. Check the code and msg for the exact reason.
      • ERROR: Application error. Signature verification failed. Ensure the private key used for the signature and the public key uploaded on the PayBy portal are a valid key pair.

  • code String Required

    • Response code.
    • Example value: 0
    • Maximum length: 10

  • msg String

    • Description of the response code.
    • Maximum length: 200

  • traceCode String

    • Internal code for locating the error.

body

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

      • Detailed payment information including fees and timestamps.

      • paidAmount Money Required

        • The amount actually paid by the user. If a discount is used, it will differ from the order amount.

      • paidTime Timestamp Required

        • Payer's successful payment time.
        • Example value: 1581493898000

      • payerMid String

        • Payer's member ID in the wallet (BOTIM or PayBy).
        • Example value: 200001200101

      • payerFeeAmount Money

        • Transaction fee charged to the payer.

      • payeeFeeAmount Money

        • Transaction fee charged to the payee.

      • payChannel String Required

        • Payment channel used by the payer.
        • Possible values: BANKCARD, INSTALLMENT, EWALLET, etc.

      • settlementAmount Money Required

        • Actual funds received by the payee after deductions.

      • 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

      • Product name related to the payment scene. Used for internal classification.
      • Example value: Basic Payment Gateway

    • totalAmount Money Required

      • The order amount intended to collect from the payer.

    • payeeMid String Required

      • Payee's member ID in PayBy.
      • Example value: 200001200101

    • expiredTime Timestamp Required

      • Order expiration time.
      • Example value: 1581493898000

    • notifyUrl String Required

      • URL to receive asynchronous notifications of order status updates.
      • Example value: https://www.yoursite.com

    • sharingInfoList List

      • Sharing information for split payments.

      • sharingIdentitySeqId Money Required

        • Serial number for multiple account IDs.
        • Example value: 1

      • sharingMid String Required

        • Member ID returned if identity matches an existing PayBy member.

      • sharingMemo String Required

        • Description of the sharing operation.

      • sharingAmount Money Required

        • Amount planned to be split to this ID.

      • sharingSettledFeeAmount Money Required

        • Transaction fee charged to this sharing account if applicable.

      • sharingSettledAmount Money Required

        • Actual amount received by this ID.

      • withholdAndRemitFee Boolean

        • Indicates whether this sharing account pays the transaction fee.
        • Only one account can have true in this field per request.

    • 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.
      • Possible values: 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: 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.
      • 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": "XBRRQzTFvIKPE4bhBLKXF23RBeJn7WytxwhQXutCTZgO7NmzVE0YufjbSUSFKB5Eg6EtrVMVFM/FmTSSI/hWBJnk0j8rBxb+K3FlplTw1ydStM7upkvxLOe2uoOkac8FFXZIvjRWDNY7+VXwo40yI33Ct3YLTwu5kQHhVCEf6ClvnkTynXuy6hxALFsbJchKOZNbqm5WA24x2VtFbNe+jz+CRwD4MD8xg6npPMwfTc0b4sZ7SkUAKYlttxm+nO9qFjczbp55R7LdajxfCXxgpTp0hc576pwo2AqyNDcMjzunynX+AR7pzDqwkgC1NIc/eax67HPq/X+v/T8t671sHg=="
}

// Http Body
{
  "head": {
    "applyStatus": "SUCCESS",
    "code": "0",
    "msg": "SUCCESS"
  },
  "body": {
    "acquireOrder": {
      "merchantOrderNo": "M172475858661",
      "orderNo": "131422372621002238",
      "status": "FAILURE",
      "product": "Basic Payment Gateway",
      "totalAmount": {
        "currency": "AED",
        "amount": 21.74
      },
      "payeeMid": "200000004021",
      "expiredTime": 1581429572587,
      "notifyUrl": "http://www.yoursite.com",
      "subject": "Your subject",
      "requestTime": 1581422372587,
      "accessoryContent": {
        "amountDetail": {
          "discountableAmount": {
            "currency": "AED",
            "amount": 2.31
          },
          "amount": {
            "currency": "AED",
            "amount": 20.65
          },
          "vatAmount": {
            "currency": "AED",
            "amount": 1.09
          },
          "tipAmount": {
            "currency": "AED",
            "amount": 0.02
          }
        },
        "goodsDetail": {
          "body": "Gifts",
          "categoriesTree": "CT12",
          "goodsCategory": "GC10",
          "goodsId": "GI1005",
          "goodsName": "candy flower",
          "price": {
            "currency": "AED",
            "amount": 10.87
          },
          "quantity": 2,
          "showUrl": "http://www.yourshop.com/index.htm"
        },
        "terminalDetail": {
          "operatorId": "OP10001",
          "storeId": "SI1002",
          "terminalId": "TI10000",
          "merchantName": "candy home",
          "storeName": "lovely house"
        }
      },
      "paySceneCode": "JSAPI"
    }
  }
}

Response Codes​

CodeMessageCauseWorkaround
0SUCCESSRequest successful—
400INVALID_PARAMETERInvalid request parametersAdjust request parameters
400REQUESTTIME_TOO_EARLYRequest time is too far in the pastAdjust request time
400REQUESTTIME_TOO_LATERRequest time is too far in the futureAdjust request time
402RATE_LIMIT_REJECTToo many requestsReduce request frequency
403UNAUTHORIZEDAPI not authorizedContact PayBy
404SERVICE_NOT_AVAILABLEAPI service unavailableContact PayBy
500SYSTEM_ERRORInternal system errorContact PayBy and retry later
504SERVICE_TIMEOUTService timeoutRetry later
601RISK_FAILRisk control validation failedAdjust business logic
62001ORDER_PAIDOrder already paid; cannot be canceledUse a different merchant order number
62002ORDER_FAILURECancellation attempted on a failed orderUse a different merchant order number
62003ORDER_SETTLEDCancellation attempted on a settled orderUse a different merchant order number
62004MERCHANT_ORDER_NO_NOT_EXISTMerchant order number does not existCheck and correct the merchant order number
62035ORDER_NO_NOT_EXISTPayBy order number does not existCheck and correct the PayBy order number