Shared Payment Tokens
Download the complete public OpenAPI schema
Shared Payment Tokens
Create, refresh, and revoke profile payment-method credentials that can be shared with compatible agentic merchants.
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/shared_payment_tokens
Create a Shared Payment Token
Reserve card budget and issue a Stripe Shared Payment Token scoped to one validated seller, amount, currency, and expiry. Requires Idempotency-Key.
Parameters, request, responses, and security
{
"tags": [
"shared-payment-tokens"
],
"summary": "Create a Shared Payment Token",
"description": "Reserve card budget and issue a Stripe Shared Payment Token scoped to one validated seller, amount, currency, and expiry. Requires Idempotency-Key.",
"operationId": "v1_create_shared_payment_token",
"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"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Idempotency-Key"
},
"name": "Idempotency-Key",
"in": "header"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedPaymentTokenCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedPaymentTokenCreateResponse"
}
}
}
},
"202": {
"description": "Stripe create outcome is ambiguous; reconciliation is pending.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedPaymentTokenCreateResponse"
}
}
}
},
"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_shared_payment_token",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/shared_payment_tokens",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 60,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../shared_payment_tokens \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"seller\": {\n \"type\": \"network_business_profile\"\n },\n \"usage_limits\": {\n \"max_amount\": 1,\n \"currency\": \"AED\"\n }\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_create_shared_payment_token\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"seller\": {\n \"type\": \"network_business_profile\"\n },\n \"usage_limits\": {\n \"max_amount\": 1,\n \"currency\": \"AED\"\n }\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_shared_payment_token\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"seller\": {\n \"type\": \"network_business_profile\"\n },\n \"usage_limits\": {\n \"max_amount\": 1,\n \"currency\": \"AED\"\n }\n},\n});"
}
]
}
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/shared_payment_tokens/{issuance_id}/refresh
Refresh a Shared Payment Token
Reconcile Stripe status, captured usage, and any Stripe.js next action. The bearer token is never returned by refresh.
Parameters, request, responses, and security
{
"tags": [
"shared-payment-tokens"
],
"summary": "Refresh a Shared Payment Token",
"description": "Reconcile Stripe status, captured usage, and any Stripe.js next action. The bearer token is never returned by refresh.",
"operationId": "v1_refresh_shared_payment_token",
"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"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Issuance Id"
},
"name": "issuance_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedPaymentTokenRead"
}
}
}
},
"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_refresh_shared_payment_token",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/shared_payment_tokens/{issuance_id}/refresh",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 70,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../shared_payment_tokens/.../refresh \\\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_refresh_shared_payment_token\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"issuance_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_refresh_shared_payment_token\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"issuance_id\": \"...\"\n},\n});"
}
]
}
POST /v1/profiles/{profile_id}/payment_methods/{payment_method_id}/shared_payment_tokens/{issuance_id}/revoke
Revoke a Shared Payment Token
Permanently revoke the Stripe token and release its unused local budget reservation. Previously captured usage remains in the spend ledger.
Parameters, request, responses, and security
{
"tags": [
"shared-payment-tokens"
],
"summary": "Revoke a Shared Payment Token",
"description": "Permanently revoke the Stripe token and release its unused local budget reservation. Previously captured usage remains in the spend ledger.",
"operationId": "v1_revoke_shared_payment_token",
"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"
},
{
"required": true,
"schema": {
"type": "string",
"title": "Issuance Id"
},
"name": "issuance_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SharedPaymentTokenRead"
}
}
}
},
"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_revoke_shared_payment_token",
"x-mcp-exposed": true,
"x-public-path": "/v1/profiles/{profile_id}/payment_methods/{payment_method_id}/shared_payment_tokens/{issuance_id}/revoke",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 1,
"x-docs-action-order": 80,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/profiles/.../payment_methods/.../shared_payment_tokens/.../revoke \\\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_revoke_shared_payment_token\",\n \"arguments\": {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"issuance_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_revoke_shared_payment_token\",\n arguments: {\n \"profile_id\": \"...\",\n \"payment_method_id\": \"...\",\n \"issuance_id\": \"...\"\n},\n});"
}
]
}