> For the complete documentation index, see [llms.txt](https://docs.zumrails.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zumrails.com/api-reference/wallet-to-wallet-transfer.md). # Wallet to Wallet Transfer A wallet to wallet transfer moves funds directly between two customers' [wallets](/payments/introduction.md#zum-wallet) within the same partner account. It uses `TransactionMethod: ZumTransfer` and `ZumRailsType: WalletTransfer`. {% hint style="info" %} **Note:** Wallet to wallet transfers can only be created by a **partner** — either through the API or the Portal. Customers cannot initiate this transaction type directly. {% endhint %} ### Prerequisites Before initiating a wallet to wallet transfer: * Both the source and target customers must exist and belong to **your partner account**. * ZumTransfer must be **enabled on both customers**. The `Enable common ownership wallet-transfers` feature flag must be enabled on both customer. Zum Rails' support team can help with this prerequisite. * Both customers must be in the **same region** (both in Canada, or both in the USA). `Method: POST` `Endpoint: {{env}}/api/transaction` {% tabs %} {% tab title="Payload" %} ```json { "TransactionMethod": "ZumTransfer", "ZumRailsType": "WalletTransfer", "SourceCustomerId": "1d431e8b-...85452adb4eee", "TargetCustomerId": "8ebd932b-...b92633e14297", "Amount": 250.00, "Memo": "Memo description", "Comment": "This transaction is just a wallet to wallet test" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "Customer": { "IsBaasEnabled": true, "Id": "a07f2fdf-a05f-4a35-a2d1-68928ac24730", "CompanyName": "Partner Test" }, "InteracHasSecurityQuestionAndAnswer": false, "UseInteracANR": false, "InteracDebtorInstitutionName": "", "IsRefundable": false, "PaymentDetails": { "Type": "Wallet", "WalletId": "fb44f427-64b9-443b-8f2b-3be938dfa3f8" }, "Id": "50caad4f-371a-401f-b51d-b477c96b345a", "CreatedAt": "2026-06-23T03:41:13.962671Z", "Memo": "", "Comment": "Wallet transfer test", "Amount": 10, "ZumRailsType": "WalletTransfer", "TransactionMethod": "ZumTransfer", "TransactionHistory": [ { "Id": "221749b2-611c-46d0-9e8f-14e694c8563e", "CreatedAt": "2026-06-23T03:41:14.242964Z", "Event": "Started", "EventDescription": "Transaction with type WalletTransfer started, from Customer Jun222309 to Customer Jun222312 with amount: $10.00" }, { "Id": "e00e959d-6128-4b32-a1d2-ae082bbc637a", "CreatedAt": "2026-06-23T03:41:14.262306Z", "Event": "WalletWithdrawn", "EventDescription": "Wallet withdrawn, amount: $10.00 - Funds moved from wallet" }, { "Id": "5e1ab028-2559-464a-af84-56acebc20de8", "CreatedAt": "2026-06-23T03:41:14.271943Z", "Event": "WalletFunded", "EventDescription": "Wallet was funded, amount: $10.00 - Funds moved to wallet" }, { "Id": "bfcbfe0c-4506-41eb-b597-1ad4bad3be83", "CreatedAt": "2026-06-23T03:41:14.276292Z", "Event": "Succeeded", "EventDescription": "Transaction completed" } ], "SourceTransactionHistory": [], "TransactionFees": [], "TransactionStatus": "Completed", "From": "Customer A", "To": "Customer B", "CompletedAt": "2026-06-23T03:41:14.280394Z", "Currency": "USD", "SourceCustomerId": "da4b4f4d-2d68-418a-8b49-5fb4d843c38b", "TargetCustomerId": "b8a5f973-f376-4ffb-8369-c22d48daede6", "InteracNotificationChannel": "Email" } } ``` {% endtab %} {% endtabs %} ### Request | Field | Type | Required | Notes | | -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `TransactionMethod` | string | Yes | Must be `"ZumTransfer"` | | `ZumRailsType` | string | Yes | Must be `"WalletTransfer"` | | `SourceCustomerId` | GUID | Yes | The customer sending funds | | `TargetCustomerId` | GUID | Yes | The customer receiving funds. Cannot equal `SourceCustomerId` | | `Amount` | decimal | Yes | Minimum `0.01`. Maximum 2 decimal places | | `Memo` | string | No | Max 15 characters. Alphanumeric, spaces, hyphens, and underscores only | | `Comment` | string | No | Max 400 characters. | | `ScheduledStartDate` | date | No | Future date to defer execution. If omitted, the transfer is processed immediately. Cannot be combined with `IsRecurrent` | | `IsRecurrent` | boolean | No | Set to `true` to create a recurring transfer. Defaults to `false`. Cannot be combined with `ScheduledStartDate` | ### Currency Currency is **automatically derived from the source customer's country** — you cannot set it explicitly in the request. | Source customer region | Currency | | ---------------------- | -------- | | Canada | `CAD` | | USA | `USD` | ### Response A successful request returns a transaction object. The fields most relevant to wallet transfers are: | Field | Type | Notes | | -------------------- | -------- | ------------------------------------------- | | `Id` | GUID | Unique transaction identifier | | `TransactionStatus` | string | `"Completed"`, `"Scheduled"`, or `"Failed"` | | `Amount` | decimal | Transfer amount | | `Currency` | string | `"CAD"` or `"USD"` | | `SourceCustomerId` | string | Source customer GUID | | `TargetCustomerId` | string | Target customer GUID | | `Wallet` | object | Source wallet details | | `TargetWallet` | object | Target wallet details | | `CreatedAt` | datetime | When the transaction was created | | `CompletedAt` | datetime | When the transfer completed (if applicable) | | `FailedAt` | datetime | When the transfer failed (if applicable) | | `TransactionHistory` | array | Audit trail of status events | ### Error Reference | Scenario | Error | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `SourceCustomerId` or `TargetCustomerId` is missing | `"TargetCustomerId and SourceCustomerId are required."` | | `SourceCustomerId` and `TargetCustomerId` are the same | `"TargetCustomerId and SourceCustomerId cannot be the same."` | | Either customer ID does not exist | `"Could not locate customer {customerId}"` | | Either customer does not belong to your partner account | `"Cannot initiate wallet transfer. Please check the customer IDs"` | | ZumTransfer is not enabled on one or both customers | `"Transaction failed: transfer into the target wallet is not supported"` | | Customers are in different regions (e.g. one in Canada, one in the USA) | Transaction fails with event `ZumTransferFailedNotInTheSameRegion` | | Customers use different bank or providers | Transaction fails with event `ZumTransferFailedNotInTheSameBank` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.zumrails.com/api-reference/wallet-to-wallet-transfer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.