You Got a Gift Processor and API

This page explains the You Got a Gift integration from an operations and customer-service perspective: how an order moves through the system, which settings control it, and what evidence is useful when investigating a failed or delayed gift-card order.

What You Got a Gift does

You Got a Gift is an asynchronous, SKU-per-product order processor with catalogue support. The application creates a provider order using the configured brand product code, parses the returned voucher payload, and can retrieve the same order again by its provider order ID.

The platform treats the integration as asynchronous, but the current interaction validates voucher data on both create and retrieve responses. A response with only an order ID and no usable url or code is therefore a response-validation failure in the current implementation rather than a normal pending response.

Order lifecycle

1. A partner orders a You Got a Gift-enabled brand.
2. The processor reads the brand's You Got a Gift product/SKU mapping, the requested amount, currency, and the internal sale UUID.
3. The currency selects the provider credentials and is converted to the provider country code: for example, AED maps to AE.
4. The client creates the provider order with the internal transaction reference and notify: 0.
5. The interaction requires order_id and gift_voucher in the response, then extracts the recognised voucher labels: url, code, and pin.
6. The provider order_id becomes the processor reference. The application stores the returned voucher data and marks the sale successful.
7. If retrieval is requested, the client calls the provider with the stored order ID and parses the same response shape again.

The provider's state and ordered amount may be present in the response and are useful for diagnostics, but they are not the success rule used by the processor. A usable voucher value is required by the parser.

Example API order flow

The following examples are illustrative and contain no real credentials or voucher values.

Create order request

The request is sent as JSON to POST /orders/ relative to the configured base URI:

{
  "reference_id": "sale-123e4567-e89b-12d3-a456-426614174000",
  "notify": 0,
  "brand_code": "ABC12",
  "currency": "AED",
  "amount": 65.0,
  "country": "AE"
}

The reference_id is the internal transaction reference, while brand_code is the provider product code configured for the brand. Authentication headers are generated from the currency-specific API key and secret and must not be copied into support tickets.

Create order response

An order that can be completed by the current parser has this general shape:

{
  "reference_id": "sale-123e4567-e89b-12d3-a456-426614174000",
  "order_id": 12345,
  "state": 1,
  "notify": 0,
  "ordered_amount": {
    "currency": "AED",
    "amount": 65
  },
  "barcode": "https://[redacted]/barcode",
  "gift_voucher": [
    {
      "label": "code",
      "value": "1234567890"
    },
    {
      "label": "pin",
      "value": "0987 654 321"
    }
  ],
  "expiry_date": "2026-08-02"
}

The provider may return a URL instead of a code:

{
  "order_id": 12345,
  "gift_voucher": [
    {
      "label": "url",
      "value": "https://[redacted]/voucher/[redacted]"
    }
  ],
  "expiry_date": "2026-08-02"
}

Retrieve order request and response

Retrieval uses the provider order ID stored as the processor reference:

GET /orders/12345/

The retrieval request has no JSON body. The currency is used to select the correct provider credentials and is included in the internal request data, while the provider order ID is carried in the URL. The response uses the same order_id and gift_voucher structure as the create response.

Response mapping and validation

The interaction maps provider fields to the internal card as follows:

For codes containing spaces, the stored code remains the provider value, while the generated barcode string encodes spaces as %20. If a response contains a URL and a PIN but no code, the order remains usable through the URL and an error is logged because the combination is unusual.

The following conditions are validation failures:

• order_id is missing or empty.
• gift_voucher is missing or empty.
• A voucher entry has no label or value.
• No recognised url or code is returned.

Audit comparison fields

Compare create and retrieve interaction audits as a sequence. The application request and response timestamps come from the processor interaction audit; the provider does not supply equivalent application timing fields in the documented request data.

A redacted comparison record can be represented as follows:

{
  "create": {
    "operation": "POST /orders/",
    "requestTimestamp": "2026-08-17T17:16:04Z",
    "responseTimestamp": "2026-08-17T17:16:05Z",
    "saleId": "sale-123e4567-e89b-12d3-a456-426614174000",
    "referenceId": "sale-123e4567-e89b-12d3-a456-426614174000",
    "brandCode": "ABC12",
    "currency": "AED",
    "country": "AE",
    "amount": 65.0,
    "orderId": "12345",
    "cardDataPresent": true
  },
  "retrieve": {
    "operation": "GET /orders/12345/",
    "requestTimestamp": "2026-08-17T17:18:22Z",
    "responseTimestamp": "2026-08-17T17:18:23Z",
    "saleId": "sale-123e4567-e89b-12d3-a456-426614174000",
    "processorReference": "12345",
    "orderId": "12345",
    "cardDataPresent": true
  }
}

