Transactions

Creating a new transaction

Use this endpoint if you want to add a new transaction.

Method: POST

Endpoint: {{env}}/api/transaction

Canada

{
  "ZumRailsType": "AccountsReceivable",
  "TransactionMethod": "Eft",
  "Amount": 123.45,
  "Memo": "Memo description",
  "Comment": "This transaction is just a test from a user to wallet",
  "UserId": "1d431e8b-...85452adb4eee",
  "WalletId": "8ebd932b-...b92633e14297"
}

US

{
  "ZumRailsType": "AccountsPayable",
  "TransactionMethod": "Ach",
  "Amount": 123.45,
  "Memo": "Memo",
  "Comment": "This transaction is just a test from a wallet to user",
  "UserId": "1d431e8b-...85452adb4eee",
  "WalletId": "8ebd932b-...b92633e14297",
  "PaymentInstrumentId": "92142401-...389ba0d87e75"
}

Input parameters

Parameter
Type
Mandatory
Description

ZumRailsType

string

yes

Transaction type

TransactionMethod

string

yes

Transaction method

Amount

decimal

yes

Transaction amount

Memo

string

yes

Memo description. If customer transaction description type is "PerTransaction", this will be shown at the bank statements. Maximum of 15 characters. Only letters, numbers, dash, space and underscore are allowed

Comment

string

no

Internal comment you might want to add. Interac transactions will display the comment on the request.

FundingSourceId

guid

no

Funding Source Id

WalletId

guid

no

Wallet Id

UserId

guid

no

User Id

User

no

It's possible to create a transaction without adding a user first. Simply pass the user object (instead of the UserId) into the transaction body. For reference, check the payload example of the user object here and pass this when you create a transaction (check interac transaction payload example). Only available for EFT and interac transaction methods

AuthCode

string

no

Processor clients can use this to securely send user information in the transaction creation API.

ScheduledStartDate

date

no

The date when the transaction will be sent to the financial institution, in the format YYYY-MM-DD. Must be greater than today.

ClientTransactionId

string

no

This field can be used to store the Transaction id created in your system when the Transaction is initiated

3D Secure

-

-

Only needed for 3D secure - Visa Direct and Credit Card

CardEci

string

no

Received from 3D secure, required if using 3D Secure but optional for Visa Direct Accounts Payable transactions

CardXid

string

no

Received from 3D secure, required if using 3D Secure but optional for Visa Direct Accounts Payable transactions

CardCavv

string

no

Received from 3D secure, required if using 3D Secure but optional for Visa Direct Accounts Payable transactions

Interac Fields

-

-

Only needed for Interac transactions

UseInteracANR

boolean

no

Indicates whether a transaction will be deposited directly to the user's saved account. (This works only for Interac account payable). Read more about Interac ANR here.

InteracHasSecurityQuestionAndAnswer

boolean

no

Indicate if there will be a question and answer for Interac

InteracSecurityQuestion

string

yes

The question for the user to process the interac request. Required if InteracHasSecurityQuestionAndAnswer is true. Pattern accepted: String [ 5 .. 40 ]. Characters accepted: a-zA-Z0-9àâäèéêëîïôœùûüÿçÀÂÄÈÉÊËÎÏÔŒÙÛÜŸÇ

InteracSecurityAnswer

string

yes

The answer for the user to process the interac request. Required if InteracHasSecurityQuestionAndAnswer is true. Pattern accepted: String [ 3 .. 25 ]. Characters accepted: a-zA-Z0-9àâäèéêëîïôœùûüÿçÀÂÄÈÉÊËÎÏÔŒÙÛÜŸÇ

SessionFingerprint

string

yes

A unique identifier for this sender, we recommend using fingerprintjs. Required if peer-to-peer Interac transactions are enabled.

SessionIpAddress

string

yes

The IP address of the UserId, the sender, of the funds. Required if Accounts Payable with Interac, and peer-to-peer enabled.

Authorize

-

no

Only needed for authorized hold Credit Card transactions

Capture

boolean

no

The field is required for authorized hold Credit Card transactions. Capture can be set to true or false

AutoExpireDays

number

no

The field is required for authorized hold Credit Card transactions. AutoExpireDays should be an number between 1 to 5.

  • For Interac transactions, either a memo or a comment is required. If both are provided, the comment will be shown in the Interac request.

  • When creating a transaction with a scheduled start date (delay transaction initiation), the transaction will be queued and sent to the financial institution based on the specified schedule.

INFO

For different use cases, Zūm Rails recommends the following workflows:

  • Accounts Payable (AP): Fund the Zūm Wallet in advance to ensure funds are available for timely disbursements.

  • Accounts Receivable (AR): Move funds from the end user into the Zūm Wallet, then configure an automatic daily withdrawal to your funding source at the end of each day.

Response

Parameter
Type
Description

Id

guid

Transaction id

ZumRailsType

Type
Description
Information to Provide

FundZumWallet

Send money from your Funding Source to Zūm Wallet

  • FundingSourceId

  • WalletId

WithdrawZumWallet

Withdraw money from Zūm Wallet to your Funding Source

  • FundingSourceId

  • WalletId

AccountsPayable

Send money (accounts payable) from your Zūm Wallet to a User

  • UserId

  • WalletId

AccountsPayable

Send money (accounts payable) from your Funding Source to a User

  • FundingSourceId

  • UserId

AccountsReceivable

Receive money (accounts receivable) from a User to your Zūm Wallet

  • UserId

  • WalletId

AccountsReceivable

