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

# Purchase Gift Card

> Buy a digital gift card — cost debited from your USD wallet

Purchase a gift card product. The face value is debited from your USD wallet.

```
POST https://api.yativo.com/api/v1/giftcards
```

<Note>
  Requires `Idempotency-Key` header. Gift card purchases are **non-refundable**.
</Note>

<ParamField body="productId" type="integer" required>
  The gift card product ID (from `GET /giftcards`).
</ParamField>

<ParamField body="unitPrice" type="number" required>
  Price per unit in the product's native currency (minimum 0.01).
</ParamField>

<ParamField body="quantity" type="integer" required>
  Number of cards to purchase (minimum 1).
</ParamField>

<ParamField body="senderName" type="string" required>
  Name of the sender. Maximum 100 characters.
</ParamField>

<ParamField body="recipientEmail" type="string" required>
  Email address of the gift card recipient.
</ParamField>

<ParamField body="customer_id" type="string">
  Optional. Link this purchase to a customer in your account.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/giftcards' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: gc-amazon-001' \
    -d '{
      "productId": 1234,
      "unitPrice": 10.00,
      "quantity": 1,
      "senderName": "John Doe",
      "recipientEmail": "recipient@example.com",
      "customer_id": "cust_abc123"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Giftcard request submitted successfully",
    "data": {
      "transaction_id": "gc-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "product_name": "Amazon US",
      "amount": 10.00,
      "currency": "USD",
      "status": "completed",
      "created_at": "2026-06-01T10:00:00.000000Z"
    }
  }
  ```

  ```json Insufficient balance theme={null}
  {
    "status": "error",
    "status_code": 402,
    "message": "Insufficient wallet balance"
  }
  ```
</ResponseExample>