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

# Pause a Mandate

> Suspend future charges on an active mandate.

Pause an active mandate so no new charges can be created until it is resumed. The request takes no body and returns the updated [mandate](https://docs.prava.space/api-reference/mandate-list.md).

`POST /v1/mandates/{id}/pause`

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

Returns the updated mandate object (see [List Mandates](https://docs.prava.space/api-reference/mandate-list.md)).

## Notes

* Only an `active` mandate can be paused. Any other transition returns `409 MANDATE_INVALID_TRANSITION`.
* Only the mandate's owner can act on it — a mismatched caller gets `403 MANDATE_FORBIDDEN`.
* To reactivate or permanently stop the mandate, use [Resume a Mandate](https://docs.prava.space/api-reference/mandate-resume.md) or [Cancel a Mandate](https://docs.prava.space/api-reference/mandate-cancel.md).

## Error responses

| Status | Code | Cause |
| - | - | - |
| 403 | `MANDATE_FORBIDDEN` | Caller does not own this mandate |
| 409 | `MANDATE_INVALID_TRANSITION` | The mandate's current status forbids this action |

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

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

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

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

```json 200 Success theme={null}
{ "id": "mdt_123", "status": "paused", "state": "paused", "merchantScope": "listed", "approvedAmount": "40.00", "currency": "USD" }
```

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

```json 409 Invalid Transition theme={null}
{
  "error": { "code": "MANDATE_INVALID_TRANSITION", "message": "The mandate's current status forbids this action" }
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/mandates/{id}/pause
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}/pause:
    post:
      summary: Pause a Mandate
      description: Suspend an active mandate. No charges succeed until it is resumed.
      operationId: pauseMandate
      parameters:
        - name: id
          in: path
          required: true
          description: The mandate id.
          schema:
            type: string
      responses:
        '200':
          description: Updated mandate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mandate'
        '403':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
components:
  schemas:
    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
    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.