Receive money (accounts receivable) from a User to your Funding Source

  • UserId

  • FundingSourceId

UnloadZumCard

Debit transaction to the zum wallet from a virtual card

  • UserId

  • WalletId

LoadZumCard

Credit transaction loading the virtual card from the zum wallet

  • UserId

  • WalletId

TransactionMethod

Type

Eft

Interac

VisaDirect

CreditCard

ZumCard

Keywords to simulate a transaction failure (Canada)

Eft
VisaDirect
Interac
CreditCard

EftFailedValidationRejection

VisaDirectGenericError

InteracFailedRecipientContactInfoMissing

CreditCardDeclined

EftFailedInsufficientFunds

VisaDirectDoNotHonor

InteracFailedInvalidEmailFormat

CreditCardError *

EftFailedCannotLocateAccount

VisaDirectInsufficientFunds

InteracFailedInvalidPhoneNumber

CreditCardHeldForReview *

EftFailedStopPayment

VisaDirectNotPermittedToCardHolderInformed

InteracFailedMultipleTransferLevelErrors

CreditCardGenericError *

EftFailedAccountClosed

VisaDirectAmountLimitNotAuthorized

InteracFailedRevoked

CreditCardUnknownResponse *

EftFailedNoDebitAllowed

VisaDirectRejectedAmlOrFraud

InteracFailedBulkCancellationRequest

CreditCardHoldCallOrPickUpCard *

EftFailedFundsNotFree

VisaDirectRejectedAccountLimitExceeded

InteracFailedRecipientRejected

CreditCardSecViolation *

EftFailedCurrencyAccountMismatch

VisaDirectReenterTransaction

InteracFailedAuthentication

CreditCardServNotAllowed *

EftFailedPayorPayeeDeceased

VisaDirectInvalidTransaction

InteracFailedReachedCancellationCutOff

CreditCardCvvMismatch *

EftFailedFrozenAccount

VisaDirectInvalidCardNumber

InteracFailedNotificationDeliveryFailure

CreditCardInvalidMerchantId *

EftFailedInvalidErrorAccountNumber

VisaDirectIssuerOrSwitchInoperative

InteracFailedAmountGreaterThanMax

CreditCardAmountExceeded *

EftFailedErrorPayorPayeeName

VisaDirectUnsupportedCardType

InteracFailedDebtorRejected

CreditCardRefundAmountExceeded *

EftFailedRefusedNoAgreement

VisaDirectInvalidExpiryDate

InteracFailedFundsDepositFailed

CreditCardCashbackNotApp *

EftFailedNotInAccountAgreementP

VisaDirectInvalidPIN

InteracFailedClientEmailedToRequestCancellation

CreditCardExpiredCard *

EftFailedNotInAccountAgreementE

VisaDirectInvalidSecret

InteracFailedGenericError

CreditCardNoAccountFound *

EftFailedAgreementRevoked

InteracFailedNameMismatch

CreditCardNotPermittedToCardHolderInformed *

EftFailedDefaultByAFinancialInstitution

InteracFailedInvalidAccountNumber

CreditCardInvalidCardNumber *

EftFailedTransactionNotAllowed

InteracFailedRequestBlockedByUser

CreditCardRejectedAmlOrFraud *

CreditCardTypeNotAccepted *

CreditCardDomesticDebitDeclined *

CreditCardClosedAccount *

* Not available for all Credit Card customers

NOTE

You can simulate late failures (after transaction completion) by using a comment: (event name), Latefailure. This feature is only available for EFT transaction error. If the string is incorrect, the transaction will fail with the event specified within it.

Get a specific transaction

Use this endpoint if you want to get all the information for a specific transaction. The transaction id is informed in the url.

Method: GET

Endpoint: {{env}}/api/transaction/{transaction_id}

{
  "statusCode": 200,
  "message": "GET Request successful.",
  "isError": false,
  "result": {
    "Id": "b7a8a505...364e8836404e",
    "CreatedAt": "2020-05-13T17:59:47.039462",
    "Memo": "Memo test",
    "Comment": "This is a transaction to test",
    "Amount": 123.45,
    "Customer": {
      "Id": "e15bbe9b...dc256ba3a247",
      "CompanyName": "Sam's Gym"
    },
    "User": {
      "Id": "c11cc378...8f34ac8173be",
      "FirstName": "John",
      "LastName": "111",
      "Email": "[email protected]",
      "IsActive": true
    },
    "Wallet": {
      "Id": "8ebd932b...b92633e14297",
      "Type": "Unified"
    },
    "FundingSource": {
      "Id": "1d431e8b...85452adb4eee",
      "Institution": "Institution",
      "InstitutionNumber": "123",
      "TransitNumber": "12345",
      "AccountNumber": "1234567"
    },
    "EventHistory": [
      {
        "CreatedAt": "2020-05-13T17:59:47.284943",
        "Event": "EFTFileUploaded",
        "EventDescription": "EFT file uploaded to Financial Institution"
      },
      {
        "CreatedAt": "2020-05-13T17:59:47.284943",
        "Event": "Started",
        "EventDescription": "Transaction with type FundZumWallet started, from Funding Source to Zūm Wallet with amount: $123.45"
      }
    ],
    "ZumRailsType": "FundZumWallet",
    "TransactionMethod": "Eft",
    "TransactionStatus": "InProgress",
    "RecurrentTransactionId": "16d2406f...87d397a8356f",
    "FailedTransactionEvent": null,
    "From": "Zūm Wallet",
    "To": "User john 111",
    "FailedAt": null,
    "IsRefundable": false,
    "AuthorizedHoldExpiredAt": ""
  }
}

