Retrieve Order Details

Overview

This interface allows merchants to retrieve detailed results of bank card transfer transactions. It provides comprehensive information about the transfer status, payment details, and transaction metadata.

API URL

• UAT Environment: https://uat.test2pay.com/sgs/api/transfer/getTransferToBankCard
• Production Environment: https://api.payby.com/sgs/api/transfer/getTransferToBankCard

Request

HTTP Headers

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(3) Required

  • Request timestamp in milliseconds.
  • Example value: 1581493898000

• bizContent GetTransferToBankOrderRequest Required

  • Business-specific request content.

  • merchantOrderNo String(64) Required

    • Unique order identifier from merchant system.
    • Example value: Me23484

Request Sample

HTTP Headers

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

HTTP Body

{
    "body": {
        "bizContent": {
            "merchantOrderNo": "M536433721888"
        },
        "requestTime": 1585142880000
    }
}

Response

HTTP Header

Attributes

• applyStatus String(16) Required

  • Request status result.
  • Example value: SUCCESS
  • Possible values:
    • SUCCESS: Application successful
    • FAIL: Application failed
    • ERROR: Exception occurred

• code String(10) Required

  • Return error code.
  • Example value: 0

• msg String(200)

  • Return message.

HTTP Body

Attributes

• requestTime Timestamp(3) Required

  • Request time passed by the merchant when placing the order.
  • Example value: 1581493898000

• merchantOrderNo String(64) Required

  • Merchant's reference number for tracking the request.
  • Example value: S10000

• orderNo String(32) Required

  • PayBy's unique identification number of the order.
  • Example value: O1000

• product String(200) Required

  • Product name of the API method used in the order.
  • Example value: Transfer Bank Card

• status String Required

  • Status of the order.
  • Possible values: CREATED, SUCCESS, FAILURE, BANK_FAIL

• amount Money Required

  • Amount to be transferred.

• accountHolderType String(16) Required

  • Account holder type: INDIVIDUAL or CORPORATE
  • Example value: INDIVIDUAL

• firstName String(200)

  • SHA256 of original text. Required if accountHolderType is INDIVIDUAL.

• lastName String(200)

  • SHA256 of original text. Required if accountHolderType is INDIVIDUAL.

• middleName String(200)

  • SHA256 of original text.

• companyName String(200)

  • SHA256 of original text. Required if accountHolderType is CORPORATE.

• cardNumber String(64) Required

  • SHA256 of original card number.

• expiryMonth String(2) Required

  • Card expiration month (1–12).
  • Example value: 09

• expiryYear String(4) Required

  • Card expiration year.
  • Example value: 2027

• memo String(128)

  • Transfer description or note.
  • Example value: Bonus

• notifyUrl String(200)

  • URL where the merchant receives notifications.
  • Example value: http://yoursite.com/api/notification

• failDes String(200)

  • Cause of order failure.
  • Example value: -

• bankReference String(128)

  • Bank reference number.

• payerFeeAmount Money Required

  • Fee paid by the payer.
  • Example value:
    {
      "amount": 0,
      "currency": "AED"
    }

• payerFeeMemberId String(32) Required

  • ID of the party paying the fee.
  • Example value: 200000429066

• paidTime Date Required

  • Time of deduction.

• refundedTime Date

  • Time of refund.

Response Sample

HTTP Headers

{
    "sign": "Yv+C2lOQmfERdm5GF9b2V4Y98HmX/6CFyconeOW36AoPqcb7InRcP9E5GnvJLfMoCScuNP4FBdJ5tJpL0A7yPHUMfxARi05jFRSMG97JJazDbWTbRkNM1ZupmTubhUvxvRCgvJp1k0c5yrHph+F+++W5eYho92xnkNgd62BS27i0iDRGzGSmsaPpK7MFcdlvnbbnmDZZJ0LH6RhYiJLYKl+znllQx3jNfCRjV28o22FZ35Q43mZTsS4uAZWbZ/KfaqWoV3sN62Cjj8DSg3mD6GCGWSVbxLq58DUxAq+6GwJ7Gj0Dc9nMXP3gnFW7dodQ9AjL2iHnH6Zh1Pw2D5/ung=="
}

HTTP Body

{
    "body": {
        "transferToBankCard": {
            "amount": {
                "amount": 0.1,
                "currency": "AED"
            },
            "partnerId": "200000429066",
            "notifyUrl": "http://yoursite.com/api/notification",
            "memo": "Bonus",
            "createdTime": 1741917501666,
            "payerFeeAmount": {
                "amount": 0,
                "currency": "AED"
            },
            "payerFeeMemberId": "200000429066",
            "orderNo": "131741917501042130",
            "merchantOrderNo": "7a5b47a4-1824-4a4d-b581-9b0ebd5dd436",
            "product": "Transfer Bank Card",
            "status": "CREATED",
            "paidTime": 1741917502000,
            "accountHolderType": "INDIVIDUAL",
            "cardNumber": "6b59af6dcc4fb841d5f053a852ed917fd5eecad0cc2c3e3507540c065f520a4c",
            "expiryMonth": "08",
            "expiryYear": "2028",
            "firstName": "c6f27629d041725bb227a0d718641d220d69356cd82b3b7230f1d0dff950de5f",
            "lastName": "15d6dacb4fbda825195e5873c175a9b093daa32345c708ac18411365f6fc6038",
            "middleName": "15d6dacb4fbda825195e5873c175a9b093daa32345c708ac18411365f6fc6038"
        }
    },
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "974825"
    }
}

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Request processed successfully	-
400	INVALID_PARAMETER	Invalid request parameters	Review and correct request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too early compared to current time	Adjust request timestamp
400	REQUESTTIME_TOO_LATER	Request time is too late compared to current time	Adjust request timestamp
402	RATE_LIMIT_REJECT	Request frequency exceeds allowed limit	Reduce request frequency
403	UNAUTHORIZED	API access not authorized	Contact PayBy for authorization
404	SERVICE_NOT_AVAILABLE	API service is unavailable	Contact PayBy support
500	SYSTEM_ERROR	Internal system error	Contact PayBy support and retry later
504	SERVICE_TIMEOUT	Service request timeout	Retry the request
601	RISK_FAIL	Risk control validation failed	Review and adjust business parameters
62004	MERCHANT_ORDER_NO_NOT_EXIST	Merchant order number does not exist	Verify and correct merchant order number