Vananam Processor and API

This page describes the Vananam integration for operations and customer-service teams. It explains asynchronous URL fulfilment, the provider calls, the states that control retry, and the records to compare when an order is delayed or fails.

What Vananam does

Vananam is an asynchronous, SKU-per-product processor. The application submits an order, stores the Vananam order id, and retrieves the order until a voucher claim URL is available. The integration is configured for third-party URL delivery; the processor test documentation explicitly notes that code delivery is not supported.

Order lifecycle

1. A partner requests a digital URL gift card for a Vananam brand and denomination.
2. The processor reads the brand's vananam-sku attribute.
3. The application sends POST orders with the product ID, denomination, sale UUID as reference_code, and quantity: 1.
4. The response id becomes the processor reference. A PENDING response leaves the card in the requested state and requires a later retrieval.
5. Retrieval sends GET orders/{id}. A PENDING response is retryable; a DELIVERED response is checked for voucher data.
6. The first voucher's claim_url becomes the card's third-party URL. A non-empty expire_date is converted to the card expiration date.
7. The application completes the card only after the delivered response passes validation. The existing application URL is retained or generated according to the asynchronous sale flow.

Example API order flow

The client uses the configured base URI, HTTP basic authentication, and JSON headers. The values below are illustrative and contain no credentials or live claim URL.

Create an order

POST ${VANANAM_BASE_URI}/orders
Authorization: Basic [REDACTED]
Content-Type: application/json
Accept: application/json

{
  "product_id": "product-sku-example",
  "denomination": 100.00,
  "reference_code": "sale-uuid-example",
  "quantity": 1
}

An accepted order can return a pending response:

{
  "id": 12345,
  "reference_number": "sale-uuid-example",
  "product_id": "product-sku-example",
  "status": "PENDING",
  "amount": 100.00,
  "vouchers": [],
  "message": "Order accepted; vouchers will be available later."
}

Retrieve an order

GET ${VANANAM_BASE_URI}/orders/12345
Authorization: Basic [REDACTED]
Accept: application/json

A completed response has the shape used by the response mapper:

{
  "id": 12345,
  "reference_number": "sale-uuid-example",
  "product_id": "product-sku-example",
  "status": "DELIVERED",
  "vouchers": [
    {
      "card_number": null,
      "pin_code": null,
      "claim_url": "https://[REDACTED]/claim/[REDACTED]",
      "expire_date": "2027-10-01T12:00:00.000Z"
    }
  ],
  "message": "Order successfully placed."
}

Response mapping and validation

The processor first requires a valid JSON response, a non-empty id, and a non-empty status. It stores the id as processor_reference.

The expire_date property must exist even when its value is null. A missing property is a validation failure, not an indication of a card without an expiry date.

Provider states and retry behaviour

The create call is a POST. If a server error occurs after Vananam has accepted the order but before the response is observed, an automatic retry can risk a duplicate order. Check the original sale UUID and interaction audit before any manual re-order.

The configured client throttling defaults to enabled, with 60 requests per 60 seconds. The values come from VANANAM_THROTTLING_ENABLED, VANANAM_THROTTLING_RATE_LIMIT, and VANANAM_THROTTLING_RATE_PERIOD; the application also classifies the provider's exact Too many requests message as retryable.

Audit comparison fields

Vananam uses the shared AuditProcessor record for the sale and enables request/response interaction auditing on the Vananam client. Compare the following evidence in order:

1. The sale UUID, client request ID, brand, denomination, and request version.
2. The create request payload: product_id, denomination, reference_code, and quantity.
3. The create response id, reference_number, and status.
4. Any retrieval request path, especially orders/{id}, and its returned status.
5. For delivery, the presence of vouchers[0].claim_url and expire_date without copying the claim URL into an escalation.
6. The AuditProcessor status: REQUESTED for an accepted or pending order, SUCCESS only after a delivered voucher is mapped, or ERROR for validation/provider failures.
7. The processor interaction audit entries for the ordered request/response sequence. These entries are keyed by the sale UUID and are redacted by the application audit model when a redactor is supplied.

The provider id is the primary Vananam reference. The sale UUID is also sent as reference_code, so the two values should be compared rather than treated as interchangeable.

Settings

Processor settings

The settings are read from config/vananam.php:

The client sends Content-Type: application/json and Accept: application/json on each provider request.

Brand settings

Each enabled brand needs the vananam-sku brand attribute. The value is sent as product_id; it is not derived from the face value. The provider catalogue collector stores product IDs as catalogue product_sku values and exposes URL delivery only.

The collector maps only products whose delivery_type is REALTIME. It maps provider country, category, currency, denominations, discount, redemption type, description, terms, validity, and image data into the cached Vananam catalogue. Fixed denominations use the provider min values; a single range becomes an open-value product.

API operations

VananamCollector is a queued job with one attempt. It keeps the previous cached catalogue when the provider response is invalid, empty, or produces no valid products. No Vananam-specific console command is defined in the inspected application tree.

Customer-service investigation

For a pending or failed order:

1. Confirm the sale UUID, client request ID, brand, currency, denomination, and delivery method.
2. Confirm the brand's vananam-sku value and compare it with product_id in the create request.
3. Find the provider id from the create response or the stored card processor reference. Use that ID for retrieval; do not submit a new order first.
4. Compare the create and retrieve interaction audits. Check the HTTP outcome, response JSON validity, status, and the reference_number/reference_code values.
5. For PENDING, allow the retry path to retrieve the original order. For Too many requests or 5xx, note the repeat code 606060 and avoid parallel manual retries.
6. For DELIVERED, verify that the response contains the first voucher's claim_url and expire_date key. Do not paste a claim URL or any voucher data into a ticket.
7. If the order is marked ERROR, compare the exact validation or provider message with the request/response audit before escalation.

Limitations and support contacts

The Vananam processor does not implement a provider balance lookup or cancellation call. It also does not map card numbers or PIN codes into the returned card; the tested integration is for third-party URL delivery.

Escalations should include the internal sale UUID, client request ID, provider order ID, timestamps, status, and redacted audit evidence. Do not include credentials, claim URLs, card numbers, or PINs.

Related code

• app/Processors/Vananam/VananamProcessor.php — asynchronous request creation, retrieval, response validation, mapping, and retry classification.
• app/Http/Clients/Vananam/VananamApi.php — authenticated HTTP client and provider paths.
• app/Http/Clients/Vananam/Requests/OrderRequestData.php — create-order payload.
• app/Http/Clients/Vananam/Requests/RetrieveOrderRequestData.php — retrieval order ID.
• app/Http/Clients/Vananam/Responses/RawVananamResponseData.php — raw response wrapper.
• app/CatalogueService/Jobs/VananamCollector.php — catalogue retrieval and mapping.
• config/vananam.php — URI, authentication, timeout, and throttling settings.
• database/migrations/2024_05_03_133334_r_c_c-14248-create-vananam-data-issuer-record.php — issuer type and onboarding contacts.
• tests/Unit/Processors/VananamProcessorTest.php — pending, delivered, validation, retry, throttling, and URL-delivery scenarios.
• tests/Unit/App/Http/Clients/Vananam/VananamApiTest.php — client paths, headers, payload, and transport failures.