Charge a Mandate

curl -X POST https://sandbox.api.prava.space/v1/mandates/mdt_123/charge \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "40.00", "reference": "invoice_2026_07" }'

import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/mandates/mdt_123/charge",
    headers={"Authorization": "Bearer sk_test_..."},
    json={"amount": "40.00", "reference": "invoice_2026_07"},
)

const resp = await fetch("https://sandbox.api.prava.space/v1/mandates/mdt_123/charge", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "40.00",
    reference: "invoice_2026_07",
  }),
});

{
  "mandateId": "mdt_123",
  "instructionId": "ins_1",
  "transactionId": "txn_9",
  "orderId": "ord_9",
  "status": "awaiting_result",
  "fetchStatus": "SUCCESS",
  "credentials": { "token": "4111111111111111", "dynamicCvv": "123", "expiryMonth": "12", "expiryYear": "2030" },
  "deduplicated": false
}

{
  "error": { "code": "MANDATE_FORBIDDEN", "message": "Caller does not own this mandate" }
}

{
  "error": { "code": "MANDATE_NOT_ACTIVE", "message": "Mandate is not active" }
}

Mint fresh single-use card credentials against an active mandate — no passkey. Merchant callers receive plaintext credentials; agent callers receive an encrypted_payload (credentials encrypted to the agent’s public key). POST /v1/mandates/{id}/charge · Authenticated with your secret key (merchants) or Ed25519 signature (agents).

Charging is available to merchants (secret key) and agents (Ed25519 signature). It is deliberately not exposed over MCP. See Mandates for the model.

Path parameters

string

required

The mandate id (from List Mandates).

Body

string

required

Charge amount as a decimal string with up to 2 decimals, e.g. "40.00". The per-charge cap is enforced by the card network — an over-cap charge is declined (THRESHOLD_EXCEEDED).

string

Idempotency key (max 255). The same mandate id + reference returns the original charge (deduplicated: true) instead of minting again. Omit it and every call is a distinct charge. A failed charge clears its key, so a retry after failure is not deduplicated.

object[]

Optional per-charge product details (exactly one entry, same shape as Create Session). Omit to reuse the mandate’s setup context. Currency always comes from the mandate, never the charge.

Response

string

Pass this to Report a Mandate Charge.

string

awaiting_result or failed.

string

SUCCESS or FAILURE.

object

Merchant callers: { token, dynamicCvv, expiryMonth, expiryYear }.

object

Agent callers: { ephemeral_public_key, iv, auth_tag, data }, decrypted client-side.

string

e.g. THRESHOLD_EXCEEDED on an over-cap decline.

boolean

True when a prior charge with the same reference was returned.

Notes

The mandate must be active. Charging a non-active mandate returns 409 MANDATE_NOT_ACTIVE.
An over-cap charge is a normal outcome: status: "failed" with an errorMessage such as THRESHOLD_EXCEEDED. The amount cap is enforced at the card-network level.
A charge outside a listed mandate’s merchant returns 403 MANDATE_MERCHANT_NOT_ALLOWED.
After checkout, settle the outcome with Report a Mandate Charge.

Error responses

Status	Code	Cause
400	`VAL_2001`	Missing or invalid `amount`
401	`AUTH_REQUIRED`	Missing or invalid credentials
403	`MANDATE_FORBIDDEN`	Caller does not own this mandate
403	`MANDATE_MERCHANT_NOT_ALLOWED`	Listed-scope mandate; the charge names a merchant not on the allow-list
409	`MANDATE_NOT_ACTIVE`	Mandate is not `active`
409	`NO_INSTRUCTION` / `NO_ORDER`	Mandate is missing its instruction/order
500	`NO_TOKEN`	Credential minting failed

curl -X POST https://sandbox.api.prava.space/v1/mandates/mdt_123/charge \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "40.00", "reference": "invoice_2026_07" }'

import requests

resp = requests.post(
    "https://sandbox.api.prava.space/v1/mandates/mdt_123/charge",
    headers={"Authorization": "Bearer sk_test_..."},
    json={"amount": "40.00", "reference": "invoice_2026_07"},
)

const resp = await fetch("https://sandbox.api.prava.space/v1/mandates/mdt_123/charge", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_test_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "40.00",
    reference: "invoice_2026_07",
  }),
});

{
  "mandateId": "mdt_123",
  "instructionId": "ins_1",
  "transactionId": "txn_9",
  "orderId": "ord_9",
  "status": "awaiting_result",
  "fetchStatus": "SUCCESS",
  "credentials": { "token": "4111111111111111", "dynamicCvv": "123", "expiryMonth": "12", "expiryYear": "2030" },
  "deduplicated": false
}

{
  "error": { "code": "MANDATE_FORBIDDEN", "message": "Caller does not own this mandate" }
}

{
  "error": { "code": "MANDATE_NOT_ACTIVE", "message": "Mandate is not active" }
}

Report Status Report a Mandate Charge

Server-Side API

Reference

Path parameters

Body

Response

Notes

Error responses

​Path parameters

​Body

​Response

​Notes

​Error responses

Path parameters

Body

Response

Notes

Error responses