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

# Get a Mandate

> Retrieve one mandate with its balance and full charge history.

Retrieve one mandate with its derived balance and full charge history.

`GET /v1/mandates/{id}` · Authenticated with your secret key.

Need to **create** a mandate? Mandate creation is part of the Session APIs — [create a mandate](https://docs.prava.space/api-reference/create-session.md#mandate-setup) with a `mandate_setup` block on Create Session.

## Path parameters

**id** `string` *required*

The mandate id.

## Response

Everything in the [List Mandates](https://docs.prava.space/api-reference/mandate-list.md) mandate object, plus:

**spent** `string`

Cumulative amount charged.

**chargeCount** `integer`

**charges** `object[]`

**charge properties**

**transactionId** `string`

**amount** `string`

**currency** `string`

**status** `string`

**reference** `string | null`

Idempotency reference supplied at charge time.

**createdAt** `string`

## Error responses

| Status | Code | Cause |
| - | - | - |
| 401 | `AUTH_REQUIRED` | Missing or invalid credentials |
| 403 | `MANDATE_FORBIDDEN` | Caller does not own this mandate |
| 404 | `MANDATE_NOT_FOUND` | No such mandate |

```bash cURL theme={null}
curl "https://sandbox.api.prava.space/v1/mandates/mdt_123" \
  -H "Authorization: Bearer sk_test_..."
```

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

resp = requests.get(
    "https://sandbox.api.prava.space/v1/mandates/mdt_123",
    headers={"Authorization": "Bearer sk_test_..."},
)
```

```javascript JavaScript theme={null}
const resp = await fetch("https://sandbox.api.prava.space/v1/mandates/mdt_123", {
  headers: {
    Authorization: "Bearer sk_test_...",
  },
});
```

```json 200 Success theme={null}
{
  "id": "mdt_123",
  "status": "active",
  "approvedAmount": "40.00",
  "currency": "USD",
  "spent": "40.00",
  "chargeCount": 1,
  "charges": [
    { "transactionId": "txn_9", "amount": "40.00", "currency": "USD", "status": "completed", "reference": "invoice_2026_07", "createdAt": "2026-07-26T00:00:00Z" }
  ]
}
```

```json 403 Forbidden theme={null}
{
  "error": { "code": "MANDATE_FORBIDDEN", "message": "Caller does not own this mandate" }
}
```

```json 404 Not Found theme={null}
{
  "error": { "code": "MANDATE_NOT_FOUND", "message": "No such mandate" }
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /v1/mandates/{id}
openapi: 3.1.0
info:
  title: Prava Payments API
  description: >-
    Server-side REST API for Prava Payments. All requests are authenticated with
    your secret key (sk_test_* in sandbox, sk_live_* in production).
  version: 1.0.0
servers:
  - url: https://sandbox.api.prava.space
    description: Sandbox
  - url: https://api.prava.space
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/mandates/{id}:
    get:
      summary: Get a Mandate
      description: Retrieve one mandate with its derived balance and full charge history.
      operationId: getMandate
      parameters:
        - name: id
          in: path
          required: true
          description: The mandate id.
          schema:
            type: string
      responses:
        '200':
          description: The mandate detail view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateDetail'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
components:
  schemas:
    MandateDetail:
      allOf:
        - $ref: '#/components/schemas/Mandate'
        - type: object
          properties:
            spent:
              type: string
              description: Cumulative amount charged.
            chargeCount:
              type: integer
            charges:
              type: array
              items:
                $ref: '#/components/schemas/MandateCharge'
    Mandate:
      type: object
      description: A standing spending authorization (list view).
      properties:
        id:
          type: string
          description: Mandate id (mdt_…).
        agentId:
          type: string
        customerId:
          type: string
        externalUserId:
          type: string
        state:
          type: string
          enum:
            - available
            - consumed
            - expired
            - paused
            - cancelled
            - pending
          description: Display-derived usability.
        status:
          type: string
          enum:
            - pending
            - active
            - paused
            - consumed
            - cancelled
            - expired
        recurringFrequency:
          type: string
          enum:
            - one_time
            - weekly
            - monthly
            - yearly
        merchantScope:
          type: string
          enum:
            - any
            - listed
        merchantName:
          type: string
        approvedAmount:
          type: string
          description: The authorized per-charge cap.
        remaining:
          type: string
          description: >-
            Remaining spend in the current window (indicative; the network
            enforces the real cap).
        currency:
          type: string
        validUntil:
          type: string
          format: date-time
          nullable: true
        renewsAt:
          type: string
          format: date-time
          nullable: true
          description: Next cycle boundary for recurring mandates.
        lastCharge:
          type: object
          nullable: true
          properties:
            status:
              type: string
            at:
              type: string
              format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    MandateCharge:
      type: object
      description: One charge against a mandate.
      properties:
        transactionId:
          type: string
        amount:
          type: string
        currency:
          type: string
        status:
          type: string
        reference:
          type: string
          nullable: true
          description: Idempotency reference supplied at charge time.
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. VAL_2001, AUTH_1001)
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: >-
                Optional — included for validation errors to specify which
                fields failed
  responses:
    Error:
      description: Error response
      headers:
        X-Response-ID:
          $ref: '#/components/headers/XResponseId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    XResponseId:
      description: >-
        UUID correlation identifier for this response. Include it when
        contacting Prava support.
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your secret key: sk_test_* (sandbox) or sk_live_* (production).'

````

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