API Response Contracts

This document provides a complete reference for integrating with the SureGifts API, including how to interpret responses, handle business logic, and process transactions.

---

Understanding Response Codes vs. Business Status Codes

In the SureGifts API, the HTTP response code and the business status code serve different purposes.

HTTP Response Code:

• Indicates only the transport-level outcome — whether the request reached the SureGifts API and was processed at the protocol level.
• If the request is successfully received and parsed by the API, the HTTP status will always be 200.
• Non-200 codes (such as 403 or 500) mean the request was rejected before reaching business logic (e.g., invalid authentication, server error).

Business Status Code (statusCode field):

• Found inside the JSON response body.
• Represents the actual result of the requested operation according to SureGifts business rules.
• Determines whether the action succeeded, failed, or requires specific handling.
• Must always be checked, even when HTTP is 200.

Aboutdata:

• The data field contains the actual response payload for the request.
• Its structure is endpoint-specific and may vary depending on the operation and the result.
• It can be an object, array, string, number, or null.
• Do not assume a fixed schema across all endpoints — validate only the fields relevant to the specific request you made.

---

Business Status Codes (statusCode field)

Code	Message	Description / Action
00	Ok	Request processed successfully.
10	Invalid Request	Check request parameters and formatting.
20	Store Can't Be Determined	Provide a valid store code.
30	Insufficient Balance	Top up account before retrying.
40	Duplicate Transaction Reference	Use a unique transactionReference for each request.
50	Invalid Voucher	Check voucher code validity before retrying.
60	Voucher Not Found	Ensure voucher exists in system.
70	Voucher Already Active	Cannot re-activate an already active voucher.
99	Transaction Not Found	No transaction matches the provided transaction ID.

---

Transaction Types

Represents the type of transaction being performed.

Code	Description
ACTIVATION	Activating a voucher.
REDEMPTION	Redeeming a voucher.

---

Sample Successful Response

JSON

{
    "data": {
        "voucherCode": "112*** ***862",
        "serialNumber": "300002137",
        "transactionId": "96",
        "transactionType": "ACTIVATION",
        "amount": 5000.00,
        "timestamp": "2025-02-10T03:31:18.6436925Z",
        "reference": "123451"
    },
    "statusCode": "00",
    "message": "Successful"
}

Notes:

• HTTP status is 200 because the request reached and was processed by the endpoint.
• statusCode value (00) confirms the business success.
• data contains the actual operation result, which varies by request type.

---

Key Points for Developers

1. Always check statusCode for the real business outcome.
2. Treat data as operation-specific — its fields will vary.
3. Use unique reference values for idempotency.
4. Never log or display full voucher codes.
5. Retry only for network/transport errors or specific recoverable business codes.