Settings

Processor settings

The processor-level settings are environment-backed values in config/you-got-a-gift.php:

The client creates an HMAC-SHA256 Signature authorization header from the selected currency's API secret and sends the API key in both the signature key ID and x-api-key header. Do not log or include the API key, secret, or generated authorization header in support evidence.

Currency credentials and country mapping

Credentials are selected from the order currency. The supported currencies and derived provider country codes are:

Both credentials must be present for the order currency. An unsupported currency fails before the provider request because no currency-to-country mapping exists.

Brand settings

Each enabled brand must have the You Got a Gift product/SKU mapping used by the brand_code field. The mapping is stored in the brand attributes using the issuer's standard SKU attribute format; it is not taken from the order amount at runtime for this processor. A wrong, missing, or stale mapping can create an order for the wrong provider product or cause the provider to reject the request.

Catalogue imports provide the provider's brand_code, accepted currency, and denomination information. Confirm that the imported product is associated with the intended brand and currency before enabling sales.

API operations and rate limits

The catalogue endpoint uses the AED credential set by default. Production limits are two calls per day to the catalogue endpoint, and each page may be called twice per day. Avoid repeated manual catalogue requests while investigating an individual sale.

Failure and retry behaviour

The client maps provider failures into interaction exceptions. The platform retries transient failures but does not retry configuration, authentication, or duplicate-order failures automatically:

For a duplicate create response or 409, do not submit another create request immediately. Check the create audit and use the existing provider order reference for retrieval or escalation.

Customer-service investigation

For a failed or delayed order, collect the following before re-ordering:

1. Internal sale UUID and transaction reference.
2. Brand slug, requested amount, delivery method, and currency.
3. The configured brand product/SKU mapping and expected brand_code.
4. The create-order audit, including request and response timestamps, endpoint, redacted request fields, HTTP result, order_id, and voucher labels.
5. Any retrieve-order audits and the processor reference used in the path.
6. The currency-specific credential configuration status, without exposing secrets.

Use the first provider operation to classify the problem:

• If POST /orders/ succeeded and returned an order_id, retrieve that order rather than creating another one.
• If create returned an order ID but no usable voucher, treat it as a response-validation or provider-completion issue; do not assume the order is safe to repeat.
• If only GET /orders/{order_id}/ appears, verify that the processor reference came from the original create flow and that the retrieval belongs to the same sale.
• If no provider audit exists, investigate processor selection, currency support, brand SKU resolution, and request dispatch before contacting the provider.
• If the provider rejected the create request, compare brand_code, currency, country, and amount with the sale and catalogue record.

Limitations and escalation evidence

You Got a Gift balance checks and cancellations are not implemented by this processor. Escalations should include the internal sale identifier, provider order ID if available, currency, timestamps, operation and endpoint, HTTP status or mapped exception, and redacted response structure. Never include API secrets, authorization headers, or unredacted voucher codes and PINs in a ticket.

Related code

• app/Processors/YouGotAGift/YouGotAGiftProcessor.php — asynchronous processor wrapper.
• app/Processors/Interaction/Integrations/YouGotAGift/YouGotAGiftProcessorInteraction.php — create/retrieve request construction, response parsing, and exception classification.
• app/Http/Clients/YouGotAGift/YouGotAGiftApi.php — provider transport, authentication headers, endpoint paths, and HTTP error mapping.
• app/Http/Clients/YouGotAGift/Requests/CreateOrderRequestData.php — create request payload.
• app/Http/Clients/YouGotAGift/Requests/RetrieveOrderRequestData.php — retrieve request data.
• app/CatalogueService/Jobs/YouGotAGiftPageCollector.php — provider catalogue import and validation.
• config/you-got-a-gift.php — processor environment settings.
• tests/Unit/Processors/Interaction/Integrations/YouGotAGift/YouGotAGiftProcessorInteractionTest.php — request mapping, voucher parsing, validation, and retry scenarios.