Skip to main content

Query Refund Order Page

Interface URL​

Request Parameters​

HTTP Header​

Variable Desc.Variable nameRequiredTypeExample valueDescription
LanguageContent-LanguageOptionalString(10)enLanguage preference: en - English (default)
SignaturesignRequiredStringIXJI/QicPQotIsID...Request signature for authentication
Merchant IDPartner-IdRequiredString(12)200000000888Unique merchant identifier assigned by PayBy

HTTP Body​

Variable Desc.Variable nameRequiredTypeExample valueDescription
Request timerequestTimeRequiredTimeStamp(3)1581404947666Unix timestamp in milliseconds
Business contentbizContentRequiredQueryRefundOrderPageSgsRequest-Contains the main query parameters

QueryRefundOrderPageSgsRequest

Variable Desc.Variable nameRequiredTypeExample valueDescription
Start DatestartDateRequiredString(10)2022-07-22Query start date in YYYY-MM-DD format
End DateendDateRequiredString(10)2022-07-22Query end date in YYYY-MM-DD format
Device ID ListdeviceIdListOptionalList(String)[]Filter by specific device IDs (empty for all devices)
Include Status ListincludeStatusListOptionalList(String)CREATED,REFUNDED_SETTLED,SUCCESS,FAILUREFilter by refund order status (empty for all statuses)
Sort Page ParameterssortPageParamRequiredSortPageParam-Pagination and sorting configuration

SortPageParam

Variable Desc.Variable nameRequiredTypeExample valueDescription
Page NumbernumberOptionalInt0Page number starting from 0 (default: 0)
Page SizesizeRequiredInt20Number of records per page

Request Sample​

// HTTP Header
{
    "Content-Language": "en",                    // Language preference
    "Content-Type": "application/json",          // Request content type
    "sign": "IXJI/QicPQotIsIDBcSGIg6jtJUXs1rTuifQFZUNd3KDTl25GKmpYO7OrkaKkTV0shDRitLmkxJCe3Z60zHE2ZSeVczrhwrnmuMG+bX9N22Hw821H6MydsXetYHRnyf5dPbgpmVja582w49grA6jRlVFAVMYdxKJDPSCb2X/IpltvyrLQ1Wt+lqr+fnpYXvyON6/PIZIQIknC8BVddVahxJnaC6HEagvJf6gskz22/DFfPHT1mlMA9pg8qrbh4O7DYZahf8TB3nIzAPc/FHOUZkYYTT2c8m4eLL8740nJVK7D3IOSqSnBAU/iJ2omjPPFvRCCSqzz17pkGsT7AW91w==",  // Request signature
    "Partner-Id": "200000000888"                // Merchant ID
}

// HTTP Body
{
    "requestTime": 1581404947666,               // Request timestamp in milliseconds
    "bizContent": {
        "startDate":"2022-07-22",               // Query from this date (YYYY-MM-DD format)
        "endDate":"2022-07-22",                 // Query to this date (YYYY-MM-DD format)
        "deviceIdList": [],                     // Empty array means all devices
        "includeStatusList":[],                 // Empty array means all refund statuses
        "sortPageParam": {
            "number": 0,                        // First page (starts from 0)
            "size": 20                          // 20 records per page
        }
    }
}

Response Parameters​

The body in the HTTP Body are returned only when applyStatus is SUCCESS and code = 0.

HTTP Body

Variable Desc.Variable nameRequiredTypeExample valueDescription
Response headheadRequiredResponseHeader-Response status and metadata
Response bodybodyOptionalPagination(RefundOrderListResult)-Paginated refund order data

Pagination

Variable Desc.Variable nameRequiredTypeExample valueDescription
Total ElementstotalElementsRequiredInt8Total number of records found
Total PagestotalPagesRequiredInt1Total number of pages available
ItemsitemsRequiredList(RefundOrderListResult)-Array of refund order records

RefundOrderListResult

Variable Desc.Variable nameRequiredTypeExample valueDescription
Refund Merchant Order NorefundMerchantOrderNoRequiredStringe80b6813-1711-4647-aa0d-48b0d1855ae7Merchant's unique refund order identifier
Order NoorderNoRequiredString911588343112002067PayBy system order number
StatusstatusRequiredStringSUCCESSRefund order status (CREATED/REFUNDED_SETTLED/SUCCESS/FAILURE)
AmountamountRequiredMoney-Refund order total amount with currency
Notify URLnotifyUrlOptionalStringhttps://www.giggles.comCallback URL for refund order notifications
ReasonreasonOptionalString111Refund reason provided by merchant
ReservedreservedOptionalStringaaaaReserved field for future use
Fee RefundedfeeRefundedRequiredMoney-The amount of refunded fee
Device IDdeviceIdOptionalString111Payment device identifier

Response Sample​

