Mercury: Send money to a recipient
Mercury accounts.createTransaction: arguments, response, policy and SDK examples.
← Accounts operations · Get started
Operation mercury.createtransaction
Provider route: POST /account/{accountId}/transactions. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/mercury with npm, or alter-sdk-mercury with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { MercuryIntegration } from "@alter-ai/mercury";
async function execute(input: Parameters<MercuryIntegration["accounts"]["createTransaction"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new MercuryIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.accounts.createTransaction(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_mercury import MercuryIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = MercuryIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.accounts.create_transaction(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.accountId | string | Required within parent | ID for a Mercury account. Format: uuid |
body | Model | Optional | Expand Send money to a recipient — request body — body |
Referenced models: Send money to a recipient — request body — body
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Get transaction by ID — response body |
Referenced models: Get transaction by ID — response body
Schemas
Section titled “Schemas”27 more schemas are linked from the tables above, on the schema pages.
Send money to a recipient — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
amount | JSON | Required within parent | Amount of USD you want to send, must be a positive number. |
amount (allOf 1) | number | All variants apply | A positive dollar amount with at least 1 cent. Format: double Minimum: 0.01 |
duplicateCheckOverride | boolean | Optional | Set to true to skip the duplicate payment check. By default, payments are blocked if the same account sent the same amount to the same recipient with the same payment method in the last 24 hours, even when the idempotency key is different. Use this field only when you intentionally send a repeat payment. |
externalMemo | string | Optional | Optional external memo Maximum length: 299 |
idempotencyKey | string | Required within parent | Unique string identifying the transaction |
note | string | Optional | Optional note |
paymentMethod | JSON | Required within parent | If domesticWire is used, then the purpose field is required. |
paymentMethod (allOf 1) | string | All variants apply | One of: ach, check, domesticWire, realTimePayment |
purpose | JSON | Optional | Purpose of payment with category and optional additional info. Required when paymentMethod is 'domesticWire'. |
purpose (allOf 1) | Model | All variants apply | Expand Request to send money — request body — body purpose External API representation of Send Money Purpose |
recipientId | JSON | Required within parent | Recipient ID from the /recipients endpoint. |
recipientId (allOf 1) | string | All variants apply | ID for a Mercury account. Format: uuid |
Referenced models: Request to send money — request body — body purpose External API representation of Send Money Purpose
Get a card — response body — category Locks item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | string | Root | Known values: Other, Advertising, Airlines, AlcoholAndBars, BooksAndNewspaper, CarRental, Charity, Clothing, Conferences, Education, Electronics, Entertainment, FacilitiesExpenses, Fees, FoodDelivery, FuelAndGas, Gambling, GovernmentServices, Grocery, GroundTransportation, Insurance, InternetAndTelephone, Legal, Lodging, Medical, Memberships, OfficeSupplies, OtherTravel, Parking, Political, ProfessionalServices, Restaurants, Retail, RideshareAndTaxis, Shipping, Software, Taxes, Utilities, VehicleExpenses |
Edit a category — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Represents an expense category for transaction classification. |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | ID for the category Format: uuid |
id (allOf 2) | JSON | All variants apply | The ID of the category |
name | string | Required within parent | The name of the category |
visibleForCardSpend | boolean | Required within parent | Whether this category is applicable to card transactions |
visibleForOther | boolean | Required within parent | Whether this category is applicable to all other transaction kinds |
visibleForReimbursements | boolean | Required within parent | Whether this category is applicable to expense reimbursement transactions |
Get transaction by ID — response body — currency Exchange Info converted From Amount, converted From Currency, converted To Amount, converted To Currency, exchange Rate, fee Amount, fee Percentage, fee Transaction Id converted From Amount, converted From Currency, converted To Amount, converted To Currency, exchange Rate, fee Amount, fee Percentage, fee Transaction Id
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
convertedFromAmount | JSON | Required within parent | |
convertedFromAmount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
convertedFromAmount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
convertedFromCurrency | JSON | Required within parent | |
convertedFromCurrency (allOf 1) | string | All variants apply | |
convertedToAmount | JSON | Required within parent | |
convertedToAmount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
convertedToAmount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
convertedToCurrency | JSON | Required within parent | |
convertedToCurrency (allOf 1) | string | All variants apply | |
exchangeRate | JSON | Required within parent | |
exchangeRate (anyOf 1) | number | Alternative | Exchange rate goes from "from currency" to "to currency" (ie from currency * exchange rate = to currency) Multiple of: 0.0001 |
exchangeRate (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
feeAmount | JSON | Required within parent | |
feeAmount (anyOf 1) | number | Alternative | Multiple of: 0.01 |
feeAmount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
feePercentage | JSON | Required within parent | |
feePercentage (anyOf 1) | number | Alternative | Multiple of: 0.0001 |
feePercentage (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
feeTransactionId | JSON | Optional | |
feeTransactionId (anyOf 1) | JSON | Alternative | |
feeTransactionId (anyOf 1) (allOf 1) | string | All variants apply | ID for this transaction Format: uuid |
feeTransactionId (anyOf 2) | null | Alternative |
Get transaction by ID — response body — gl Allocations item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A GL code allocation on a transaction — a GL code name paired with the amount allocated to it. When a transaction is fully categorized, the amounts across all allocations sum to the transaction total. |
amount | JSON | Required within parent | |
amount (anyOf 1) | number | Alternative | The amount allocated to this GL code Multiple of: 0.01 |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
className | JSON | Optional | |
className (anyOf 1) | string | Alternative | The name of the class from the connected accounting integration, if assigned |
className (anyOf 2) | null | Alternative | |
departmentName | JSON | Optional | |
departmentName (anyOf 1) | string | Alternative | The name of the department from the connected accounting integration, if assigned |
departmentName (anyOf 2) | null | Alternative | |
description | JSON | Optional | |
description (anyOf 1) | string | Alternative | Optional user-provided description for this allocation |
description (anyOf 2) | null | Alternative | |
glCodeName | string | Required within parent | The name of the GL code from the connected accounting integration |
Get transaction by ID — response body — merchant amount, category, category Code, currency, id Merchant information for card transactions
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Merchant information for card transactions |
amount | JSON | Optional | |
amount (anyOf 1) | JSON | Alternative | |
amount (anyOf 1) (anyOf 1) | integer | Alternative | The transaction amount in the smallest unit of the merchant's currency (e.g., cents for USD/EUR, yen for JPY, fils for BHD). For debits this is negative, for credits positive. Use 'merchantCurrency' to determine the appropriate decimal scaling: most currencies use 2 decimal places (divide by 100), but JPY uses 0 (no division needed) and BHD/KWD/OMR use 3 (divide by 1000). This is useful for international transactions where the merchant charges in a currency different from the account currency. Nothing if not available. Format: int64 Maximum: 9223372036854776000 Minimum: -9223372036854776000 |
amount (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
amount (anyOf 2) | null | Alternative | |
category | JSON | Optional | |
category (anyOf 1) | JSON | Alternative | |
category (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get a card — response body — category Locks item |
category (anyOf 1) (allOf 2) | JSON | All variants apply | Mercury category for the merchant (e.g., "Restaurants", "Software") |
category (anyOf 2) | null | Alternative | |
categoryCode | JSON | Optional | |
categoryCode (anyOf 1) | string | Alternative | 4-digit merchant category code (MCC) for card transactions |
categoryCode (anyOf 2) | null | Alternative | |
currency | JSON | Optional | |
currency (anyOf 1) | JSON | Alternative | |
currency (anyOf 1) (allOf 1) | string | All variants apply | |
currency (anyOf 1) (allOf 2) | JSON | All variants apply | ISO 4217 currency code of the merchant's currency (e.g., "EUR", "GBP", "JPY"). Nothing if not available. |
currency (anyOf 2) | null | Alternative | |
id | JSON | Optional | |
id (anyOf 1) | string | Alternative | Merchant ID for card transactions |
id (anyOf 2) | null | Alternative |
Referenced models: Get a card — response body — category Locks item
Get transaction by ID — response body — attachments item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
attachmentType | JSON | Required within parent | |
attachmentType (allOf 1) | string | All variants apply | Known values: checkImage, receipt, other |
fileName | string | Required within parent | |
url | string | Required within parent |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: mercury.createtransaction. Catalog operation: mercury:createTransaction. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.