Skip to content

Mercury (API Token)

Connect Mercury accounts using a scoped API token

PropertyValue
Template IDmercury
CategoryFinance
Credential TypeBearer Token

The managed Mercury SDK accepts API-token managed secrets and partner OAuth connections.

  1. Sign in to Mercury and open All Settings → Tokens.
  2. Select Create Token, name it, and choose Read Only, Read and Write, or Custom permissions for the required operations.
  3. Copy the complete token, including a secret-token: prefix if present.
  4. For a write token, configure the IP whitelist Mercury requires for your integration.

Custom token scopes cannot be edited. Create a replacement token to change them. Mercury can delete unused tokens after 45 days and downgrade their permissions according to its token security policies.

In your application in the Developer Portal, open Managed Secrets, add Mercury, paste the token and save. Restrict its allowed hosts and create a system grant for the application or agent.

Terminal window
alter managed-secrets set-allowed-hosts <secret> --host api.mercury.com

Card PAN/CVC retrieval uses the separate vault-api.mercury.com host. Include that host only when the application needs it. For sandbox, create a separate token at sandbox.mercury.com and restrict its allowed host to api-sandbox.mercury.com. Alter selects the environment from these saved host restrictions and refuses mixed production/sandbox restrictions. Mercury documents no sandbox Vault API origin.

Custom scopes can omit any particular read endpoint, so there is no universal token verification request. Alter reports save-time verification as skipped; confirm access with an operation that the token permits.

from alter_sdk_mercury import MercuryIntegration
client = MercuryIntegration(alter_app, {"grant_id": "YOUR_GRANT_ID"})
result = await (await client.accounts.get_accounts({})).wait()
print(result.body_json())

See Mercury’s getting started guide, API token security policies, sandbox guide, and Vault API reference.

