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

# Payment API

> HMAC-authenticated in-app OLIVE payment routes

<Info>
  Use these endpoints for in-app OLIVE payments. They support custom metadata and return that metadata after a successful payment.
</Info>

<Warning>
  Payment routes use HMAC headers, not bearer tokens: `X-API-Key-ID`, `X-Timestamp`, and `X-Signature`.
</Warning>

## Endpoints

<CardGroup cols={2}>
  <Card title="Process Payment" icon="credit-card" href="/api-reference/payment/payment">
    `POST /api/v1/payment`

    Process an in-app OLIVE payment and attach arbitrary metadata
  </Card>

  <Card title="Verify Card" icon="search">
    `POST /api/v1/payment/verify-card`

    Same behavior as the POS verify-card endpoint
  </Card>

  <Card title="Refund" icon="undo">
    `POST /api/v1/payment/refund`

    Same behavior as the POS refund endpoint
  </Card>

  <Card title="Lookup Card" icon="info">
    `POST /api/v1/payment/lookup-card`

    Same behavior as the POS lookup-card endpoint
  </Card>
</CardGroup>

## Notes

* `POST /api/v1/payment` is for in-app payments, not POS terminal payments.
* `terminal_id` and `pin` are not used on payment routes — the integrating partner's HMAC signature provides the security.
* Custom `metadata` can be any valid JSON object, array, string, number, boolean, or `null` and is echoed back in the success response.
* `POST /api/v1/payment/verify-account` is also available and mirrors the POS account verification route.