Response

Parameter
Type
Description

Id

guid

Transaction id

CreatedAt

datetime

When the transaction was created

Memo

string

Transaction memo

Comment

string

Transaction comment

Amount

decimal

Transaction amount

ZumRailsType

string

Transaction type

TransactionStatus

string

Indicate the status of the transaction

RecurrentTransactionId

guid

The id of the recurrent transaction that created this transaction (null if inexistent)

FailedTransactionEvent

string

If the transaction has failed, the transaction event that caused it (null otherwise)

ScheduledStartDate

date

The date transaction will be sent to the financial institution.

ClientTransactionId

string

The Transaction id you informed in the creation of this transaction

InteracUrl

string

The interac URL to complete the transaction, if available

InteracDebtorInstitutionNumber

string

The Financial Institution used to complete the Interac Request money.

InteracDebtorFullName

string

The Full Name used to complete the Interac Request money. This information not yet 100% accurate, often is the same name sent. Gradually each Institution is improving and sending this information for Zūm Rails.

UseInteracANR

boolean

Indicates whether a transaction will be deposited directly to the user's saved account. (This works only for account payable transactions from wallet to user)

From

string

From description for the transaction

To

string

To description for the transaction

IsRefundable

boolean

Indicates if the transaction is IsRefundable

FailedAt

datetime

When the transaction was failed (null otherwise)

AuthorizedHoldExpiredAt

datetime

When the transaction was the authorized hold Credit Card transaction (null otherwise)

Customer

Basic Customer data

CompanyName

string

Company Name

Id

guid

Id for the related customer

User

If transaction has a user - * Not all information from a user is returned in this endpoint

Id

guid

The user id

First Name

string

User first name

Last Name

string

User last name

Company Name

string

User company name

IsActive

boolean

Indicates if the user is active or not

Wallet

If transaction has a wallet * Not all information from a user is returned in this endpoint

Id

guid

The wallet id

Type

string

The wallet type

FundingSource

If transaction has a funding source * Not all information from a user is returned in this endpoint

Id

guid

The funding source id

Institution

string

The institution name

InstitutionNumber

string

The institution number

TransitNumber

string

The transit number

AccountNumber

string

The account number

TargetWallet

If transaction has a target wallet

Id

guid

The target wallet id

Type

string

The target wallet type

TransactionHistory

List of transaction history events

CreatedAt

datetime

When the transaction event happened

Event

string

The event happened

EventDescription

string

The event description

Status and events

Zūm Rails offers 6 main statuses for transactions:

Transaction Status

Type
Description

InProgress

Indicates the transaction is being processed

Completed

Indicates the transaction is completed, this is a permanent status for Interac, Visa Direct and Credit Card. For EFT, a completed transaction might still fail up to 90 days after it's completion.

Failed

Indicates the transaction has failed, this is a permanent status.

Cancelled

Indicates the transaction has canceled, this is a permanent status.

Scheduled

Indicates the transaction is scheduled.

InReview

Indicates the transaction is under review. As of now, only Interac transactions uses this status. Once a transaction is "Under Review" you need to "Take Action" on the transaction from within the portal or via API implementation to guide Interac on how you want to treat this transaction. It could also happen that "Completed" transactions are flagged as "Under Review". This is when Interac requires a response from the Merchant stating if the transactions is legit/fraud/scam. Click here to read more. A transaction might be under review up to 7 days, after that our system will automatically cancel it.

Pending Cancellation

Indicates a cancellation request has been submitted for the transaction, but a response from the payment provider is still pending. This status applies to certain payment methods, such as Interac and ACH, where cancellations are not immediate and require provider confirmation.

Transaction Events

Zūm Rails also offers a more detailed transaction event, to indicate every step the transaction passed. Depending on the transaction methods, the events will change.

Method
Event
Description

All

Started

When the transaction started

All

Succeeded

When the transaction succeeds, when it finishes without any error

All

WalletFunded

When the transaction funds a wallet

All

WalletWithdrawn

When the transaction withdrawn a wallet

-------

-------

-------

Eft

EFTFileCreated

When an EFT file is created. One transaction might have up to 2 files

Eft

EFTFileUploaded

When an EFT file is uploaded

Eft

EFTAnswerReceived

When an EFT file response is received

Eft

EFTAnswerProcessed

When an EFT file is processed

Eft

EftFailedValidationRejection

When EFT could not be created, due an invalid information provided

Eft

EftFailedInsufficientFunds

When transaction is rejected, due non sufficient funds available

Eft

EftFailedCannotLocateAccount

When account is not located, account, transit or institution numbers are invalid

Eft

EftFailedStopPayment

Account do not allow EFT

Eft

EftFailedAccountClosed

When account is closed

Eft

EftFailedNoDebitAllowed

Account do not allow EFT

Eft

EftFailedFundsNotFree

When transaction is rejected, due non sufficient funds available

Eft

EftFailedCurrencyAccountMismatch

When the currency of the transaction does not match the currency of the account

Eft

EftFailedPayorPayeeDeceased

Account do not allow EFT

Eft

EftFailedFrozenAccount

Account do not allow EFT

Eft

EftFailedInvalidErrorAccountNumber

When account is not located, account numbers are invalid

Eft

EftFailedErrorPayorPayeeName

When account is not located, first, last or company name (business) mismatch

Eft

EftFailedRefusedNoAgreement

