> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laikipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify & Retrieve Gift Card Order

> Verify fulfillment status and securely retrieve voucher code, PIN, and redemption instructions by reference

## Overview

The `/gift-cards/verify/{reference}` endpoint queries the fulfillment state of a gift card order using its unique client or transaction reference.

If an order was initially in `"PROCESSING"` state, calling this endpoint triggers automated Transaction Status Query (TSQ) reconciliation with the upstream issuance network and returns the unlocked `voucherCode` and `voucherPin`.

***

## Real-World Use Cases

<CardGroup cols={2}>
  <Card title="Order Status Polling" icon="rotate">
    Poll this endpoint if your client connection dropped during the initial `POST /gift-cards/purchase` call to recover the voucher code without double-charging.
  </Card>

  <Card title="Voucher Retrieval on User Request" icon="key">
    Allow users to revisit their order history page inside your mobile app to re-copy their voucher PIN and view redemption instructions.
  </Card>
</CardGroup>

***

## Path Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `reference` | `string` | **Yes** | Client order reference (e.g. `GC_ORD_89102`) or internal transaction reference. |

***

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.laikipay.com/v1/merchant/gift-cards/verify/GC_ORD_89102" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  import axios from 'axios';

  async function verifyGiftCardOrder(accessToken, reference) {
    const response = await axios.get(
      `https://api.laikipay.com/v1/merchant/gift-cards/verify/${reference}`,
      {
        headers: { Authorization: `Bearer ${accessToken}` },
      }
    );

    const { isSuccessful, voucher } = response.data;
    console.log(`Order Status: ${isSuccessful ? 'SUCCESS' : 'PENDING'}`);
    console.log(`Voucher: ${voucher?.code} (PIN: ${voucher?.pin})`);
    return response.data;
  }
  ```

  ```python Python theme={null}
  import requests

  def verify_gift_card(access_token, reference):
      url = f"https://api.laikipay.com/v1/merchant/gift-cards/verify/{reference}"
      headers = {"Authorization": f"Bearer {access_token}"}
      
      response = requests.get(url, headers=headers)
      response.raise_for_status()
      order = response.json()
      print(f"Status: {order['orderStatus']} | Voucher: {order.get('voucher', {}).get('code')}")
      return order
  ```
</CodeGroup>

***

## Response Structure

### Success Response (`200 OK`)

```json theme={null}
{
  "status": "success",
  "reference": "GC_ORD_89102",
  "transactionId": "gco_78a10b9c",
  "productCode": "LAI-AMZN-USA-001",
  "productName": "Amazon US",
  "currency": "USD",
  "faceValue": 25.0,
  "costNgn": 41615.0,
  "voucher": {
    "code": "AQ48-921829-LP902",
    "pin": "4819",
    "serialNumber": "SN-829102-AMZ",
    "instructions": "Redeem online at amazon.com/redeem"
  },
  "recipient": {
    "email": "david.adeleke@example.com",
    "name": "David Adeleke"
  },
  "orderStatus": "SUCCESS",
  "isSuccessful": true,
  "environment": "TEST",
  "createdAt": "2026-10-14T12:00:00.000Z"
}
```

***

## Error Handling

<AccordionGroup>
  <Accordion title="404 Not Found — Order Not Found">
    ```json theme={null}
    {
      "statusCode": 404,
      "message": "Gift card order 'GC_ORD_invalid' not found",
      "error": "Not Found"
    }
    ```
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml openapi.json GET /gift-cards/verify/{reference}
openapi: 3.0.3
info:
  title: LaikiPay Developer API
  description: >-
    Developer-first financial infrastructure for virtual card issuance,
    corporate vaults, and payment automation.
  version: 1.0.0
servers:
  - url: https://api.laikipay.com/v1/merchant
    description: Base url
security:
  - bearerAuth: []
paths:
  /gift-cards/verify/{reference}:
    get:
      tags:
        - Gift Cards
      summary: Verify & Retrieve Gift Card Order
      description: >-
        Verify fulfillment status and securely retrieve voucher code, PIN, and
        redemption instructions by reference.
      parameters:
        - name: reference
          in: path
          required: true
          schema:
            type: string
          example: GC_ORD_89102
      responses:
        '200':
          description: Gift card order details, verification status, and voucher PIN
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT Access Token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.