Wallet to Wallet Transfer

A wallet to wallet transfer moves funds directly between two customers' wallets within the same partner account. It uses TransactionMethod: ZumTransfer and ZumRailsType: WalletTransfer.

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.

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

Payload

{
  "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"
} 

Response

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