curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
-H "Authorization: Bearer sk_test_..."
import requests
resp = requests.get(
"https://sandbox.api.prava.space/v1/mandates",
headers={"Authorization": "Bearer sk_test_..."},
params={"customer_id": "user_123", "standing_only": "true"},
)
const resp = await fetch(
"https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
{
headers: {
Authorization: "Bearer sk_test_...",
},
}
);
{
"mandates": [
{
"id": "mdt_123",
"status": "active",
"state": "available",
"recurringFrequency": "monthly",
"merchantScope": "listed",
"merchantName": "Acme Store",
"approvedAmount": "40.00",
"remaining": "40.00",
"currency": "USD",
"validUntil": "2027-07-26T00:00:00Z",
"renewsAt": "2026-08-26T00:00:00Z",
"lastCharge": null,
"createdAt": "2026-07-26T00:00:00Z",
"updatedAt": "2026-07-26T00:00:00Z"
}
]
}
{
"error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}
{
"error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}
Server-Side API
List Mandates
List the standing mandates on an account, with approved and remaining amounts.
GET
/
v1
/
mandates
curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
-H "Authorization: Bearer sk_test_..."
import requests
resp = requests.get(
"https://sandbox.api.prava.space/v1/mandates",
headers={"Authorization": "Bearer sk_test_..."},
params={"customer_id": "user_123", "standing_only": "true"},
)
const resp = await fetch(
"https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
{
headers: {
Authorization: "Bearer sk_test_...",
},
}
);
{
"mandates": [
{
"id": "mdt_123",
"status": "active",
"state": "available",
"recurringFrequency": "monthly",
"merchantScope": "listed",
"merchantName": "Acme Store",
"approvedAmount": "40.00",
"remaining": "40.00",
"currency": "USD",
"validUntil": "2027-07-26T00:00:00Z",
"renewsAt": "2026-08-26T00:00:00Z",
"lastCharge": null,
"createdAt": "2026-07-26T00:00:00Z",
"updatedAt": "2026-07-26T00:00:00Z"
}
]
}
{
"error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}
{
"error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}
List the caller’s mandates. Merchant keys pass
customer_id; control-plane callers (dashboard) scope by dashboard_user_id (+ agent_id).
GET /v1/mandates · Authenticated with your secret key.
Need to create a mandate? Mandate creation is part of the Session APIs — create a mandate with a mandate_setup block on Create Session.
Query parameters
string
Filter to one customer — the
external_user_id (the user_id used at session creation) or a cus_ id.boolean
When
true, return only standing mandates (exclude the transient per-checkout mandates that every ordinary checkout creates internally).Response
object[]
Show mandate properties
Show mandate properties
string
Mandate id (
mdt_…).string
string
string
string
Display-derived usability:
available, consumed, expired, paused, cancelled, or pending.string
pending, active, paused, consumed, cancelled, or expired.string
one_time, weekly, monthly, yearly.string
any or listed.string
string
Authorized per-charge cap.
string
Remaining spend this window — indicative for display; the enforced ceiling is the amount cap at the card-network level.
string
string | null
string | null
Next cycle boundary for recurring mandates.
object | null
{ status, at }.string
string
Notes
- Use the returned
idwith Get a Mandate, Charge a Mandate, or the lifecycle actions.
Error responses
| Status | Code | Cause |
|---|---|---|
| 401 | AUTH_REQUIRED | Missing or invalid credentials |
| 403 | FORBIDDEN | Caller may not list these mandates |
curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
-H "Authorization: Bearer sk_test_..."
import requests
resp = requests.get(
"https://sandbox.api.prava.space/v1/mandates",
headers={"Authorization": "Bearer sk_test_..."},
params={"customer_id": "user_123", "standing_only": "true"},
)
const resp = await fetch(
"https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
{
headers: {
Authorization: "Bearer sk_test_...",
},
}
);
{
"mandates": [
{
"id": "mdt_123",
"status": "active",
"state": "available",
"recurringFrequency": "monthly",
"merchantScope": "listed",
"merchantName": "Acme Store",
"approvedAmount": "40.00",
"remaining": "40.00",
"currency": "USD",
"validUntil": "2027-07-26T00:00:00Z",
"renewsAt": "2026-08-26T00:00:00Z",
"lastCharge": null,
"createdAt": "2026-07-26T00:00:00Z",
"updatedAt": "2026-07-26T00:00:00Z"
}
]
}
{
"error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}
{
"error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}
Authorizations
Your secret key: sk_test_* (sandbox) or sk_live_* (production).
Query Parameters
Filter to one customer (merchant keys): the external_user_id or a cus_ id.
When true, return only standing mandates.
Response
The caller's mandates.
Show child attributes
Show child attributes