Account do not allow EFT

Eft

EftFailedNotInAccountAgreementP

Account do not allow EFT

Eft

EftFailedNotInAccountAgreementE

Account do not allow EFT

Eft

EftFailedAgreementRevoked

Account do not allow EFT

Eft

EftFailedDefaultByAFinancialInstitution

Generic error provided by the financial institution

Eft

EftFailedCustomerInitiatedReturnCreditOnly

When the payee has requested the credit to be returned

Eft

EftFailedTransactionNotAllowed

When the bank account is banned

Eft

EftFailedCustomerInitiatedReturnCreditOnly

When the payee has requested the credit to be returned

Eft

EftFailedNoPrenotificationP1

No Confirmation/Pre-Notification – Personal

Eft

EftFailedNoPrenotificationP2

No Confirmation/Pre-Notification – Business

Eft

EFTFileCreated

When the EFT file is created

Eft

EFTAnswerReceived

When the EFT answer is received

Eft

EFTAnswerProcessed

When the EFT answer is processed

Eft

NotEnoughBalanceInWalletError

When the wallet has not balance enough

-------

-------

-------

VisaDirect

VisaDirectGenericError

When a generic error happened in the network

VisaDirect

VisaDirectDoNotHonor

When the information provided was inconsistent, such as address or name on card

VisaDirect

VisaDirectInsufficientFunds

When not sufficient funds available in the card

VisaDirect

VisaDirectNotPermittedToCardHolderInformed

When the card holder did not authorize the transaction or the card is restricted for this usage

VisaDirect

VisaDirectAmountLimitNotAuthorized

When the limit informed invalid, too high or exceeds the withdrawal frequency limit, too many transactions for this card in the current period

VisaDirect

VisaDirectRejectedAmlOrFraud

When visa identified this transaction as AML or potential fraud

VisaDirect

VisaDirectWaitingSettlementIntoClientsAccounts

Waiting for funds to be settled into client's account

VisaDirect

VisaDirectSettledIntoClientsAccount

When visa funds are settled into client's account

VisaDirect

VisaDirectInvalidCardNumber

When the card has an invalid number

VisaDirect

VisaDirectChargeback

When the card number is invalid

VisaDirect

VisaDirectReenterTransaction

When an error happened. Retry creating the transaction

VisaDirect

VisaDirectInvalidTransaction

When transaction was considered invalid by visa direct

VisaDirect

VisaDirectIssuerOrSwitchInoperative

When issuer or switch is inoperative

VisaDirect

VisaDirectUnsupportedCardType

When a type card is not supported

VisaDirect

VisaDirectRejectedAccountLimitExceeded

When an account limit reaches the exceed amount

VisaDirect

VisaDirectInvalidExpiryDate

When a VisaDirect transaction due to invalid expiration dates

VisaDirect

VisaDirectInvalidPIN

When a VisaDirect transaction due to invalid pin

VisaDirect

VisaDirectInvalidSecret

When a VisaDirect transaction due to invalid secret

VisaDirect

VisaDirectTimeoutLimitReachedError

When a VisaDirect transaction timeout limit reached

-------

-------

-------

Interac

InteracSent

When the transaction is sent to interac

Interac

InteracAcknowledgedCredit

When a credit transaction is received by interac

Interac

InteracAcknowledgedDebit

When a debit transaction is received by interac

Interac

InteracFailedRecipientContactInfoMissing

Need to add recipient email or mobile phone number

Interac

InteracFailedInvalidEmailFormat

If the email provided is not valid. * We minimize this error by validating it before

Interac

InteracFailedInvalidPhoneNumber

If the phone number provided is not valid

Interac

InteracFailedMultipleTransferLevelErrors

If there is more than one error in the file

Interac

InteracFailedRevoked

When the transaction is revoked

Interac

InteracFailedBulkCancellationRequest

When the transaction was cancelled by request

Interac

InteracFailedRecipientRejected

When the transaction was cancelled due to recipient having declined receipt of funds

Interac

InteracFailedAuthentication

Transfer cancelled due to maximum number of unsuccessful attempts to answer the security question by the recipient

Interac

InteracFailedReachedCancellationCutOff

Transfer cancelled due to expiry

Interac

InteracFailedNotificationDeliveryFailure

Transfer cancelled due to maximum number of failed email notification attempts reached

Interac

InteracFailedAmountGreaterThanMax

If the transaction amount exceeds the maximum allowed

Interac

InteracFailedDebtorRejected

The debtor rejected the request

Interac

InteracFailedFundsDepositFailed

The funds deposit failed

Interac

InteracFailedClientEmailedToRequestCancellation

Client emailed to request cancellation

Interac

InteracFailedGenericError

When Interac Network is unavailable - * We have never seen this

Interac

InteracWaitingSettlementIntoWallet

Waiting for funds to be settled into wallet

Interac

InteracSettledIntoWallet

When Interac funds are settled into wallet

Interac

InteracFailedNameMismatch

When the debtor name used to fulfill the Interac is different than the name on file

Interac

InteracFraudAlertResponded

When a fraud alert responded for that transaction

Interac

InteracFundsHeldForValidation

User needs to contact their Financial Institution to validate the transfer and release of funds

Interac

InteracFailedInvalidAccountNumber

When the account number provided is invalid

Interac

InteracFailedRequestBlockedByUser

When the transaction failed since the user has blocked some or all Interac requests coming to their email

-------

-------

-------

CreditCard

CreditCardDeclined

Transaction declined by the issuing bank

