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

# Transaction History

> Get partner's transaction history

Get the authenticated partner's transaction history and current balance. Partner routes use HMAC headers, so this page provides a copyable request instead of the interactive playground.

## Authentication

<ParamField header="X-API-Key-ID" type="string" required>
  API key ID issued for the partner integration
</ParamField>

<ParamField header="X-Partner-ID" type="string" required>
  Partner identifier such as `VULT`
</ParamField>

<ParamField header="X-Timestamp" type="string" required>
  RFC3339 timestamp used when generating the signature
</ParamField>

<ParamField header="X-Signature" type="string" required>
  Hex-encoded HMAC-SHA256 of `METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY`
</ParamField>

## Request Body

<ParamField body="limit" type="integer" default="20">
  Number of transactions (max 100)
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Pagination offset
</ParamField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  BODY='{"limit":20,"offset":0}'
  TIMESTAMP='2026-03-10T12:00:00Z'
  SIGNATURE=$(printf 'POST\n/api/v1/partner/transaction-history\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$OLIVE_HMAC_SECRET" -hex | sed 's/^.* //')

  curl -X POST "https://demo.api.vultlocal.com/api/v1/partner/transaction-history" \
    -H "X-API-Key-ID: $OLIVE_API_KEY_ID" \
    -H "X-Partner-ID: $OLIVE_PARTNER_ID" \
    -H "X-Timestamp: $TIMESTAMP" \
    -H "X-Signature: $SIGNATURE" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

## Response

```json theme={null}
{
  "success": true,
  "partner_id": "VULT",
  "balance": "15000.00",
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "partner_cashin",
      "status": "completed",
      "amount": "500.00",
      "fee": "0.00",
      "description": "Cash-in via VULT (ref: TXN-123456)",
      "created_at": "2025-01-15T10:30:00Z",
      "subscriber": "sub_xyz789"
    }
  ],
  "total_count": 150
}
```

## Notes

* Returns empty transactions array if partner has no transactions yet
* Account is created on first cash-in transaction

## Errors

| Status | Description                               |
| ------ | ----------------------------------------- |
| 400    | Invalid request body                      |
| 401    | Missing or invalid HMAC headers/signature |


## OpenAPI

````yaml olive-openapi.json POST /partner/transaction-history
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /partner/transaction-history:
    post:
      tags:
        - Partner
      summary: Transaction History
      description: Get partner's transaction history
      parameters:
        - name: X-API-Key-ID
          in: header
          required: true
          schema:
            type: string
        - name: X-Partner-ID
          in: header
          required: true
          schema:
            type: string
        - name: X-Timestamp
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                offset:
                  type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      description: >-
        API Key for third-party integrations (WhatsApp, Smart PAY, VULT).
        Format: 'Bearer olive_live_xxxxxxxxxxxxx'
      type: apiKey
      name: Authorization
      in: header

````