> ## 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.

# Partner API

> External partner integration with HMAC authentication

<Info>
  The Partner API enables external systems like **VULT** to interact with OLIVE wallets. All requests require HMAC-SHA256 signature authentication.
</Info>

<Warning>
  The interactive Mintlify playground is disabled for partner endpoints because these routes require custom HMAC headers and a signature over the exact raw JSON body. Use the copyable bash examples on each endpoint page.
</Warning>

## Integration Partners

<CardGroup cols={3}>
  <Card title="VULT" icon="zap">
    Mobile money integration for wallet funding
  </Card>

  <Card title="Banks" icon="landmark">
    Bank transfer integrations
  </Card>

  <Card title="Custom" icon="plug">
    Custom partner integrations
  </Card>
</CardGroup>

***

## Endpoints

<CardGroup cols={3}>
  <Card title="Account Status" icon="user-check" color="#6366f1" href="/api-reference/partner/account-status">
    `POST /api/v1/partner/account-status`

    Check if subscriber account exists
  </Card>

  <Card title="Transaction History" icon="history" color="#8b5cf6" href="/api-reference/partner/transaction-history">
    `POST /api/v1/partner/transaction-history`

    Get partner's transaction history
  </Card>

  <Card title="Cash In" icon="plus-circle" color="#10b981" href="/api-reference/partner/cashin">
    `POST /api/v1/partner/cashin`

    Credit subscriber wallet
  </Card>
</CardGroup>

***

## Authentication

Partner API uses **HMAC-SHA256** signature authentication instead of Bearer tokens.

<Tabs>
  <Tab title="Required Headers">
    | Header         | Description                                  |
    | -------------- | -------------------------------------------- |
    | `X-API-Key-ID` | Partner API key ID                           |
    | `X-Partner-ID` | Your partner identifier (for example `VULT`) |
    | `X-Timestamp`  | RFC3339 timestamp                            |
    | `X-Signature`  | HMAC-SHA256 signature                        |
  </Tab>

  <Tab title="Signature Generation">
    ```javascript theme={null}
    const crypto = require('crypto');

    function generateSignature(method, path, body, timestamp, secret) {
      const canonicalString = `${method}\n${path}\n${timestamp}\n${body}`;
      
      return crypto
        .createHmac('sha256', secret)
        .update(canonicalString)
        .digest('hex');
    }

    // Example
    const signature = generateSignature(
      'POST',
      '/api/v1/partner/cashin',
      '{"phone_number":"0771234567","amount":50000,"reference":"PARTNER-TXN-123"}',
      '2026-03-10T12:00:00Z',
      'your_hmac_secret'
    );
    ```
  </Tab>

  <Tab title="Full Request">
    ```bash theme={null}
    BODY='{"phone_number":"0771234567","amount":50000,"reference":"PARTNER-TXN-123"}'
    TIMESTAMP='2026-03-10T12:00:00Z'
    SIGNATURE=$(printf 'POST\n/api/v1/partner/cashin\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/cashin \
      -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"
    ```
  </Tab>
</Tabs>

<Warning>
  Signatures are only valid for **5 minutes** from the timestamp. Ensure your server clock is synchronized.
</Warning>

***

## Cash-In Flow

<Steps>
  <Step title="Lookup Subscriber">
    Partner calls `account-status` to verify subscriber exists
  </Step>

  <Step title="Initiate Cash-In">
    Partner sends `cashin` request with amount and reference
  </Step>

  <Step title="Account Credited">
    Subscriber wallet is immediately credited
  </Step>

  <Step title="Partner Debited">
    Partner clearing account is debited (can go negative)
  </Step>

  <Step title="Confirmation">
    Transaction ID returned for reconciliation
  </Step>
</Steps>

***

## Response Examples

<Tabs>
  <Tab title="Account Status">
    ```json theme={null}
    {
      "success": true,
      "exists": true,
      "status": "active"
    }
    ```
  </Tab>

  <Tab title="Cash-In Success">
    ```json theme={null}
    {
      "success": true,
      "transaction_id": "txn_abc123",
      "message": "Cash-in successful",
      "data": {
        "subscriber_id": "sub_xyz789",
        "name": "John Doe",
        "amount": 5000000,
        "new_balance": 7500000,
        "currency": "SLE",
        "reference": "TXN-123456"
      }
    }
    ```
  </Tab>

  <Tab title="Transaction History">
    ```json theme={null}
    {
      "success": true,
      "partner_id": "VULT",
      "balance": "15000.00",
      "transactions": [
        {
          "id": "txn_abc123",
          "type": "partner_cashin",
          "status": "completed",
          "amount": "500.00",
          "created_at": "2025-01-15T10:30:00Z"
        }
      ],
      "total_count": 150
    }
    ```
  </Tab>
</Tabs>

***

## Error Handling

| Status | Code                 | Description                        |
| ------ | -------------------- | ---------------------------------- |
| 400    | `INVALID_REQUEST`    | Missing or invalid parameters      |
| 401    | `INVALID_SIGNATURE`  | HMAC signature verification failed |
| 401    | `EXPIRED_TIMESTAMP`  | Timestamp older than 5 minutes     |
| 404    | `USER_NOT_FOUND`     | Subscriber not found               |
| 500    | `TRANSACTION_FAILED` | Internal processing error          |

***

## Integration Checklist

<CardGroup cols={2}>
  <Card title="Development" icon="code">
    * [ ] Obtain `X-API-Key-ID`, partner ID, and HMAC secret
    * [ ] Implement signature generation
    * [ ] Test with sandbox environment
    * [ ] Handle all error responses
  </Card>

  <Card title="Production" icon="rocket">
    * [ ] Request production credentials
    * [ ] Set up webhook receivers
    * [ ] Configure reconciliation process
    * [ ] Enable monitoring/alerting
  </Card>
</CardGroup>