Budgets
Download the complete public OpenAPI schema
Budgets
Create and manage standing spending budgets on a profile's payment methods, then draw one-time card credentials against them.
A standing budget is a pre-approved allowance (optionally recurring weekly, monthly, or yearly) attached to a payment method. Once the budget is approved and verified, the credentials API draws against it repeatedly; each draw decrements the remaining budget.
GET /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/budget
Retrieve a standing budget
Return the current standing credentials budget for a profile PaymentMethod.
Parameters, request, responses, and security
{
"tags": [
"budgets"
],
"summary": "Retrieve a standing budget",
"description": "Return the current standing credentials budget for a profile PaymentMethod.",
"operationId": "v1_get_payment_method_budget",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Profile Id"
},
"name": "profile_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Payment Method Id"
},
"name": "payment_method_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicStandingBudgetRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_get_payment_method_budget",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/budget",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 20,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X GET https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../budget \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_get_payment_method_budget\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_get_payment_method_budget\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\"\n},\n});"
}
]
}
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/budget
Create or update standing budget
Create, amend, cancel, or verify the current standing credentials budget. The instruction id is derived from the PaymentMethod.
Parameters, request, responses, and security
{
"tags": [
"budgets"
],
"summary": "Create or update standing budget",
"description": "Create, amend, cancel, or verify the current standing credentials budget. The instruction id is derived from the PaymentMethod.",
"operationId": "v1_apply_payment_method_budget_command",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Profile Id"
},
"name": "profile_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Payment Method Id"
},
"name": "payment_method_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicStandingBudgetCommandRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicStandingBudgetRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_apply_payment_method_budget_command",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/budget",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 10,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../budget \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"action\": \"create\"\n}'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_apply_payment_method_budget_command\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"action\": \"create\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_apply_payment_method_budget_command\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"action\": \"create\"\n},\n});"
}
]
}
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/credentials
Issue one-time card credentials
Issue one-time scoped virtual card credentials against the PaymentMethod standing budget. A positive amount and matching currency are required. Optional merchant details lock the card to the merchant.
Parameters, request, responses, and security
{
"tags": [
"budgets"
],
"summary": "Issue one-time card credentials",
"description": "Issue one-time scoped virtual card credentials against the PaymentMethod standing budget. A positive amount and matching currency are required. Optional merchant details lock the card to the merchant.",
"operationId": "v1_issue_payment_method_credentials",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Profile Id"
},
"name": "profile_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Payment Method Id"
},
"name": "payment_method_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CredentialIssueRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CredentialIssueResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_issue_payment_method_credentials",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/credentials",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 30,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../credentials \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"amount_cents\": 1,\n \"currency_code\": \"AED\"\n}'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_issue_payment_method_credentials\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"amount_cents\": 1,\n \"currency_code\": \"AED\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_issue_payment_method_credentials\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"amount_cents\": 1,\n \"currency_code\": \"AED\"\n},\n});"
}
]
}
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/budget/payment_verification_challenge
Create a standing budget verification challenge
Start the cardholder passkey or redirect verification ceremony for the PaymentMethod standing budget. The instruction id is derived server-side.
Parameters, request, responses, and security
{
"tags": [
"budgets"
],
"summary": "Create a standing budget verification challenge",
"description": "Start the cardholder passkey or redirect verification ceremony for the PaymentMethod standing budget. The instruction id is derived server-side.",
"operationId": "v1_create_standing_budget_verification_challenge",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Profile Id"
},
"name": "profile_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Payment Method Id"
},
"name": "payment_method_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StandingBudgetVerificationChallengeRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_create_standing_budget_verification_challenge",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/budget/payment_verification_challenge",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 40,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../budget/payment_verification_challenge \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_create_standing_budget_verification_challenge\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_create_standing_budget_verification_challenge\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\"\n},\n});"
}
]
}
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/charge
Simulate a charge against a standing budget (test mode)
Test mode only. Record a simulated draw against the PaymentMethod standing budget and decrement the remaining allowance by the charge amount. Optional merchant and item details are recorded on the draw. Returns 400 when the charge exceeds the remaining standing budget.
Parameters, request, responses, and security
{
"tags": [
"budgets"
],
"summary": "Simulate a charge against a standing budget (test mode)",
"description": "Test mode only. Record a simulated draw against the PaymentMethod standing budget and decrement the remaining allowance by the charge amount. Optional merchant and item details are recorded on the draw. Returns 400 when the charge exceeds the remaining standing budget.",
"operationId": "v1_simulate_payment_method_charge",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Profile Id"
},
"name": "profile_id",
"in": "path"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Payment Method Id"
},
"name": "payment_method_id",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CredentialChargeRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CredentialChargeResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_simulate_payment_method_charge",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/charge",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 50,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../charge \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"amount_cents\": 1,\n \"currency_code\": \"AED\"\n}'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_simulate_payment_method_charge\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"amount_cents\": 1,\n \"currency_code\": \"AED\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_simulate_payment_method_charge\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"amount_cents\": 1,\n \"currency_code\": \"AED\"\n},\n});"
}
]
}