Operation IDFamiliesMethodProvider pathNotes
mercury:getAccountCardsreadGET/api/v1/account/{accountId}/cards—
mercury:requestSendMoneypayment, send, writePOST/api/v1/account/{accountId}/request-send-money—
mercury:getAccountStatementsreadGET/api/v1/account/{accountId}/statements—
mercury:getTransactionreadGET/api/v1/account/{accountId}/transaction/{transactionId}—
mercury:listAccountTransactionsreadGET/api/v1/account/{accountId}/transactions—
mercury:createTransactionpayment, send, writePOST/api/v1/account/{accountId}/transactions—
mercury:getAccountsreadGET/api/v1/accounts—
mercury:createInternalTransferpayment, writePOST/api/v1/transfer—
mercury:getRecipientreadGET/api/v1/recipient/{recipientId}allowed; its secret is never stored in a payload capture
mercury:getRecipientsreadGET/api/v1/recipientsallowed; its secret is never stored in a payload capture
mercury:updateRecipientpayment, writePOST/api/v1/recipient/{recipientId}also payment when (body.@EditRecipientRequest.address is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.checkInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.domesticWireRoutingInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.electronicRoutingInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.realTimePaymentRoutingInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.name is present ({"missing”: false, “null”: true, “type”: “string"})); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture
mercury:createRecipientwritePOST/api/v1/recipientsallowed; its secret is never stored in a payload capture
mercury:uploadRecipientAttachmentwritePOST/api/v1/recipient/{recipientId}/attachments—
mercury:listRecipientsAttachmentsreadGET/api/v1/recipients/attachmentsallowed; its secret is never stored in a payload capture
mercury:deleteRecipientdeleteDELETE/api/v1/recipient/{recipientId}—
mercury:createRecipientInvitepayment, send, writePOST/api/v1/recipients/invitesalso send when body.@CreateRecipientInviteApiRequest.sendEmail is one of [true] ({"missing”: null, “null”: null, “type”: “boolean"}); also payment when (body.@CreateRecipientInviteApiRequest.recipientId is present ({"missing”: false, “null”: false, “type”: “string"})) and (body.@CreateRecipientInviteApiRequest.name is present ({"missing”: false, “null”: true, “type”: “string"})); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture
mercury:getRecipientInvitereadGET/api/v1/recipients/invites/{inviteId}allowed; its secret is never stored in a payload capture
mercury:listRecipientInvitesreadGET/api/v1/recipients/invitesallowed; its secret is never stored in a payload capture
mercury:deleteRecipientInvitedeleteDELETE/api/v1/recipients/invites/{inviteId}—
mercury:listSendMoneyApprovalRequestsreadGET/api/v1/request-send-money—
mercury:getSendMoneyApprovalRequestreadGET/api/v1/request-send-money/{requestId}—
mercury:requestTransferMoneypayment, writePOST/api/v1/request-transfer—
mercury:listTransferMoneyApprovalRequestsreadGET/api/v1/request-transfer—
mercury:getTransferMoneyApprovalRequestreadGET/api/v1/request-transfer/{requestId}—
mercury:getTreasuryreadGET/api/v1/treasury—
mercury:getTreasuryTransactionsreadGET/api/v1/treasury/{treasuryId}/transactions—
mercury:getTreasuryStatementsreadGET/api/v1/treasury/{treasuryId}/statements—
mercury:getStatementPdfreadGET/api/v1/statements/{statementId}/pdf—
mercury:updateTransactionwritePATCH/api/v1/transaction/{transactionId}—
mercury:listTransactionsreadGET/api/v1/transactions—
mercury:getTransactionByIdreadGET/api/v1/transaction/{transactionId}—
mercury:uploadTransactionAttachmentwritePOST/api/v1/transaction/{transactionId}/attachments—
mercury:listCategoriesreadGET/api/v1/categories—
mercury:createCategorywritePOST/api/v1/categories—
mercury:editCategorywritePOST/api/v1/categories/{expenseCategoryId}—
mercury:deleteCategorydeleteDELETE/api/v1/categories/{expenseCategoryId}—
mercury:listMerchantsreadGET/api/v1/merchants—
mercury:listCreditreadGET/api/v1/credit—
mercury:getCreditAccountStatementsreadGET/api/v1/credit/{accountId}/statements—
mercury:getOrganizationreadGET/api/v1/organization—
mercury:getAttachmentreadGET/api/v1/ar/attachments/{attachmentId}allowed; its secret is never stored in a payload capture
mercury:listCustomersreadGET/api/v1/ar/customers—
mercury:createCustomerwritePOST/api/v1/ar/customers—
mercury:deleteCustomerdeleteDELETE/api/v1/ar/customers/{customerId}—
mercury:getCustomerreadGET/api/v1/ar/customers/{customerId}—
mercury:updateCustomerpayment, send, writePOST/api/v1/ar/customers/{customerId}also send when body.@ApiV1ArCustomerUpdateRequest.resendOpenInvoices is one of [true] ({"missing”: null, “null”: null, “type”: “boolean"}); the family column is the upper bound; base families are write, payment; unreadable or invalid effect inputs are refused when the request condition reads them
mercury:listInvoicesreadGET/api/v1/ar/invoicesallowed; its secret is never stored in a payload capture
mercury:createInvoicepayment, send, writePOST/api/v1/ar/invoicesalso send when (body.@ApiV1ArInvoiceCreateRequest.sendEmailOption is one of [“SendNow”] ({"missing”: true, “null”: null, “type”: “string”, “valid_values”: [“DontSend”, “SendNow"]})) or (body.@ApiV1ArInvoiceCreateRequest.ccEmails is nonempty ({"missing”: null, “null”: null, “type”: “array"})); the family column is the upper bound; base families are payment, write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture
mercury:getInvoicereadGET/api/v1/ar/invoices/{invoiceId}allowed; its secret is never stored in a payload capture
mercury:updateInvoicepayment, send, writePOST/api/v1/ar/invoices/{invoiceId}also send when body.@ApiV1ArInvoiceUpdateRequest.ccEmails is nonempty ({"missing”: null, “null”: null, “type”: “array"}); the family column is the upper bound; base families are payment, write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture
mercury:cancelInvoicedelete, paymentPOST/api/v1/ar/invoices/{invoiceId}/cancel—
mercury:listInvoiceAttachmentsreadGET/api/v1/ar/invoices/{invoiceId}/attachmentsallowed; its secret is never stored in a payload capture
mercury:getInvoicePdfreadGET/api/v1/ar/invoices/{invoiceId}/pdf—
mercury:getEventsreadGET/api/v1/events—
mercury:getEventreadGET/api/v1/events/{eventId}—
mercury:createWebhookadmin, send, writePOST/api/v1/webhooksallowed; its secret is never stored in a payload capture; delivery address in policy parameter url
mercury:updateWebhookadmin, delete, send, writePOST/api/v1/webhooks/{webhookEndpointId}also delete when body.@UpdateWebhookParams.status is one of [“paused”] ({"missing”: false, “null”: null, “type”: “string”, “valid_values”: [“active”, “paused"]}); also send when (body.@UpdateWebhookParams.url is non-null ({"missing”: false, “null”: null, “type”: “string"})) or (body.@UpdateWebhookParams.status is one of [“active”] ({"missing”: false, “null”: null, “type”: “string”, “valid_values”: [“active”, “paused"]})) or (body.@UpdateWebhookParams.eventTypes is present ({"missing”: false, “null”: true, “type”: “array"})) or (body.@UpdateWebhookParams.filterPaths is present ({"missing”: false, “null”: true, “type”: “array"})); the family column is the upper bound; base families are write, admin; unreadable or invalid effect inputs are refused when the request condition reads them; delivery address in policy parameter url
mercury:verifyWebhooksendPOST/api/v1/webhooks/{webhookEndpointId}/verify—
mercury:getWebhookreadGET/api/v1/webhooks/{webhookEndpointId}—
mercury:getWebhooksreadGET/api/v1/webhooks—
mercury:deleteWebhookadmin, deleteDELETE/api/v1/webhooks/{webhookEndpointId}—
mercury:getUserreadGET/api/v1/users/{userId}—
mercury:getUsersreadGET/api/v1/users—
mercury:getSafeRequestsreadGET/api/v1/safes—
mercury:getSafeRequestreadGET/api/v1/safes/{safeRequestId}—
mercury:getSafeRequestDocumentreadGET/api/v1/safes/{safeRequestId}/document—
mercury:listReceiptsreadGET/api/v1/spend/receipts—
mercury:createReceiptUploadUrlwritePOST/api/v1/spend/receiptsallowed; its secret is never stored in a payload capture
mercury:getReceiptreadGET/api/v1/spend/receipts/{receiptId}—
mercury:matchReceiptwritePOST/api/v1/spend/receipts/{receiptId}/match—
mercury:listBudgetsreadGET/api/v1/spend/budgets—
mercury:createBudgetwritePOST/api/v1/spend/budgets—
mercury:getBudgetreadGET/api/v1/spend/budgets/{budgetId}—
mercury:updateBudgetpayment, writePOST/api/v1/spend/budgets/{budgetId}also payment when (body.@ApiV1UpdateBudgetRequest.amountPerUserPerPeriod is non-null ({"missing”: false, “null”: false, “type”: “number"})) or (body.@ApiV1UpdateBudgetRequest.frequency is non-null ({"missing”: false, “null”: false, “type”: “string”, “valid_values”: [“oneTime”, “daily”, “weekly”, “monthly”, “yearly"]})) or (body.@ApiV1UpdateBudgetRequest.startDate is non-null ({"missing”: false, “null”: false, “type”: “string"})) or (body.@ApiV1UpdateBudgetRequest.endDate is non-null ({"missing”: false, “null”: false, “type”: “string"})); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them
mercury:archiveBudgetdeletePOST/api/v1/spend/budgets/{budgetId}/archive—
mercury:assignTransactionToBudgetwritePOST/api/v1/spend/budgets/{budgetId}/assign-transaction—
mercury:getBudgetExpendituresreadGET/api/v1/spend/budgets/{budgetId}/expenditures—
mercury:getBudgetMembersreadGET/api/v1/spend/budgets/{budgetId}/members—
mercury:listCardsreadGET/api/v1/cards—
mercury:createCardpayment, writePOST/api/v1/cards—
mercury:getCardreadGET/api/v1/cards/{cardId}—
mercury:updateCardpayment, writePOST/api/v1/cards/{cardId}also payment when body.@UpdateCardRequest.spendLimit is present ({"missing”: false, “null”: true}); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them
mercury:cancelCarddeletePOST/api/v1/cards/{cardId}/cancel—
mercury:freezeCarddeletePOST/api/v1/cards/{cardId}/freeze—
mercury:unfreezeCardpayment, writePOST/api/v1/cards/{cardId}/unfreeze—
mercury:revealCardPanreadGET/api/v1/cards/{cardId}/reveal—
mercury:getAutoTransferRulesreadGET/api/v1/auto-transfer-rules—
auth:authorization_endpointadmin, send, writeGET/oauth2/authrefused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec
auth:token_endpointadmin, writePOST/oauth2/tokenrefused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec
auth:userinfo_endpointreadGET/userinfoserved by the provider but absent from its published spec
auth:revocation_endpointadmin, deletePOST/oauth2/revokerefused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec
auth:device_authorization_endpointwritePOST/oauth2/device/authallowed; its secret is never stored in a payload capture; served by the provider but absent from its published spec
auth:end_session_endpointdelete, sendGET/oauth2/sessions/logoutserved by the provider but absent from its published spec
auth:jwks_urireadGET/.well-known/jwks.jsonserved by the provider but absent from its published spec
auth:credentials_endpoint_draft_00admin, read, writePOST/credentialsrefused by default when (not (a complete, unambiguous JSON object containing only format=jwt_vc_json and a type array of exactly VerifiableCredential and UserCredential in either order, with no proof or additional member)); a credential_minting rule can allow it; also admin, read when not (a complete, unambiguous JSON object containing only format=jwt_vc_json and a type array of exactly VerifiableCredential and UserCredential in either order, with no proof or additional member); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them; its secret is never stored in a payload capture; served by the provider but absent from its published spec
auth:authorization_endpoint:postadmin, send, writePOST/oauth2/authrefused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec
auth:userinfo_endpoint:postreadPOST/userinfoserved by the provider but absent from its published spec
auth:end_session_endpoint:postdelete, sendPOST/oauth2/sessions/logoutserved by the provider but absent from its published spec
mercury:createProductwritePOST/api/v1/ar/products—
mercury:listProductsreadGET/api/v1/ar/products—
mercury:deleteProductdeleteDELETE/api/v1/ar/products/{productId}—

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.