CreditCard

CreditCardError

The card information, address, CVV is not correct

CreditCard

CreditCardHeldForReview

Transaction is pre-approved, it might take a few hours to approve completely. This is rare

CreditCard

CreditCardGenericError

The Credit Card network is unavailable

CreditCard

CreditCardUnknownResponse

No clear response from the issuing bank

CreditCard

CreditCardHoldCallOrPickUpCard

Credit Card is considered lost or stolen by the issuing bank

CreditCard

CreditCardSecViolation

Restrictions were placed on the Credit Card by the issuing bank possibly due to a security violation

CreditCard

CreditCardServNotAllowed

The merchant account or Credit Card processor is not set up for this operation

CreditCard

CreditCardCvvMismatch

Transaction rejected since CVV provided is invalid

CreditCard

CreditCardInvalidMerchantId

The account is not approved for Credit Card transactions

CreditCard

CreditCardAmountExceeded

The amount exceeds the maximum allowed by the Credit Card provider

CreditCard

CreditCardRefundAmountExceeded

Transaction amount exceeds refund limit

CreditCard

CreditCardCashbackNotApp

Cashback not applicable on card

CreditCard

CreditCardExpiredCard

Transaction rejected since the card has expired

CreditCard

CreditCardNoAccountFound

Transaction rejected since the account was not found

CreditCard

CreditCardNotPermittedToCardHolderInformed

The card holder did not authorize the transaction or the card is restricted for this usage

CreditCard

CreditCardInvalidCardNumber

Transaction rejected since card number provided is invalid

CreditCard

CreditCardRejectedAmlOrFraud

Transaction is identified as AML or potential fraud

CreditCard

CreditCardTypeNotAccepted

Card type not accepted for the transaction

CreditCard

CreditCardDomesticDebitDeclined

Domestic debits are not allowed on the card

CreditCard

CreditCardClosedAccount

Transaction rejected since the account has been closed

Transaction Chargeback Status

Type
Description

Pending

Indicates the chargeback is pending to take action.

AcceptedByUser

Indicates the chargeback was accepted by user via portal or API.

AcceptedByDefault

Indicates the chargeback was accepted past due date.

Disputed

Indicates the chargeback was disputed by user via portal our API.

Search a transaction

Use this endpoint to search for specific transactions. You can filter results using various parameters. Transactions are returned in a paginated format, so to retrieve all results, you’ll need to make successive calls to this endpoint while incrementing the CurrentPage value.

Method: POST

Endpoint: {{env}}/api/transaction/filter

{
    "Id": "c7a8a909...364e8836409d",
    "CreatedAtFrom": "2020-05-13T04:00:00.000Z",
    "CreatedAtTo": "2020-05-13T04:00:00.000Z",
    "CreatedAtOperator": "isBetween",
    "UserId": "4085e4dc...20522aab5e1b",
    "ZumRailsType": "FundZumWallet",
    "TransactionMethod": "Eft",
    "TransactionStatus": "Completed",
    "FailedTransactionEvent": "EftFailedValidationRejection",
    "Pagination": 
    {
        "PageNumber": 1
    }
}

Input parameters

Parameter
Type
Mandatory
Description

Id

guid

no

Transaction id

GenericSearch

string

no

Filter transactions by user name, user email, client transaction id, transaction id and memo

ZumRailsType

string

no

Transaction type

TransactionMethod

string

no

The transaction method

TransactionStatus

string

no

Transaction status

FailedTransactionEvent

string

no

Transaction event (column Event from the "Transaction Events" table)

DateType

string

no

The type of date on which the date-filter applies.

CreatedAtFrom

datetime

no

Start date (This field is only used when the operator is between)

CreatedAtTo

datetime

no

End date (This field is only used when the operator is between)

CreatedAt

datetime

no

Created date

CreatedAtOperator

string

no

Operator to filter with CreatedAt properties

UserId

string

no

User id

ClientTransactionId

string

no

The Transaction id you informed in the creation of the transaction

Memo

string

no

Memo field

Comment

string

no

Comment field

FraudAlertActionTaken

boolean

no

Filter transactions for which the fraud alert action was taken

FraudAlertReported

boolean

no

Filter transactions that were reported for fraud through internal analysis

Pagination

no

PageNumber

number

no

The respective page, starting at 1

Date Operators

Type
Description

IsInTheLast

Filter records on or after

ExactlyMatches

Filter records with exact date

IsBetween

Filters records in range

IsAfter

Filter records after date

IsOnOrAfter

Filter records on or after

IsBefore

Filter records before date

IsBeforeOrOn

Filter records before or on date

Date Types

Type
Description

CreatedAt

Filter records based on date when transactions were created

CompletedAt

Filter records based on date when transactions were completed

CancelledAt

Filters records based on date when transactions were cancelled

FailedAt

Filter records based on date when transactions were failed

Response

Parameter
Type
Description

CurrentPage

number

The current page

PageSize

number

The amount of rows returned in the current page

TotalCount

number

The total rows the filter returns

Items

List of transactions

Id

guid

Transaction id

CreatedAt

datetime

When the transaction was created

Memo

string

Transaction memo

Comment

string

Transaction comment

Amount

decimal

Transaction amount

ZumRailsType

string

Transaction type

TransactionMethod

string

Transaction method

TransactionStatus

string

Indicate the status of the transaction

RecurrentTransactionId

guid

The id of the recurrent transaction that created this transaction (null if inexistent)

FailedTransactionEvent

string

