VoucherHub Mobile API Assessment

VoucherHub is a recruitment assessment API for building a mobile voucher-shopping app. This guide focuses on the context, expected user journey, integration approach, and the things that will help you build a good mobile client without relying on hard-coded assumptions.

Use the OpenAPI documentation for exact endpoints, request bodies, response schemas, and status codes:

{baseUrl}/swagger

What This API Is About

VoucherHub lets an authenticated user browse Suregifts voucher products, add selected voucher amounts to a cart, perform a simulated checkout, and view purchased vouchers afterward.

The API is intentionally shaped like a small production integration rather than a static mock. Product data comes from Suregifts through the backend, voucher amounts are validated server-side, checkout can return different purchase states, and voucher fields may vary depending on what the provider returns.

Your mobile app should treat the API as the source of truth.

Assessment Goal

Build a mobile application that consumes the VoucherHub API and gives the user a complete voucher purchase experience.

The expected app should include:

Login.
Product catalog.
Product detail or amount selection.
Cart management.
Cart total review.
Checkout.
Checkout result handling.
Voucher history.
Voucher detail.

The exact UI is up to you, but the app should feel like a real user can complete the journey without developer guidance.

Base URL

Hosted assessment environment:

https://assessment.suregifts.com.ng

Swagger:

{baseUrl}/swagger

Test Login

Use the seeded test account:

Email: [email protected]
Password: Password1@

After login, store the returned access token and send it as a bearer token on protected API calls.

Authorization: Bearer {accessToken}

There is no refresh-token flow in this assessment. If the token expires or the API returns unauthorized, send the user back to login.

Recommended User Journey

The cleanest app flow is:

User logs in.
App loads the product catalog.
User opens a product and chooses a valid amount.
User chooses quantity.
App adds the item to cart.
User reviews cart.
App calculates the total before checkout.
User checks out.
App shows the checkout status.
User can view voucher history and voucher details.

This flow is more important than the exact screen count. For example, product selection and amount selection can be on the same screen if the experience is clear.

Product Handling

Do not hard-code product names, images, categories, voucher values, or merchant information. Load them from the API.

Products may include:

Display name.
Image.
Description.
Currency.
Fixed denominations.
Minimum and maximum values.
Redemption details.
Countries, stores, and categories.
Validity information.

Use these fields to make the catalog useful. A strong implementation should help the user understand what they are buying before it goes into the cart.

Amount Selection Rules

The product data tells the app how amounts should be selected.

If a product has denominations, show those values as fixed choices. The user should not type an arbitrary amount for that product.

If a product does not have denominations, allow the user to enter an amount within the product's minimum and maximum value.

Even when the app validates amount selection, still expect the API to reject invalid values. Server validation is the final authority.

Cart Behavior

The cart belongs to the authenticated user. The API creates or returns the user's current cart.

The app should support:

Viewing cart items.
Updating quantity.
Changing selected amount where the product allows it.
Removing items.
Showing subtotal and total.
Handling an empty cart gracefully.

If the same product and amount are added more than once, the API may merge the cart lines by increasing quantity. Your UI should render the cart returned by the API instead of assuming the local cart state is still correct.

Checkout Behavior

Checkout uses a simulated payment flow and then attempts to purchase vouchers through Suregifts.

Your app should not assume checkout always succeeds immediately. It should handle these possible states:

Pending.
Payment successful.
Purchase processing.
Purchase successful.
Purchase failed.

If checkout succeeds, vouchers may be returned immediately. If purchase is still processing, show a clear processing state and let the user return to voucher history later.

If checkout fails, display the failure reason when the API provides one.

Voucher History

Voucher history represents vouchers returned by Suregifts and saved by VoucherHub.

Voucher details may include:

Voucher code.
PIN.
Serial number.
Expiry date.
Product name.
Amount.
Provider order identifier.
Provider voucher identifier.

Some of these fields can be missing. Build the UI so missing optional fields do not break the screen. For example, a product may not require a PIN, or Suregifts may not return the voucher code immediately.

For voucher details, prioritize readability and copyability. Users should be able to read or copy voucher code, PIN, and serial number easily.

Error Handling Expectations

The app should handle API errors as part of the normal user experience.

At minimum, handle:

Invalid login credentials.
Missing or expired token.
Product loading failure.
Invalid amount.
Invalid quantity.
Empty cart checkout.
Checkout failure.
Network failure.
Slow loading states.

Avoid showing raw technical errors when a user-friendly message is possible. If the API provides a clear message, use it.

State Management Guidance

Keep server state and local state separate.

Good rules:

Treat the login token as session state.
Treat product list data as refreshable remote data.
Treat the cart returned by the API as the source of truth.
Refetch or update cart state after add, update, or delete operations.
Do not assume checkout created vouchers until the API response or voucher history confirms it.

For mobile apps, also consider what happens when the user backgrounds the app, returns later, or loses network connectivity during a request.

UX Expectations

The assessment is not only about calling endpoints. The app should show that you can turn an API into a usable mobile experience.

Expected UX quality:

Clear loading indicators.
Empty states for products, cart, and voucher history.
Useful error states with retry actions where appropriate.
Responsive layout on typical mobile screen sizes.
Currency values formatted clearly.
Product images displayed when available.
Disabled checkout when the cart is empty.
Confirmation or clear feedback after cart and checkout actions.
Voucher details presented securely and clearly.

What Not To Do

Avoid these common shortcuts:

Do not hard-code product data.
Do not bypass login by hard-coding a token.
Do not ignore server validation errors.
Do not assume all vouchers have a PIN.
Do not assume checkout always returns vouchers immediately.
Do not keep using stale cart data after a cart mutation.
Do not build only a Swagger client screen; build an actual mobile user journey.

Suggested Test Cases

Before submitting, test these scenarios:

Successful login.
Failed login.
Product list loads.
Product detail opens.
Fixed denomination product can be added to cart.
Invalid amount is rejected or prevented.
Quantity can be updated.
Cart item can be removed.
Empty cart is handled.
Checkout with items returns a clear status.
Voucher history loads.
Voucher detail handles missing optional values.
API/network failure does not crash the app.

Suregifts Context

VoucherHub integrates with Suregifts behind the scenes. The mobile app should consume VoucherHub only, not Suregifts directly.

The backend handles:

Suregifts authentication.
Product retrieval.
Product amount validation.
Order submission.
Voucher persistence.
Mapping Suregifts responses into mobile-friendly API responses.

For this assessment, product queries are scoped to Nigeria and amounts are handled in NGN.