--- title: "Create an internal transfer" method: POST path: "/transfer" tags: ["Accounts"] --- # Create an internal transfer `POST /transfer` Transfer funds between two accounts within the same organization. Supports transfers between depository accounts (checking/savings), from a depository account to a treasury/investment account, and from a treasury/investment account to a depository account. Creates paired debit and credit transactions. ## Request body - InternalTransferAPIRequest — Request body for POST /api/v1/transfer endpoint. Transfers funds between two depository, treasury, or investment accounts belonging to the same organization. - `amount` number, double, required — A positive dollar amount with at least 1 cent. - `destinationAccountId` string, uuid, required — ID for a Mercury account. - `idempotencyKey` string, required - `note` string, nullable - `sourceAccountId` string, uuid, required — ID for a Mercury account. ## Response `200` - InternalTransferAPIResponse — Response for POST /api/v1/transfer endpoint. Returns both the credit and debit transactions for the transfer (depository, treasury, or investment). - `creditTransaction` Transaction, required - `accountId` string, uuid, required — The external-facing account identifier for the Mercury account that owns this transaction - `amount` number, required - `attachments` TransactionAttachment[], required - `attachmentType` 'checkImage' | 'receipt' | 'other', required - `fileName` string, required - `url` string, required - `bankDescription` string, nullable - `categoryData` CategoryData — Represents an expense category for transaction classification. - `id` string, uuid, required — The ID of the category - `name` string, required — The name of the category - `visibleForCardSpend` boolean, required — Whether this category is applicable to card transactions - `visibleForOther` boolean, required — Whether this category is applicable to all other transaction kinds - `visibleForReimbursements` boolean, required — Whether this category is applicable to expense reimbursement transactions - `checkNumber` string, nullable — Present for check deposits and mailed checks; Nothing otherwise. - `compliantWithReceiptPolicy` boolean, required - `counterpartyId` string, uuid, required — ID for a Mercury account. - `counterpartyName` string, required - `counterpartyNickname` string, nullable - `createdAt` string, yyyy-mm-ddThh:MM:ssZ, required - `creditAccountPeriodId` string, uuid — ID for the credit statement period - `currencyExchangeInfo` CurrencyExchangeInfo - `convertedFromAmount` number, required - `convertedFromCurrency` string, required - `convertedToAmount` number, required - `convertedToCurrency` string, required - `exchangeRate` number, required — Exchange rate goes from "from currency" to "to currency" (ie from currency * exchange rate = to currency) - `feeAmount` number, required - `feePercentage` number, required - `feeTransactionId` string, uuid — ID for this transaction - `dashboardLink` string, required - `details` TransactionMethodData - `address` AddressData - `address1` string, required - `address2` string, nullable - `city` string, required - `postalCode` string, required - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' - `creditCardInfo` CreditCardInfo - `email` string, nullable - `id` string, uuid, required - `paymentMethod` string, required - `debitCardInfo` DebitCardInfo - `id` string, uuid, required - `domesticWireRoutingInfo` DomesticWireRoutingInfo - `accountNumber` string, required - `address` AddressWithoutName - `address1` string, required - `address2` string, nullable - `city` string, required - `country` string, required - `postalCode` string, required - `region` string, required - `bankName` string, nullable - `routingNumber` string, required - `electronicRoutingInfo` ElectronicRoutingInfo - `accountNumber` string, required - `address` AddressWithoutName - `address1` string, required - `address2` string, nullable - `city` string, required - `country` string, required - `postalCode` string, required - `region` string, required - `bankName` string, nullable - `electronicAccountType` 'businessChecking' | 'businessSavings' | 'personalChecking' | 'personalSavings', required - `routingNumber` string, required - `internationalWireRoutingInfo` InternationalWireRoutingInfo - `address` AddressWithoutName - `address1` string, required - `address2` string, nullable - `city` string, required - `country` string, required - `postalCode` string, required - `region` string, required - `bankDetails` SwiftCodeData - `bankCityState` string, required - `bankCountry` string, required - `bankName` string, required - `correspondentInfo` InternationalWireCorrespondentInfo - `bankName` string, nullable - `routingNumber` string, nullable - `swiftCode` string, nullable - `countrySpecific` InternationalWireCountrySpecificData, required - `australia` InternationalWireAustraliaSpecificData - `bsbCode` string, required - `brazil` InternationalWireBrazilSpecificData - `legalId` string, required - `canada` InternationalWireCanadaSpecificData - `bankCode` string, required - `transitNumber` string, required - `chile` InternationalWireChileSpecificData - `legalId` string, required - `colombia` InternationalWireColombiaSpecificData - `legalId` string, required - `dominicanRepublic` InternationalWireDominicanRepublicSpecificData - `accountType` 'checking' | 'savings', required - `legalId` string, required - `honduras` InternationalWireHondurasSpecificData - `accountType` 'checking' | 'savings', required - `legalId` string, required - `india` InternationalWireIndiaSpecificData - `ifscCode` string, required - `kazakhstan` InternationalWireKazakhstanSpecificData - `legalId` string, required - `pakistan` InternationalWirePakistanSpecificData - `legalId` string, required - `legalIdType` 'CNIC' | 'SNIC' | 'Passport' | 'NTN', required - `paraguay` InternationalWireParaguaySpecificData - `legalId` string, required - `philippines` InternationalWirePhilippinesSpecificData - `routingNumber` string, required - `russia` InternationalWireRussiaSpecificData - `inn` string, required - `southAfrica` InternationalWireSouthAfricaSpecificData - `branchCode` string, required - `emailAddress` string, nullable - `iban` string, required - `phoneNumber` string, nullable - `swiftCode` string, required - `estimatedDeliveryDate` string, yyyy-mm-ddThh:MM:ssZ, required - `externalMemo` string, nullable - `failedAt` string, yyyy-mm-ddThh:MM:ssZ - `feeId` string, uuid — ID for this transaction - `generalLedgerCodeName` string, nullable — Deprecated: use transactionGlAllocations instead. This field does not reflect GL codes assigned via Mercury auto-categorization rules. Preserved for backwards compatibility. - `glAllocations` GlAllocation[], required — GL code allocations assigned to this transaction via a connected accounting software integration (e.g. QuickBooks, Xero, NetSuite). Each allocation has a GL code name and the amount allocated to it; amounts sum to the transaction total when the transaction is fully categorized. Empty if no GL codes have been assigned. Distinct from Mercury custom categories (see transactionCategoryData). - `amount` number, required — The amount allocated to this GL code - `description` string, nullable — Optional user-provided description for this allocation - `glCodeName` string, required — The name of the GL code from the connected accounting integration - `hasGeneratedReceipt` boolean, required - `id` string, uuid, required — ID for this transaction - `kind` 'externalTransfer' | 'internalTransfer' | 'outgoingPayment' | 'creditCardCredit' | 'creditCardTransaction' | 'debitCardCredit' | 'debitCardTransaction' | 'cardInternationalTransactionFee' | 'cardInternationalTransactionFeeRebate' | 'cardInternationalTransactionFeeReversal' | 'cardInternationalTransactionFeeRebateReversal' | 'incomingDomesticWire' | 'checkDeposit' | 'incomingInternationalWire' | 'treasuryTransfer' | 'currencyCloudReturn' | 'wireFee' | 'personalBankingSubscriptionFee' | 'billingEngineSubscriptionFee' | 'expenseReimbursement' | 'exogenousWireDrawdown' | 'interestPayment' | 'other', required - `merchant` object, nullable — Merchant information for card transactions, including the merchant category code (MCC), merchant ID, Mercury category, and for international transactions, the amount and currency in the merchant's local currency. Nothing for non-card transactions. - `amount` integer, nullable — 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. - `category` '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', nullable — Mercury category for the merchant (e.g., "Restaurants", "Software") - `categoryCode` string, nullable — 4-digit merchant category code (MCC) for card transactions - `currency` string, nullable — ISO 4217 currency code of the merchant's currency (e.g., "EUR", "GBP", "JPY"). Nothing if not available. - `id` string, nullable — Merchant ID for card transactions - `mercuryCategory` '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' - `note` string, nullable - `postedAt` string, yyyy-mm-ddThh:MM:ssZ - `reasonForFailure` string, nullable - `relatedTransactions` RelatedTransactionData[], required - `accountId` string, uuid, required — ID for a Mercury account. - `amount` number, required - `id` string, uuid, required — ID for this transaction - `relationKind` 'ProvisionalCreditReversalToMerchantRefund' | 'MerchantRefundToProvisionalCreditReversal' | 'MerchantRefundToFraudulentCharge' | 'FraudulentChargeToMerchantRefund' | 'PaymentRefundToFailedPayment' | 'FailedPaymentToPaymentRefund' | 'GiftCompensationToOriginalTransaction' | 'FeePaymentToOriginalTransaction' | 'OriginalTransactionToFeePayment' | 'FeePaymentToFeeRebate' | 'FeeRebateToFeePayment' | 'FeePaymentToFeeReversal' | 'FeeReversalToFeePayment' | 'FeeRebateToFeeRebateReversal' | 'FeeRebateReversalToFeeRebate' | 'TreasurySplitLiquidation' | 'ProvisionalCreditToOriginalCharge' | 'OriginalChargeToProvisionalCredit' | 'FeeAtmReimbursementToAtmTransaction' | 'AtmTransactionToFeeAtmReimbursement' | 'AtmTransactionToAtmReimbursementReversal' | 'AtmReimbursementReversalToAtmTransaction' | 'ReturnToOriginalTransaction' | 'OriginalTransactionToReturn' | 'ProvisionalCreditToReversal' | 'ReversalToProvisionalCredit' | 'MerchantRefundToOriginalCharge' | 'OriginalChargeToMerchantRefund', required - `requestId` string, nullable - `status` 'pending' | 'sent' | 'cancelled' | 'failed' | 'reversed' | 'blocked', required - `trackingNumber` string, nullable — Present for transactions that have tracking numbers (e.g., RTP, ACH, wires); Nothing otherwise. - `debitTransaction` Transaction, required - `accountId` string, uuid, required — The external-facing account identifier for the Mercury account that owns this transaction - `amount` number, required - `attachments` TransactionAttachment[], required - `attachmentType` 'checkImage' | 'receipt' | 'other', required - `fileName` string, required - `url` string, required - `bankDescription` string, nullable - `categoryData` CategoryData — Represents an expense category for transaction classification. - `id` string, uuid, required — The ID of the category - `name` string, required — The name of the category - `visibleForCardSpend` boolean, required — Whether this category is applicable to card transactions - `visibleForOther` boolean, required — Whether this category is applicable to all other transaction kinds - `visibleForReimbursements` boolean, required — Whether this category is applicable to expense reimbursement transactions - `checkNumber` string, nullable — Present for check deposits and mailed checks; Nothing otherwise. - `compliantWithReceiptPolicy` boolean, required - `counterpartyId` string, uuid, required — ID for a Mercury account. - `counterpartyName` string, required - `counterpartyNickname` string, nullable - `createdAt` string, yyyy-mm-ddThh:MM:ssZ, required - `creditAccountPeriodId` string, uuid — ID for the credit statement period - `currencyExchangeInfo` CurrencyExchangeInfo - `convertedFromAmount` number, required - `convertedFromCurrency` string, required - `convertedToAmount` number, required - `convertedToCurrency` string, required - `exchangeRate` number, required — Exchange rate goes from "from currency" to "to currency" (ie from currency * exchange rate = to currency) - `feeAmount` number, required - `feePercentage` number, required - `feeTransactionId` string, uuid — ID for this transaction - `dashboardLink` string, required - `details` TransactionMethodData - `address` AddressData - `address1` string, required - `address2` string, nullable - `city` string, required - `postalCode` string, required - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' - `creditCardInfo` CreditCardInfo - `email` string, nullable - `id` string, uuid, required - `paymentMethod` string, required - `debitCardInfo` DebitCardInfo - `id` string, uuid, required - `domesticWireRoutingInfo` DomesticWireRoutingInfo - `accountNumber` string, required - `address` AddressWithoutName - `address1` string, required - `address2` string, nullable - `city` string, required - `country` string, required - `postalCode` string, required - `region` string, required - `bankName` string, nullable - `routingNumber` string, required - `electronicRoutingInfo` ElectronicRoutingInfo - `accountNumber` string, required - `address` AddressWithoutName - `address1` string, required - `address2` string, nullable - `city` string, required - `country` string, required - `postalCode` string, required - `region` string, required - `bankName` string, nullable - `electronicAccountType` 'businessChecking' | 'businessSavings' | 'personalChecking' | 'personalSavings', required - `routingNumber` string, required - `internationalWireRoutingInfo` InternationalWireRoutingInfo - `address` AddressWithoutName - `address1` string, required - `address2` string, nullable - `city` string, required - `country` string, required - `postalCode` string, required - `region` string, required - `bankDetails` SwiftCodeData - `bankCityState` string, required - `bankCountry` string, required - `bankName` string, required - `correspondentInfo` InternationalWireCorrespondentInfo - `bankName` string, nullable - `routingNumber` string, nullable - `swiftCode` string, nullable - `countrySpecific` InternationalWireCountrySpecificData, required - `australia` InternationalWireAustraliaSpecificData - `bsbCode` string, required - `brazil` InternationalWireBrazilSpecificData - `legalId` string, required - `canada` InternationalWireCanadaSpecificData - `bankCode` string, required - `transitNumber` string, required - `chile` InternationalWireChileSpecificData - `legalId` string, required - `colombia` InternationalWireColombiaSpecificData - `legalId` string, required - `dominicanRepublic` InternationalWireDominicanRepublicSpecificData - `accountType` 'checking' | 'savings', required - `legalId` string, required - `honduras` InternationalWireHondurasSpecificData - `accountType` 'checking' | 'savings', required - `legalId` string, required - `india` InternationalWireIndiaSpecificData - `ifscCode` string, required - `kazakhstan` InternationalWireKazakhstanSpecificData - `legalId` string, required - `pakistan` InternationalWirePakistanSpecificData - `legalId` string, required - `legalIdType` 'CNIC' | 'SNIC' | 'Passport' | 'NTN', required - `paraguay` InternationalWireParaguaySpecificData - `legalId` string, required - `philippines` InternationalWirePhilippinesSpecificData - `routingNumber` string, required - `russia` InternationalWireRussiaSpecificData - `inn` string, required - `southAfrica` InternationalWireSouthAfricaSpecificData - `branchCode` string, required - `emailAddress` string, nullable - `iban` string, required - `phoneNumber` string, nullable - `swiftCode` string, required - `estimatedDeliveryDate` string, yyyy-mm-ddThh:MM:ssZ, required - `externalMemo` string, nullable - `failedAt` string, yyyy-mm-ddThh:MM:ssZ - `feeId` string, uuid — ID for this transaction - `generalLedgerCodeName` string, nullable — Deprecated: use transactionGlAllocations instead. This field does not reflect GL codes assigned via Mercury auto-categorization rules. Preserved for backwards compatibility. - `glAllocations` GlAllocation[], required — GL code allocations assigned to this transaction via a connected accounting software integration (e.g. QuickBooks, Xero, NetSuite). Each allocation has a GL code name and the amount allocated to it; amounts sum to the transaction total when the transaction is fully categorized. Empty if no GL codes have been assigned. Distinct from Mercury custom categories (see transactionCategoryData). - `amount` number, required — The amount allocated to this GL code - `description` string, nullable — Optional user-provided description for this allocation - `glCodeName` string, required — The name of the GL code from the connected accounting integration - `hasGeneratedReceipt` boolean, required - `id` string, uuid, required — ID for this transaction - `kind` 'externalTransfer' | 'internalTransfer' | 'outgoingPayment' | 'creditCardCredit' | 'creditCardTransaction' | 'debitCardCredit' | 'debitCardTransaction' | 'cardInternationalTransactionFee' | 'cardInternationalTransactionFeeRebate' | 'cardInternationalTransactionFeeReversal' | 'cardInternationalTransactionFeeRebateReversal' | 'incomingDomesticWire' | 'checkDeposit' | 'incomingInternationalWire' | 'treasuryTransfer' | 'currencyCloudReturn' | 'wireFee' | 'personalBankingSubscriptionFee' | 'billingEngineSubscriptionFee' | 'expenseReimbursement' | 'exogenousWireDrawdown' | 'interestPayment' | 'other', required - `merchant` object, nullable — Merchant information for card transactions, including the merchant category code (MCC), merchant ID, Mercury category, and for international transactions, the amount and currency in the merchant's local currency. Nothing for non-card transactions. - `amount` integer, nullable — 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. - `category` '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', nullable — Mercury category for the merchant (e.g., "Restaurants", "Software") - `categoryCode` string, nullable — 4-digit merchant category code (MCC) for card transactions - `currency` string, nullable — ISO 4217 currency code of the merchant's currency (e.g., "EUR", "GBP", "JPY"). Nothing if not available. - `id` string, nullable — Merchant ID for card transactions - `mercuryCategory` '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' - `note` string, nullable - `postedAt` string, yyyy-mm-ddThh:MM:ssZ - `reasonForFailure` string, nullable - `relatedTransactions` RelatedTransactionData[], required - `accountId` string, uuid, required — ID for a Mercury account. - `amount` number, required - `id` string, uuid, required — ID for this transaction - `relationKind` 'ProvisionalCreditReversalToMerchantRefund' | 'MerchantRefundToProvisionalCreditReversal' | 'MerchantRefundToFraudulentCharge' | 'FraudulentChargeToMerchantRefund' | 'PaymentRefundToFailedPayment' | 'FailedPaymentToPaymentRefund' | 'GiftCompensationToOriginalTransaction' | 'FeePaymentToOriginalTransaction' | 'OriginalTransactionToFeePayment' | 'FeePaymentToFeeRebate' | 'FeeRebateToFeePayment' | 'FeePaymentToFeeReversal' | 'FeeReversalToFeePayment' | 'FeeRebateToFeeRebateReversal' | 'FeeRebateReversalToFeeRebate' | 'TreasurySplitLiquidation' | 'ProvisionalCreditToOriginalCharge' | 'OriginalChargeToProvisionalCredit' | 'FeeAtmReimbursementToAtmTransaction' | 'AtmTransactionToFeeAtmReimbursement' | 'AtmTransactionToAtmReimbursementReversal' | 'AtmReimbursementReversalToAtmTransaction' | 'ReturnToOriginalTransaction' | 'OriginalTransactionToReturn' | 'ProvisionalCreditToReversal' | 'ReversalToProvisionalCredit' | 'MerchantRefundToOriginalCharge' | 'OriginalChargeToMerchantRefund', required - `requestId` string, nullable - `status` 'pending' | 'sent' | 'cancelled' | 'failed' | 'reversed' | 'blocked', required - `trackingNumber` string, nullable — Present for transactions that have tracking numbers (e.g., RTP, ACH, wires); Nothing otherwise. ## Other responses - `400` — Invalid `body` --- [API](https://skmtc.net/mercurytechnologies/apis/mercury-api.md) · [All operations](https://skmtc.net/mercurytechnologies/apis/mercury-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mercurytechnologies/mercury-api/versions/0bdf4a496e03/schema)