If the transaction has failed, the transaction event that caused it (null otherwise)

ScheduledStartDate

date

The date transaction will be sent to the financial institution

ClientTransactionId

string

The Transaction id you informed in the creation of the transaction

tip

If you're looking for a specific transaction, we recommend first retrieving its transaction ID. You can then use the GET Specific Transaction endpoint to access detailed information about that transaction.

Cancel a transaction

Use this endpoint if you want to delete or cancel a specific transaction.

Method: DELETE

Endpoint: {{env}}/api/transaction/{transaction_id}

{
  "statusCode": 200,
  "message": "DELETE Request successful.",
  "isError": false,
  "result": "Request completed"
}

INFO (Canada)

  • For EFT, transactions can only be deleted and cancelled if it's not been transmitted to the financial institution. We send transactions to the financial institution multiple times a day.

  • For Interac (bulk), the transactions are not canceled right away since we need to wait for the provider’s response as the technology is file-based. We will return 200 (OK), meaning that the cancellation request was successful. After this endpoint is called, the transaction status will be updated to Pending Cancellation. Once we receive confirmation that the cancellation was executed, the transaction status will be updated to Cancelled. If the transaction can't be canceled, the status will be updated to either Completed or Failed. Transactions can only be deleted or canceled if the end-user has not yet initiated the payment by opening the email/sms.

  • For Visa Direct / Credit Card, transactions cannot be deleted/cancelled. If needed, you can call the endpoint to reverse a Transaction.

INFO (US)

  • For Credit Card payment method, cancellation is allowed only on those transactions that have not been refunded.

Transaction batch

You can create transactions in batch by uploading a CSV file—this is supported for both EFT/ Interac (Canada) and ACH (US) payments.

A CSV template is available for download directly in the portal to help you format your data correctly.

EFT/ Interac batch file (Canada)

To process a batch of transactions:

  1. Validate the CSV file to ensure all data is correct.

NOTE

If any transaction in the EFT batch is invalid, the entire file will be rejected. This ensures full data accuracy before processing.

ACH batch file (US)

  1. Upload the CSV file- validation happens behind the scenes.

  2. Valid transactions will be processed, and any invalid ones will be skipped and flagged.

NOTE

ACH batches support partial processing, meaning a single invalid transaction will not block the rest of the file from being processed.

Validating a batch (Canada)

Use this endpoint if you want to validate an EFT or Interac transactions batch file.

Method: POST

Endpoint: {{env}}/api/transaction/ValidateBatchFile

{
  "TransactionType": "AccountsReceivable",
  "WalletId": "30126b59-ab21-491c-8033-008376504210",
  "Bytes": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKjtzY2hlZHVsZWRfZGF0ZQpKb2huO0RvZTs7MTIzOzEyMzQ1OzEyMzQ1Njc7MTAwO0ludGVybmFsIE1lc3NhZ2U7TWVtbyBtZXNzYWdlOw=="
}

Input parameters

Parameter
Type
Mandatory
Description

TransactionType

string

yes

Transaction type

WalletId

string

no

The Wallet Id, according to TransactionType

FundingSourceId

string

no

The Funding Source Id

Bytes

string

yes

The file's blob

NOTE

Only fundingSourceId or walletId should be provided- depending on the transaction type.

Response

Parameter
Type
Description

InvalidTransactions

string

The amount of invalid transactions

ValidTransactions

int

The amount of valid transactions

Status

string

The validation status

TotalAmount

decimal

The sum of all transactions amount

Transactions

AccountNumber

string

The account number

Amount

decimal

The transaction's amount

Comment

string

The transaction's comment

CompanyName

string

Company's name

CustomerId

string

Customer id

FirstName

string

User's first name

LastName

string

User's last name

InstitutionNumber

string

Institution's number

Memo

string

The transaction's memo

Status

string

The status

TransitNumber

string

Transit number

Each transaction will return a Status property explaining what is wrong with it

Status

Description

Ok

First Name, Last Name or Company name are mandatory

Either First and Last Name or Company Name should be informed

Institution, Transit and Account numbers are mandatory

Institution Number min length is 3 characters

Transit Number length needs to be 5 characters

Account Number min length is 5 characters

Account Number max length is 12 characters

Invalid amount

Amount must be greater than zero

Duplicated transaction

Creating a batch transaction (Canada)

Use this endpoint if you want to create EFT or Interac transactions using a batch file.

Method: POST

Endpoint: {{env}}/api/transaction/ProcessBatchFile

