• English
  • Order Query

    Supported Markets: NG Nigeria | ZA South Africa

    /api/v2/payment/merchant/order/queryStatus

    Request Parameters

    ParameterTypeLengthNGZADescription
    orderIdstring32NoNoMerchant's unique order ID. At least one of orderId or orderNo is required.
    orderNostring32NoNoPalmPay platform order number. At least one of orderId or orderNo is required.
    nonceStrstring—Yes—Random string
    requestTimeinteger—Yes—Unix timestamp in seconds
    versionstring—Yes—V1.1

    Yes = Required | No = Optional | — = Not applicable for this market |

    Response Fields

    FieldTypeNGZADescription
    orderIdstringYesYesMerchant's unique order ID
    orderNostringYesYesPalmPay platform order number
    merchantIdstringYesYesMerchant ID
    amountlongYesYesTransaction amount (in cents / minor units)
    currencystringYesYesCurrency code
    orderStatusintegerYesYesOrder status (see Order Status)
    productTypestringNoYesProduct type
    remarkstringNo—Remark / note
    errorMsgstringNo—Error message
    FieldTypeNGZADescription
    payMethodstring—YesPayment method
    createdTimelong—YesCreation time (Unix timestamp in milliseconds)
    completedTimelong—YesCompletion time (Unix timestamp in milliseconds)
    payerobject—NoPayer information (returned for auth orders)
    payer.accountNamestring—NoCardholder name
    captureInfoarray—NoList of associated capture orders (returned for auth orders)
    captureInfo[].orderNostring—NoCapture order's platform order number
    captureInfo[].amountlong—NoCapture amount (in cents / minor units)
    cardBrandstring—NoCard brand (returned for instant payment original orders / capture orders; not returned for auth orders)
    bankNamestring—NoIssuing bank. Same return rules as cardBrand.
    cardLast4string—NoLast 4 digits of the card number. Same return rules as cardBrand.
    cardCountrystring—NoIssuing country. Same return rules as cardBrand.
    ecistring—No3DS ECI value. Same return rules as cardBrand.
    cardTokenstring—NoCard token (returned when rememberCard=true)

    Yes = Always returned | No = Conditionally returned | — = Not returned

    ZA Pre-auth Scenario Note: When querying an auth order (the original order created with captureMode=manual), cardBrand / cardLast4 / cardCountry / eci are not returned. To obtain card information, locate the capture order number via captureInfo, then query the capture order separately.

    Examples

    NG · POST

    curl 'https://open-gw-sandbox.palmpay-inc.com/api/v2/payment/merchant/order/queryStatus' \
      -H 'CountryCode: NG' -H 'Authorization: Bearer xxx' -H 'Content-Type: application/json' \
      -d '{"requestTime":1662171389940,"version":"V1.1","nonceStr":"xxx",
           "orderId":"1558616686273","orderNo":"242019052313044587518762420"}'
    {
      "respCode": "00000000",
      "respMsg": "success",
      "data": {
        "orderId": "1558616686273",
        "orderNo": "242019052313044587518762420",
        "merchantId": "CH1913953825",
        "currency": "NGN",
        "amount": 900000,
        "orderStatus": 2,
        "remark": "test",
        "errorMsg": "message"
      }
    }

    ZA · Query Capture Order (with card info)

    Applicable to: instant payment original orders / captured child orders.

    curl 'https://open-gw-daily.palmpay-inc.com/api/v2/payment/merchant/queryorder?orderNo=24260610123227106892' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx'
    {
      "respCode": "00000000",
      "respMsg": "success",
      "data": {
        "country": "ZA",
        "amount": 130400,
        "orderNo": "24260907071635802373",
        "orderId": "1788765395809",
        "cardCountry": "ZA",
        "completedTime": 1788765470765,
        "orderExpireMilliSec": 0,
        "cardType": "debit_card",
        "orderStatus": 2,
        "eci": "05",
        "bankName": "Wema Bank",
        "payerAccountType": 12,
        "transType": "24",
        "merchantId": "125010905579101",
        "payMethod": "bank_card",
        "createdTime": 1788765395809,
       "currency": "ZAR",
       "cardBrand": "VISA",
        "cardLast4": "0036",
        "productType": "bank_card"
      }
    }

    ZA · Query Auth Order (with captureInfo, no card info)

    Applicable to: original auth orders created with captureMode=manual. Card information is not returned; use captureInfo to locate the capture order number, then query that capture order for card details.

    curl 'https://open-gw-daily.palmpay-inc.com/api/v2/payment/merchant/queryorder?orderNo=24260610012259245300' \
      -H 'CountryCode: ZA' -H 'Authorization: Bearer xxx'
    {
      "respCode": "00000000",
      "respMsg": "success",
      "data": {
        "country": "ZA",
        "amount": 1000,
        "orderNo": "2426070123334445566",
        "capturedAmount": 1000,
        "orderId": "17123341123444",
        "captureInfo": [
          {
            "orderNo": "24260701233311244",
            "amount": 1000
          }
        ],
        "cardCountry": "ZA",
        "completedTime": 1782894853528,
        "orderExpireMilliSec": -30921,
        "cardType": "debit_card",
        "orderStatus": 2,
        "bankName": "CAPITEC BANK LIMITED",
        "payer": {
          "accountName": "palmer"
        },
        "payerAccountType": 12,
        "transType": "24",
        "merchantId": "124012503542121",
        "payMethod": "bank_card",
        "appId": "L112233445566778899",
        "createdTime": 1782894198074,
        "currency": "ZAR",
        "cardBrand": "MasterCard",
        "cardLast4": "1234",
        "cardToken": "sdarqwfasasqwf!sfadssd",
        "productType": "bank_card"
      }
    }

    ZA Query Logic Summary

    queryorder(orderNo)
        │
        ├─ orderStatus = 2 AND captureMode = immediate
        │     → Directly returns cardBrand / cardLast4 / cardCountry / eci
        │
        ├─ orderStatus = 5 (required_capture) OR orderStatus = 2 AND captureMode = manual
        │     → Returns captureInfo[] + payer, does NOT return card info
        │     → Use captureInfo[].orderNo to call queryorder again
        │           → Returns cardBrand / cardLast4 / cardCountry / eci
        │
        └─ captureInfo[].orderNo → the corresponding capture order
              → Returns cardBrand / cardLast4 / cardCountry / eci