Plugins
Extensions served under a slug: list them, install one for your account, and call its queries and commands.
Each plugin with its manifest (capabilities, egress, config settings, queries, commands, events) and installation: this consumer's installation of it, or null. An installation lists pendingCapabilities when the plugin was updated to ask for more than was granted, and its actions are refused until it is installed again. Answers { data }, not paged.
Requires the plugins:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
OK
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/plugins'{ "data": [ { "slug": "example", "name": "Example: payment notes", "version": "1.0.0", "description": "Reference plugin: keeps a timeline of notes per payment intent, and adds one when it is paid.", "author": "Cosmos Pay support", "capabilities": [ "payment_intents:read" ], "egress": [], "config": { "label": { "type": "string", "description": "Optional prefix for every note, e.g. your team name.", "required": false, "secret": false } }, "queries": [ "get-notes" ], "commands": [ "add-note" ], "events": [ "PAYMENT_INTENT_SUCCEEDED" ], "installation": { "id": "clx9z8a1b0000abcd1234efgh", "pluginVersion": "1.0.0", "grantedCapabilities": [ "payment_intents:read" ], "pendingCapabilities": [], "config": {}, "secretsSet": [], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" } } ]}One plugin's manifest and this consumer's installation of it (null when not installed). Read it before installing: PUT /v1/plugins/{slug}/installation must grant exactly the capabilities listed here. Secret settings are never returned; installation.secretsSet names the ones that hold a value.
Requires the plugins:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
slug*stringThe plugin, e.g. example.
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example'{ "slug": "example", "name": "Example: payment notes", "version": "1.0.0", "description": "Reference plugin: keeps a timeline of notes per payment intent, and adds one when it is paid.", "author": "Cosmos Pay support", "capabilities": [ "payment_intents:read" ], "egress": [], "config": { "label": { "type": "string", "description": "Optional prefix for every note, e.g. your team name.", "required": false, "secret": false } }, "queries": [ "get-notes" ], "commands": [ "add-note" ], "events": [ "PAYMENT_INTENT_SUCCEEDED" ], "installation": { "id": "clx9z8a1b0000abcd1234efgh", "pluginVersion": "1.0.0", "grantedCapabilities": [ "payment_intents:read" ], "pendingCapabilities": [], "config": {}, "secretsSet": [], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}Deletes this consumer's installation and, with it, everything the plugin stored for the consumer. It works even when the deployment no longer serves the plugin; a plugin that is not installed is a 404. Answers { slug, uninstalled: true }.
Requires the plugins:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
slug*stringThe plugin, e.g. example.
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/installation'{ "slug": "example", "uninstalled": true}Installing is consent: grantCapabilities must list exactly the capabilities the plugin declares, no more and no fewer (400 plugin_consent_mismatch). config is checked against the plugin's settings; secret settings are stored sealed and kept when not sent again. Call it again after an update leaves pendingCapabilities; it answers the plugin with its new installation.
Requires the plugins:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
slug*stringThe plugin, e.g. example.
application/json- body
Request to install a plugin, or re-consent to or reconfigure it: consent to exactly its capabilities, and its settings.
grantCapabilities*array<string>Consent: exactly the capabilities the plugin declares (see GET /v1/plugins/{slug}). A partial or extra list is refused, so installing means having read it.
config?Settings, as the plugin declares them. Secret fields are sealed at rest and never returned; leave one out on a re-install to keep the value already stored.
OK
validation_failed: The body, query or headers failed validation
plugin_consent_mismatch: grantCapabilities must list exactly the capabilities the plugin declares
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X PUT 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/installation' \ -H 'Content-Type: application/json' \ -d '{ "grantCapabilities": [ "payment_intents:read" ]}'{ "slug": "example", "name": "Example: payment notes", "version": "1.0.0", "description": "Reference plugin: keeps a timeline of notes per payment intent, and adds one when it is paid.", "author": "Cosmos Pay support", "capabilities": [ "payment_intents:read" ], "egress": [], "config": { "label": { "type": "string", "description": "Optional prefix for every note, e.g. your team name.", "required": false, "secret": false } }, "queries": [ "get-notes" ], "commands": [ "add-note" ], "events": [ "PAYMENT_INTENT_SUCCEEDED" ], "installation": { "id": "clx9z8a1b0000abcd1234efgh", "pluginVersion": "1.0.0", "grantedCapabilities": [ "payment_intents:read" ], "pendingCapabilities": [], "config": {}, "secretsSet": [], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }}Runs one of the plugin's queries with input (JSON, at most 64 KiB) and answers its output; a query cannot write the plugin storage, customers or products. The plugin must be installed with every capability it now asks for (409 plugin_not_installed). A refusal by the plugin is 400 plugin_rejected, a failure 502 plugin_failed, and a run over 10 seconds 504 plugin_failed.
Requires the plugins:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
slug*stringThe plugin, e.g. example.
action*stringAn action the plugin lists under queries / commands.
application/json- body
Request to run one of a plugin's queries or commands.
input?The action input, as the plugin documents it. Plain JSON, at most 64 KiB.
OK
validation_failed: The body, query or headers failed validation
plugin_rejected: The plugin refused the input; the message is the plugin’s own
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
plugin_not_installed: The plugin is not installed for this key, or its consent is out of date
The budget in x-cosmos-rate-limit is spent for this caller. Honour Retry-After.
The ratelimit-* triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers 503 provider_unavailable.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
plugin_failed: The plugin failed or timed out (the detail is logged, never returned)
plugin_failed: The plugin failed or timed out (the detail is logged, never returned)
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/queries/get-notes' \ -H 'Content-Type: application/json' \ -d '{}'{ "plugin": "example", "action": "get-notes", "output": { "paymentIntentId": "clx9z8a1b0000abcd1234efgh", "notes": [ { "at": "2026-09-29T12:00:00.000Z", "text": "Customer called", "source": "tenant" } ] }}Runs one of the plugin's commands with input (JSON, at most 64 KiB) and answers its output; a command may write its own storage and, as far as the granted capabilities allow, this consumer's customers and products. It needs an installation with every capability the plugin now asks for (409 plugin_not_installed), and storage is capped per installation (409 plugin_quota_exceeded). A refusal by the plugin is 400 plugin_rejected, a failure 502 plugin_failed, and a run over 10 seconds 504 plugin_failed.
Requires the plugins:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
slug*stringThe plugin, e.g. example.
action*stringAn action the plugin lists under queries / commands.
application/json- body
Request to run one of a plugin's queries or commands.
input?The action input, as the plugin documents it. Plain JSON, at most 64 KiB.
OK
validation_failed: The body, query or headers failed validation
plugin_rejected: The plugin refused the input; the message is the plugin’s own
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
plugin_not_installed: The plugin is not installed for this key, or its consent is out of date
plugin_quota_exceeded: The installation holds as many records as it may
The budget in x-cosmos-rate-limit is spent for this caller. Honour Retry-After.
The ratelimit-* triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers 503 provider_unavailable.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
plugin_failed: The plugin failed or timed out (the detail is logged, never returned)
plugin_failed: The plugin failed or timed out (the detail is logged, never returned)
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/plugins/example/commands/add-note' \ -H 'Content-Type: application/json' \ -d '{}'{ "plugin": "example", "action": "get-notes", "output": { "paymentIntentId": "clx9z8a1b0000abcd1234efgh", "notes": [ { "at": "2026-09-29T12:00:00.000Z", "text": "Customer called", "source": "tenant" } ] }}Public Key
The shared public API key, served without a key to wallets that have no account yet. Not a secret: what it may call is confined server-side to routes that return no per-consumer data.
Aliases
Payment handles: resolve a name to its addresses, and claim or manage one with a signature by each address it points at.