Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.accountIdstringRequired within parentID for a Mercury account.
Format: uuid
bodyModelOptionalExpand Send money to a recipient — request body — body

Referenced models: Send money to a recipient — request body — body

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Get transaction by ID — response body

Referenced models: Get transaction by ID — response body

27 more schemas are linked from the tables above, on the schema pages.

Send money to a recipient — request body — body
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
amountJSONRequired within parentAmount of USD you want to send, must be a positive number.
amount (allOf 1)numberAll variants applyA positive dollar amount with at least 1 cent.
Format: double
Minimum: 0.01
duplicateCheckOverridebooleanOptionalSet 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.
externalMemostringOptionalOptional external memo
Maximum length: 299
idempotencyKeystringRequired within parentUnique string identifying the transaction
notestringOptionalOptional note
paymentMethodJSONRequired within parentIf domesticWire is used, then the purpose field is required.
paymentMethod (allOf 1)stringAll variants applyOne of: ach, check, domesticWire, realTimePayment
purposeJSONOptionalPurpose of payment with category and optional additional info. Required when paymentMethod is 'domesticWire'.
purpose (allOf 1)ModelAll variants applyExpand Request to send money — request body — body purpose External API representation of Send Money Purpose
recipientIdJSONRequired within parentRecipient ID from the /recipients endpoint.
recipientId (allOf 1)stringAll variants applyID 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
FieldTypePresenceDescription and constraints
$stringRootKnown 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
FieldTypePresenceDescription and constraints
$objectRootRepresents an expense category for transaction classification.
idJSONRequired within parent
id (allOf 1)stringAll variants applyID for the category
Format: uuid
id (allOf 2)JSONAll variants applyThe ID of the category
namestringRequired within parentThe name of the category
visibleForCardSpendbooleanRequired within parentWhether this category is applicable to card transactions
visibleForOtherbooleanRequired within parentWhether this category is applicable to all other transaction kinds
visibleForReimbursementsbooleanRequired within parentWhether 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
FieldTypePresenceDescription and constraints
$objectRoot
convertedFromAmountJSONRequired within parent
convertedFromAmount (anyOf 1)numberAlternativeMultiple of: 0.01
convertedFromAmount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
convertedFromCurrencyJSONRequired within parent
convertedFromCurrency (allOf 1)stringAll variants apply
convertedToAmountJSONRequired within parent
convertedToAmount (anyOf 1)numberAlternativeMultiple of: 0.01
convertedToAmount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
convertedToCurrencyJSONRequired within parent
convertedToCurrency (allOf 1)stringAll variants apply
exchangeRateJSONRequired within parent
exchangeRate (anyOf 1)numberAlternativeExchange rate goes from "from currency" to "to currency"
(ie from currency * exchange rate = to currency)
Multiple of: 0.0001
exchangeRate (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
feeAmountJSONRequired within parent
feeAmount (anyOf 1)numberAlternativeMultiple of: 0.01
feeAmount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
feePercentageJSONRequired within parent
feePercentage (anyOf 1)numberAlternativeMultiple of: 0.0001
feePercentage (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
feeTransactionIdJSONOptional
feeTransactionId (anyOf 1)JSONAlternative
feeTransactionId (anyOf 1) (allOf 1)stringAll variants applyID for this transaction
Format: uuid
feeTransactionId (anyOf 2)nullAlternative
Get transaction by ID — response body — gl Allocations item
FieldTypePresenceDescription and constraints
$objectRootA 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.
amountJSONRequired within parent
amount (anyOf 1)numberAlternativeThe amount allocated to this GL code
Multiple of: 0.01
amount (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
classNameJSONOptional
className (anyOf 1)stringAlternativeThe name of the class from the connected accounting integration, if assigned
className (anyOf 2)nullAlternative
departmentNameJSONOptional
departmentName (anyOf 1)stringAlternativeThe name of the department from the connected accounting integration, if assigned
departmentName (anyOf 2)nullAlternative
descriptionJSONOptional
description (anyOf 1)stringAlternativeOptional user-provided description for this allocation
description (anyOf 2)nullAlternative
glCodeNamestringRequired within parentThe 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
FieldTypePresenceDescription and constraints
$objectRootMerchant information for card transactions
amountJSONOptional
amount (anyOf 1)JSONAlternative
amount (anyOf 1) (anyOf 1)integerAlternativeThe 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)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
amount (anyOf 2)nullAlternative
categoryJSONOptional
category (anyOf 1)JSONAlternative
category (anyOf 1) (allOf 1)ModelAll variants applyExpand Get a card — response body — category Locks item
category (anyOf 1) (allOf 2)JSONAll variants applyMercury category for the merchant (e.g., "Restaurants", "Software")
category (anyOf 2)nullAlternative
categoryCodeJSONOptional
categoryCode (anyOf 1)stringAlternative4-digit merchant category code (MCC) for card transactions
categoryCode (anyOf 2)nullAlternative
currencyJSONOptional
currency (anyOf 1)JSONAlternative
currency (anyOf 1) (allOf 1)stringAll variants apply
currency (anyOf 1) (allOf 2)JSONAll variants applyISO 4217 currency code of the merchant's currency (e.g., "EUR", "GBP", "JPY").
Nothing if not available.
currency (anyOf 2)nullAlternative
idJSONOptional
id (anyOf 1)stringAlternativeMerchant ID for card transactions
id (anyOf 2)nullAlternative

Referenced models: Get a card — response body — category Locks item

Get transaction by ID — response body — attachments item
FieldTypePresenceDescription and constraints
$objectRoot
attachmentTypeJSONRequired within parent
attachmentType (allOf 1)stringAll variants applyKnown values: checkImage, receipt, other
fileNamestringRequired within parent
urlstringRequired within parent

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.

Official provider source

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.