--- 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' | 'other', required - `merchant` object, nullable — Merchant information for card transactions; Nothing for non-card transactions - `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 - `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', 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' | 'other', required - `merchant` object, nullable — Merchant information for card transactions; Nothing for non-card transactions - `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 - `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', 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` ## Changes - **2026-04-23** `3e266f593eb1` — 6 info - added the required property `creditTransaction/allOf[#/components/schemas/Transaction]/categoryData/allOf[#/components/schemas/CategoryData]/visibleForCardSpend` to the response with the `200` status - added the required property `creditTransaction/allOf[#/components/schemas/Transaction]/categoryData/allOf[#/components/schemas/CategoryData]/visibleForOther` to the response with the `200` status - added the required property `creditTransaction/allOf[#/components/schemas/Transaction]/categoryData/allOf[#/components/schemas/CategoryData]/visibleForReimbursements` to the response with the `200` status - added the required property `debitTransaction/allOf[#/components/schemas/Transaction]/categoryData/allOf[#/components/schemas/CategoryData]/visibleForCardSpend` to the response with the `200` status - …2 more [Change history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/transfer/post.md) --- [API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) · [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mercurytechnologies/mercury-api/revisions/314f542b4d39/schema)