{
  "FileName": "zumrails_Ach_batch_transaction_template.csv",
  "SkipFileAlreadyProcessedInLast24Hours": true,
  "WithdrawSumTotalFromFundingSource": false,
  "Bytes":"Zmlyc3RfbmFtZV9yZXF1aXJlZDtsYXN0X25hbWVfcmVxdWlyZWQ7Y29tcGFueV9uYW1lO2VtYWlsO3Bob25lX251bWJlcjtpZF90eXBlO2lkX251bWJlcjtidXNpbmVzc190YXhfaWQ7YW1vdW50X3JlcXVpcmVkO2FkZHJlc3NMaW5lMV9yZXF1aXJlZDthZGRyZXNzTGluZTI7Y2l0eV9yZXF1aXJlZDtzdGF0ZV9yZXF1aXJlZDt6aXBfcmVxdWlyZWQ7YWNjb3VudF90eXBlX3JlcXVpcmVkO3JvdXRpbmdfbnVtYmVyX3JlcXVpcmVkO2FjY291bnRfbnVtYmVyX3JlcXVpcmVkO21lbW87Y29tbWVudDtzY2hlZHVsZWRfZGF0ZTtjbGllbnRfdXNlcl9pZA0KSm9objtEb2U7Ozs7U1NOOzEyMzQ1Njc4OTs7MTUwO01haW4gU3RyZWV0IDEyMztTdWl0ZSAzMDE7QW55dG93bjtUWDsxMjM0NTY3ODk7Q2hlY2tpbmc7MTIyMDAwNDk2OzEyMzQ1Njc4OTtNZW1vIG1lc3NhZ2U7SW50ZXJuYWwgTWVzc2FnZTsyMDI1LTA1LTA2Ow0KSm9objtEb2U7O2pvaG4uZG9lQGVtYWlsLmNvbTs1NTU1NTU1NTU1O1NTTjsxMjM0NTY3ODk7OzE2MDtNYWluIFN0cmVldCAxMjM7U3VpdGUgMzAxO0FueXRvd247VFg7MTIzNDU2Nzg5O1NhdmluZ3M7MTIyMDAwNDk2OzEyMzQ1Njc4OTtNZW1vIG1lc3NhZ2U7SW50ZXJuYWwgTWVzc2FnZTsyMDI1LTA1LTA2Ow0K",
  "FundingSourceId": "2e228bf1-0044-4058-8307-fd066089b02e",
  "TransactionMethod":"Eft",
  "TransactionType": "AccountsPayable"
}

Input parameters

Parameter
Type
Mandatory
Description

FileName

string

yes

The name of the batch file

SkipFileAlreadyProcessedInLast24Hours

bollean

yes

Checks if the same file was already processed in the last 24 hours

WithdrawSumTotalFromFundingSource

boolean

yes

If set to True, we will do one transaction to pull the entire sum of transactions in the batch from the funding source. This is only applicable for Accounts Payable transactions with more than 1 transaction in the file. It does not work for scheduled transactions. Read more about this feature here.

Bytes

string

yes

The file's blob

FundingSourceId

string

no

The Funding Source Id

WalletId

string

no

The Wallet Id, according to TransactionType

TransactionType

string

yes

Transaction type

Transaction Methos

string

yes

The selected transaction method (EFT/ Interac)

NOTE

Only fundingSourceId or walletId should be provided- depending on the transaction type.

Transaction types

Type
Description

AccountsReceivable

Execute accounts receivable AR

AccountsPayable

Execute accounts payable AP

Upload a batch file (US)

Use this endpoint if you want to upload and and process an ACH transactions batch file.

Method: POST

Endpoint: {{env}}/api/transaction/UploadBatchFileUs

{
  "FileName": "zumrails_Ach_batch_transaction_template.csv",
  "SkipFileAlreadyProcessedInLast24Hours": true,
  "WithdrawSumTotalFromFundingSource": false,
  "Bytes":"Zmlyc3RfbmFtZV9yZXF1aXJlZDtsYXN0X25hbWVfcmVxdWlyZWQ7Y29tcGFueV9uYW1lO2VtYWlsO3Bob25lX251bWJlcjtpZF90eXBlO2lkX251bWJlcjtidXNpbmVzc190YXhfaWQ7YW1vdW50X3JlcXVpcmVkO2FkZHJlc3NMaW5lMV9yZXF1aXJlZDthZGRyZXNzTGluZTI7Y2l0eV9yZXF1aXJlZDtzdGF0ZV9yZXF1aXJlZDt6aXBfcmVxdWlyZWQ7YWNjb3VudF90eXBlX3JlcXVpcmVkO3JvdXRpbmdfbnVtYmVyX3JlcXVpcmVkO2FjY291bnRfbnVtYmVyX3JlcXVpcmVkO21lbW87Y29tbWVudDtzY2hlZHVsZWRfZGF0ZTtjbGllbnRfdXNlcl9pZA0KSm9objtEb2U7Ozs7U1NOOzEyMzQ1Njc4OTs7MTUwO01haW4gU3RyZWV0IDEyMztTdWl0ZSAzMDE7QW55dG93bjtUWDsxMjM0NTY3ODk7Q2hlY2tpbmc7MTIyMDAwNDk2OzEyMzQ1Njc4OTtNZW1vIG1lc3NhZ2U7SW50ZXJuYWwgTWVzc2FnZTsyMDI1LTA1LTA2Ow0KSm9objtEb2U7O2pvaG4uZG9lQGVtYWlsLmNvbTs1NTU1NTU1NTU1O1NTTjsxMjM0NTY3ODk7OzE2MDtNYWluIFN0cmVldCAxMjM7U3VpdGUgMzAxO0FueXRvd247VFg7MTIzNDU2Nzg5O1NhdmluZ3M7MTIyMDAwNDk2OzEyMzQ1Njc4OTtNZW1vIG1lc3NhZ2U7SW50ZXJuYWwgTWVzc2FnZTsyMDI1LTA1LTA2Ow0K",
  "FundingSourceId": "2e228bf1-0044-4058-8307-fd066089b02e",
  "TransactionMethod":"Ach",
  "TransactionType": "AccountsPayable"
}

Input parameters

Parameter
Type
Mandatory
Description

FileName

string

yes

The name of the batch file

SkipFileAlreadyProcessedInLast24Hours

bollean

yes

Checks if the same file was already processed in the last 24 hours

WithdrawSumTotalFromFundingSource

boolean

yes