// HTTP Body
{
    "body": {
        "totalElements": 8,                     // Total number of refund records found
        "totalPages": 1,                        // Total pages available for pagination
        "sortPageParam": {
            "number": 0,                        // Current page number
            "size": 20                          // Page size
        },
        "items": [
            {
                "refundMerchantOrderNo": "e80b6813-1711-4647-aa0d-48b0d1855ae7", // Merchant refund order ID
                "orderNo": "911588343112002067",                                  // PayBy order number
                "status": "SUCCESS",                                              // Refund completed successfully
                "amount": {
                    "amount": 0.01,                                               // Refund amount
                    "currency": "AED"                                             // Currency code
                },
                "notifyUrl": "https://www.baidu.com",                             // Notification callback URL
                "reason": "111",                                                  // Refund reason
                "reserved": "aaaa",                                               // Reserved field
                "feeRefunded": {
                    "amount": 2.0,                                                // Fee refunded amount
                    "currency": "AED"                                             // Fee currency
                },
                "deviceId": "111"                                                 // Device identifier
            },
            {
                "refundMerchantOrderNo": "b7f48ccd-fe19-4982-bd25-47c00c48e582", // Another successful refund
                "orderNo": "911588340433001500",
                "status": "SUCCESS",                                              // Refund successful
                "amount": {
                    "amount": 0.01,                                               // Small refund amount
                    "currency": "AED"
                },
                "feeRefunded": {
                    "amount": 0.0,                                                // No fee refunded
                    "currency": "AED"
                }
            },
            {
                "refundMerchantOrderNo": "6aa56830-8d4c-4a27-99a3-a7ac737dc446", // Third successful refund
                "orderNo": "911588340592001696",
                "status": "SUCCESS",
                "amount": {
                    "amount": 0.01,
                    "currency": "AED"
                },
                "feeRefunded": {
                    "amount": 0.0,
                    "currency": "AED"
                }
            },
            {
                "refundMerchantOrderNo": "8d549b08-1d57-4761-b0a8-1475ea7ef3a8", // Fourth successful refund
                "orderNo": "911588340324001456",
                "status": "SUCCESS",
                "amount": {
                    "amount": 0.01,
                    "currency": "AED"
                },
                "feeRefunded": {
                    "amount": 0.0,
                    "currency": "AED"
                }
            },
            {
                "refundMerchantOrderNo": "5dda518d-9801-4ee6-2985-af117b3c4d52", // Failed refund example
                "orderNo": "191588328390002304",
                "status": "FAILURE",                                              // Refund failed
                "amount": {
                    "amount": 90.0,                                               // Larger refund amount
                    "currency": "AED"
                },
                "notifyUrl": "http://www.yoursite.com",                           // Merchant notification URL
                "feeRefunded": {
                    "amount": 0.0,                                                // No fee refunded for failed refund
                    "currency": "AED"
                }
            },
            {
                "refundMerchantOrderNo": "5dda518d-8500-4ee6-2985-af117b3c4d52", // Another failed refund
                "orderNo": "191588327382002089",
                "status": "FAILURE",
                "amount": {
                    "amount": 90.0,
                    "currency": "AED"
                },
                "notifyUrl": "http://www.yoursite.com",
                "feeRefunded": {
                    "amount": 0.0,
                    "currency": "AED"
                }
            },
            {
                "refundMerchantOrderNo": "5dda518d-8500-4ee6-1985-af117b3c4d52", // Third failed refund
                "orderNo": "191588327146001910",
                "status": "FAILURE",
                "amount": {
                    "amount": 99.99,                                              // High value failed refund
                    "currency": "AED"
                },
                "notifyUrl": "http://www.yoursite.com",
                "feeRefunded": {
                    "amount": 0.0,
                    "currency": "AED"
                }
            },
            {
                "refundMerchantOrderNo": "5dda515d-8900-4ee6-9385-af117b3c4d52", // Created but not processed
                "orderNo": "191588326189001889",
                "status": "CREATED",                                              // Refund created but not processed yet
                "amount": {
                    "amount": 99.99,
                    "currency": "AED"
                },
                "notifyUrl": "http://127.0.0.1/wc-api/payby_refund_notify",       // Local callback URL
                "feeRefunded": {
                    "amount": 0.0,                                                // No fee refunded yet
                    "currency": "AED"
                }
            }
        ]
    },
    "head": {
        "applyStatus": "SUCCESS",               // Application processed successfully
        "code": "0",                            // Success code
        "msg": "SUCCESS",                       // Success message
        "traceCode": "000000"                   // Trace code for debugging
    }
}

Return Code​

CodeMessageCauseWorkaround
0SUCCESSRequest processed successfully—
400INVALID_PARAMETERParameter errorAdjust the request parameters
402RATE_LIMIT_REJECTRequests are too frequentReduce request frequency
403UNAUTHORIZEDAPI is not authorizedContact PayBy
404SERVICE_NOT_AVAILABLEAPI service is unavailableContact PayBy
500SYSTEM_ERRORInternal system errorContact PayBy and try again later
504SERVICE_TIMEOUTService timeoutTry again later
601RISK_FAILRisk control verification failedAdjust the business logic
71002REQUESTTIME_TOO_EARLYRequest time is more than 15 minutes earlier than current timeAdjust the request time
71003REQUESTTIME_TOO_LATERRequest time is more than 15 minutes later than current timeAdjust the request time