If set to True, we will do one transaction to pull the entire sum of transactions in the batch from the funding source. This is only applicable for Accounts Payable transactions with more than 1 transaction in the file. It does not work for scheduled transactions. Read more about this feature here.

Bytes

string

yes

The file's blob

FundingSourceId

string

no

The Funding Source Id

WalletId

string

no

The Wallet Id, according to TransactionType

TransactionType

string

yes

Transaction type

Transaction Methos

string

yes

The selected transaction method (EFT/ Interac)

Search transactions batches (US)

Retrieve a paginated list of transactions batches. This is useful for getting an overview of all transaction batches made.

Method: POST

Endpoint: {{env}}/api/batch/filter

{
    "CreatedAt": "2025-05-05T04:00:00.000Z",
    "CreatedAtOperator": "exactlymatches"
    "ItemsPerPage": 10,
    "PageNumber": 1
}

Input parameters

Parameter
Type
Required
Description

CreatedAt

string

No

The transaction status

Pagination

ItemsPerPage

Integer

No

The desired number of transactions per page

PageNumber

Integer

No

The desired page

Operators

Type
Description

contains

Filter records that contains the value

excludes

Filter records that does not contains the value

exactly matches

Filter records that exactly matches the value

Response

Parameter
Type
Decription

CurrentPage

integer

The current page number in the paginated result.

PageSize

integer

The number of items per page.

TotalCount

integer

The total number of items across all pages.

Items

List of all batch file transactions

Id

guid

Unique identifier of the batch transaction

CreatedAt

date

Timestamp of when the item was created

ZumRailsType

string

Type of the batch, e.g., "AccountsReceivable"

TransactionMethod

string

The transaction method used, e.g., "Ach"

IdCounter

integer

Internal numeric identifier- batch counter

Status

string

Status of the batch, e.g., "PartiallyProcessed"

NumberOfTransactions

integer

Number of transactions associated with the batch.

FileName

string

Name of the file associated with the batch

TransactionsCount

integer

Total number of transactions in the batch

SuccessCount

integer

Number of successfully processed transactions

FailureCount

integer

Number of failed transactions

Customer

Customer details

AchProvider

string

ACH provider used by the customer

AddressCountry

string

Country of the customer's address

Id

guid

Unique identifier of the customer

CompanyName

string

Name of the customer's company

CompanyEmail

string

Contact email of the customer's company.

Get a batch file transactions (US)

Use this endpoint to retrieve the details of a batch file transactionby its Id. It’s especially useful for viewing the status of each individual transaction processed within the batch.

Method: POST

Endpoint: {{env}}/api/batch/get-batch-transactions{batchId}

Replace {batchId} with the Id of the batch file you want to retrieve.

{
"ItemsPerPage": 10,
"PageNumber": 1
}

Input parameters

Parameter
Type
Required
Description

Status

string

No

The transaction status

Pagination

ItemsPerPage

Integer

No

The desired number of transactions per page

PageNumber

Integer

No

The desired page

Response

Parameter
Type
Description

isError

boolean

Indicates whether the request resulted in an error.

CurrentPage

integer

The current page number in the paginated result.

PageSize

integer

The number of items per page.

TotalCount

integer

The total number of items across all pages.

Items

List of all the transaction in the batch file

PhoneNumber

string

User’s phone number.

BusinessTaxId

string

User's business tax identification number (if applicable)

IdType

string

User's type of identification document (e.g., SSN)

IdNumber

string

User's identification number associated with the given ID type

AddressLine1

string

User's primary address line

AddressLine2

string

User's secondary address line

City

string

City of the user’s address

State

string

State of the user’s address

PostalCode

string

Postal or ZIP code of the user’s address

AccountType

string

Type of bank account (e.g., Checking, Savings)

RoutingNumber

string

Bank routing number for the account

AccountNumber

string

Bank account number

FirstName

string

User’s first name

LastName

string

User’s last name

CompanyName

string

Name of the user’s company, if applicable

Amount

decimal

Transaction amount

Comment

string

Internal comment or note related to the transaction

Memo

string

Description or memo field that may appear in the transaction

Status

string

Status of the transaction, including error messages if any

CustomerId

guid

Unique identifier of the customer

ScheduledDate

date

Date and time when the transaction is scheduled

Email

string

User’s email address

BatchCsvTransactionStatus

string

Overall transaction status within the batch (e.g., Success, Failed).

Each transaction includes a Status property that provides details about any issues encountered

Status

Description

Failed

Success

In Progress

Refund a Transaction

With Zūm Rails, it is easy to refund Credit Card transactions. Currently we support whole/partial refunds of initial transactions. When you create a new refund, you must specify the transaction ID that you wish to refund. Creating a new refund will refund a transaction that has previously been created but not yet refunded. Funds will be refunded to the Credit Card that was originally charged. Read more about refunds here.

Method: POST

Endpoint: {{env}}/api/transaction/{transaction_id}/Refund

{
  "Amount": 9.99
}

The response details are the same as the get transaction API.

CAUTION (Canada)

To simulate a Partial refund transaction in Sandbox, use the word PartialRefundTest in the field COMMENT while creating a Credit Card transaction. If the word PartialRefundTest is not informed, or something else is informed, you will not be able to simulate multiple Partial Refunds for this transaction.

Retrieve a refund

To retrieve the details of an existing refund, use the get transaction API.

List all refunds

Returns a list of all refunds you’ve previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. For convenience, the 10 most recent refunds will be returned by default. To get a list of all refunds, use the filter transaction API.

Last updated

Was this helpful?