Transactions

Overview#

At Zūm Rails, there are 4 ways to create transactions, when using the portal or via API. When creating a transaction via API, the transaction type “ZumRailsType” must be specified.

There are four transaction types (ZumRailsType):

  • FundZumWallet
  • WithdrawZumWallet
  • AccountsPayable
  • AccountsReceivable
note
  • Zūm Rails allows money to be sent to a user from your virtual wallet or from your funding source.
  • Zūm Rails allows money to be collected from a user to your virtual wallet or to your funding source.
  1. If you want to send money from your Funding Source to Zūm Wallet, use ZumRailsType FundZumWallet and inform:
    • FundingSourceId
    • WalletId
  2. If you want to withdraw money from Zūm Wallet to your Funding Source, use ZumRailsType WithdrawZumWallet and inform:
    • FundingSourceId
    • WalletId
  3. If you want to send money (accounts payable) from your Zūm Wallet to a User, use ZumRailsType AccountsPayable and inform:
    • UserId
    • WalletId
  4. If you want to send money (accounts payable) from your Funding Source to a User, use ZumRailsType AccountsPayable and inform:
    • UserId
    • FundingSourceId
  5. If you want to withdraw money (accounts receivable) from a User to your Zūm Wallet, use ZumRailsType AccountsReceivable and inform:
    • UserId
    • WalletId
  6. If you want to withdraw money (accounts receivable) from a User to your Funding Source, use ZumRailsType AccountsReceivable and inform:
    • UserId
    • FundingSourceId
info
  • For accounts payable use-case, Zūm Rails recommend you to first Fund the Zūm Wallet, so that the money can be quickly moved.
info
  • For accounts receivable use-case Zūm Rails, recommend you to move funds from the User to the Zūm Wallet, then set up an automatic daily withdrawal at the end of each day to your funding source.
info
  • Credit Card transactions are settled directly into the merchant account. Hence, it is not required to specify the WalletId or FundingSourceId while creating a credit card transaction

Zūm Payment Methods

Creating a new transaction#

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

Method: POST

Endpoint: {{env}}/api/transaction

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

Input parameters

ParameterTypeMandatoryDescription
ZumRailsTypestringyesTransaction type
TransactionMethodstringyesTransaction method
AmountdecimalyesTransaction amount
MemostringyesMemo 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
CommentstringnoInternal comment you might want to add. Interac transactions will display the comment on the request.
FundingSourceIdguidnoFunding Source Id
WalletIdguidnoWallet Id
UserIdguidnoUser Id
UserUser inputnoIt'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
AuthCodestringnoProcessor clients can use this to securely send user information in the transaction creation API.
ScheduledStartDatedatenoThe date when the transaction will be sent to the financial institution, in the format YYYY-MM-DD. Must be greater than today.
ClientTransactionIdstringnoThis 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
CardEcistringnoReceived from 3D secure, required if using 3D Secure but optional for Visa Direct Accounts Payable transactions
CardXidstringnoReceived from 3D secure, required if using 3D Secure but optional for Visa Direct Accounts Payable transactions
CardCavvstringnoReceived from 3D secure, required if using 3D Secure but optional for Visa Direct Accounts Payable transactions
Interac Fields--Only needed for Interac transactions
UseInteracANRbooleannoIndicates 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.
InteracHasSecurityQuestionAndAnswerbooleannoIndicate if there will be a question and answer for Interac
InteracSecurityQuestionstringyesThe question for the user to process the interac request. Required if InteracHasSecurityQuestionAndAnswer is true. Pattern accepted: String [ 5 .. 40 ] characters ^[^\s]([a-zA-Z0-9àâäèéêëîïôœùûüÿçÀÂÄÈÉÊËÎÏÔŒÙÛÜŸÇ -.\?!,#]+)[^\s]$
InteracSecurityAnswerstringyesThe answer for the user to process the interac request. Required if InteracHasSecurityQuestionAndAnswer is true. Pattern accepted: String [ 3 .. 25 ] characters [a-zA-Z0-9àâäèéêëîïôœùûüÿçÀ ÄÈÉÊËÎÏÔŒÙÛÜŸÇ]+$...
SessionFingerprintstringyesA unique identifier for this sender, we recommend using fingerprintjs. Required if peer-to-peer Interac transactions are enabled.
SessionIpAddressstringyesThe IP address of the UserId, the sender, of the funds. Required if Accounts Payable with Interac, and peer-to-peer enabled.
Authorize-noOnly needed for authorized hold credit card transactions
CapturebooleannoThe field is required for authorized hold credit card transactions. Capture can be set to true or false
AutoExpireDaysnumbernoThe field is required for authorized hold credit card transactions. AutoExpireDays should be an number between 1 to 5.
info

Either a memo or comment is mandatory for Interac transactions. If both are specified, the comment will be presented on the Interac request.

Response

ParameterTypeDescription
IdguidTransaction id

ZumRailsType

TypeDescription
FundZumWalletSend money to your Zūm Wallet
WithdrawZumWalletWithdraw from your Zūm Wallet
AccountsPayableExecute accounts payable AP
AccountsReceivableExecute accounts receivable AR

TransactionMethod

Type
Eft
Interac
VisaDirect
CreditCard
{
"ZumRailsType": "FundZumWallet",
"TransactionMethod": "Eft",
"Amount": 123.45,
"Memo": "Memo description",
"Comment": "This transaction will succeed because there's no keyword",
"FundingSourceId": "1d431e8b-...85452adb4eee",
"WalletId": "8ebd932b-...b92633e14297"
}
danger

In a sandbox environment, real bank operations are not performed. It provides a way to simulate success, failures and review situations.

caution

To simulate a failure, use one of the keywords to simulate failure (shown below) in the field COMMENT while creating a transaction. If no keyword is informed, or something else is informed, the transaction will eventually change status to "Completed". This service is executed every minute.

caution

Interac transactions in sandbox will be simulated like the real flow. Hence, emails will be sent out to the user email mentioned when the transaction is created. Make sure to use a real email address to be able to simulate this flow and complete the transaction.

caution

Occasionally, Interac flags transactions believed to be possible fraud cases. When Zum Rails is notified, the status of the transaction is changed to "Under Review". To simulate this situation (only available for interac for now), create a transaction with the keyword "UnderReview" in the COMMENT field. Transactions can be flagged "Under Review" for two other scenarios: Scenario 1: It could happen that a transaction was flagged as in "Under Review" but before an action was taken it "Completed". Simulate such transactions using the keyword "stopatunderreview" in the COMMENT field. Scenario 2: It could also happen that the transaction was "completed" and then later a fraud alert email was received and hence was flagged as in "Under Review". Simulate such transactions using the keyword "latefraudalert" in the COMMENT field. There is a service which runs every minute that will update the transaction status to Under Review in the first execution. The next time the service runs, it will Complete the transaction. These fraud alerts only apply to certain accounts*

info

When a transaction is created with a scheduled start date (delay transaction initiation), it won't be dispatched right away. This transaction will be prepared to be sent to the financial institution according to its scheduled start date.

Keywords to simulate a transaction failure

EftVisaDirectInteracCreditCard
EftFailedValidationRejectionVisaDirectGenericErrorInteracFailedRecipientContactInfoMissingCreditCardDeclined
EftFailedInsufficientFundsVisaDirectDoNotHonorInteracFailedInvalidEmailFormatCreditCardError *
EftFailedCannotLocateAccountVisaDirectInsufficientFundsInteracFailedInvalidPhoneNumberCreditCardHeldForReview *
EftFailedStopPaymentVisaDirectNotPermittedToCardHolderInformedInteracFailedMultipleTransferLevelErrorsCreditCardGenericError *
EftFailedAccountClosedVisaDirectAmountLimitNotAuthorizedInteracFailedRevokedCreditCardUnknownResponse *
EftFailedNoDebitAllowedVisaDirectRejectedAmlOrFraudInteracFailedBulkCancellationRequestCreditCardHoldCallOrPickUpCard *
EftFailedFundsNotFreeVisaDirectRejectedAccountLimitExceededInteracFailedRecipientRejectedCreditCardSecViolation *
EftFailedCurrencyAccountMismatchVisaDirectReenterTransactionInteracFailedAuthenticationCreditCardServNotAllowed *
EftFailedPayorPayeeDeceasedVisaDirectInvalidTransactionInteracFailedReachedCancellationCutOffCreditCardCvvMismatch *
EftFailedFrozenAccountVisaDirectInvalidCardNumberInteracFailedNotificationDeliveryFailureCreditCardInvalidMerchantId *
EftFailedInvalidErrorAccountNumberVisaDirectIssuerOrSwitchInoperativeInteracFailedAmountGreaterThanMaxCreditCardAmountExceeded *
EftFailedErrorPayorPayeeNameVisaDirectUnsupportedCardTypeInteracFailedDebtorRejectedCreditCardRefundAmountExceeded *
EftFailedRefusedNoAgreementVisaDirectInvalidExpiryDateInteracFailedFundsDepositFailedCreditCardCashbackNotApp *
EftFailedNotInAccountAgreementPVisaDirectInvalidPINInteracFailedClientEmailedToRequestCancellationCreditCardExpiredCard *
EftFailedNotInAccountAgreementEVisaDirectInvalidSecretInteracFailedGenericErrorCreditCardNoAccountFound *
EftFailedAgreementRevokedInteracFailedNameMismatchCreditCardNotPermittedToCardHolderInformed *
EftFailedDefaultByAFinancialInstitutionInteracFailedInvalidAccountNumberCreditCardInvalidCardNumber *
EftFailedTransactionNotAllowedInteracFailedRequestBlockedByUserCreditCardRejectedAmlOrFraud *
CreditCardTypeNotAccepted *
CreditCardDomesticDebitDeclined *
CreditCardClosedAccount *

* Not available for all credit card customers

note

You can simulate late failures (Failure 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.

Creating a new transaction - Interac peer-to-peer#

info

This endpoint is not available for all Zūm Rails customers, if you need to use it, make sure to talk with our team.

If you have an environment with Zūm Rails that support Interac peer-to-peer, you will be authorized to create transactions Accounts Receivables (pull) and Accounts Payable (push) only.

The main difference in Interac peer-to-peer is the fact that you have to inform two different users. UserId (from) and TargetUserId (to), the payload will be like:

Method: POST

Endpoint: {{env}}/api/transaction

{
"ZumRailsType": "AccountsReceivable",
"TransactionMethod": "Interac",
"Amount": 123.45,
"Memo": "Memo description",
"Comment": "This transaction is a test",
"UserId": "8ebd932b-...b92633e14290",
"TargetUserId": "8ebd932b-...b92633e14291"
}

In case you are doing an Accounts Payable - push - transaction, it's important that you call the endpoint Interac - Send Funds options to determine the options available for the target user. This endpoint will return if the user needs security question or not, as well tell if the user is eligible for Account Routing Number - ANR deposits.

The definition of all input parameters for this endpoint can be found here. The definition for all output parameters returned in this endpoint, can be found here.

info

If your Zūm Rails account is configured to user Interac peer-to-peer, you will only be authorized to do Interac transactions. If you need to use other rails, a new Zūm Rails environment will be needed.

info

When using Interac peer-to-peer, the email the TargetUserId will receive from Interac will be coming from UserId and not from your Zūm Rails environment. For example, when you do Accounts Payable from a user John, to another user Mary, the email will say: John is sending funds to Mary. This setup provides a lot of flexibility.

Without peer-to-peer, the email would say: <Your company name> is sending funds to Mary.

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": "lxtkzblpk12wurb4tczfy@gmail.com",
"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

ParameterTypeDescription
IdguidTransaction id
CreatedAtdatetimeWhen the transaction was created
MemostringTransaction memo
CommentstringTransaction comment
AmountdecimalTransaction amount
ZumRailsTypestringTransaction type
TransactionStatusstringIndicate the status of the transaction
RecurrentTransactionIdguidThe id of the recurrent transaction that created this transaction (null if inexistent)
FailedTransactionEventstringIf the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDatedateThe date transaction will be sent to the financial institution.
ClientTransactionIdstringThe Transaction id you informed in the creation of this transaction
InteracUrlstringThe interac URL to complete the transaction, if available
InteracDebtorInstitutionNumberstringThe Financial Institution used to complete the Interac Request money.
InteracDebtorFullNamestringThe 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.
UseInteracANRbooleanIndicates whether a transaction will be deposited directly to the user's saved account. (This works only for account payable transactions from wallet to user)
FromstringFrom description for the transaction
TostringTo description for the transaction
IsRefundablebooleanIndicates if the transaction is IsRefundable
FailedAtdatetimeWhen the transaction was failed (null otherwise)
AuthorizedHoldExpiredAtdatetimeWhen the transaction was the authorized hold credit card transaction (null otherwise)
CustomerBasic Customer data
CompanyNamestringCompany Name
IdguidId for the related customer
UserIf transaction has a user - * Not all information from a user is returned in this endpoint
IdguidThe user id
First NamestringUser first name
Last NamestringUser last name
Company NamestringUser company name
IsActivebooleanIndicates if the user is active or not
WalletIf transaction has a wallet * Not all information from a user is returned in this endpoint
IdguidThe wallet id
TypestringThe wallet type
FundingSourceIf transaction has a funding source * Not all information from a user is returned in this endpoint
IdguidThe funding source id
InstitutionstringThe institution name
InstitutionNumberstringThe institution number
TransitNumberstringThe transit number
AccountNumberstringThe account number
TargetWalletIf transaction has a target wallet
IdguidThe target wallet id
TypestringThe target wallet type
TransactionHistoryList of transaction history events
CreatedAtdatetimeWhen the transaction event happened
EventstringThe event happened
EventDescriptionstringThe event description

Status and events#

Zūm Rails offers 6 main statuses for transactions:

Transaction Status

TypeDescription
InProgressIndicates the transaction is being processed
CompletedIndicates 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.
FailedIndicates the transaction has failed, this is a permanent status.
CancelledIndicates the transaction has canceled, this is a permanent status.
ScheduledIndicates the transaction is scheduled.
InReviewIndicates 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.

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.

MethodEventDescription
AllStartedWhen the transaction started
AllSucceededWhen the transaction succeeds, when it finishes without any error
AllWalletFundedWhen the transaction funds a wallet
AllWalletWithdrawnWhen the transaction withdrawn a wallet
---------------------
EftEFTFileCreatedWhen an EFT file is created. One transaction might have up to 2 files
EftEFTFileUploadedWhen an EFT file is uploaded
EftEFTAnswerReceivedWhen an EFT file response is received
EftEFTAnswerProcessedWhen an EFT file is processed
EftEftFailedValidationRejectionWhen EFT could not be created, due an invalid information provided
EftEftFailedInsufficientFundsWhen transaction is rejected, due non sufficient funds available
EftEftFailedCannotLocateAccountWhen account is not located, account, transit or institution numbers are invalid
EftEftFailedStopPaymentAccount do not allow EFT
EftEftFailedAccountClosedWhen account is closed
EftEftFailedNoDebitAllowedAccount do not allow EFT
EftEftFailedFundsNotFreeWhen transaction is rejected, due non sufficient funds available
EftEftFailedCurrencyAccountMismatchWhen the currency of the transaction does not match the currency of the account
EftEftFailedPayorPayeeDeceasedAccount do not allow EFT
EftEftFailedFrozenAccountAccount do not allow EFT
EftEftFailedInvalidErrorAccountNumberWhen account is not located, account numbers are invalid
EftEftFailedErrorPayorPayeeNameWhen account is not located, first, last or company name (business) mismatch
EftEftFailedRefusedNoAgreementAccount do not allow EFT
EftEftFailedNotInAccountAgreementPAccount do not allow EFT
EftEftFailedNotInAccountAgreementEAccount do not allow EFT
EftEftFailedAgreementRevokedAccount do not allow EFT
EftEftFailedDefaultByAFinancialInstitutionGeneric error provided by the financial institution
EftEftFailedCustomerInitiatedReturnCreditOnlyWhen the payee has requested the credit to be returned
EftEftFailedTransactionNotAllowedWhen the bank account is banned
EftEftFailedCustomerInitiatedReturnCreditOnlyWhen the payee has requested the credit to be returned
EftEftFailedNoPrenotificationP1No Confirmation/Pre-Notification – Personal
EftEftFailedNoPrenotificationP2No Confirmation/Pre-Notification – Business
EftEFTFileCreatedWhen the EFT file is created
EftEFTAnswerReceivedWhen the EFT answer is received
EftEFTAnswerProcessedWhen the EFT answer is processed
EftNotEnoughBalanceInWalletErrorWhen the wallet has not balance enough
---------------------
VisaDirectVisaDirectGenericErrorWhen a generic error happened in the network
VisaDirectVisaDirectDoNotHonorWhen the information provided was inconsistent, such as address or name on card
VisaDirectVisaDirectInsufficientFundsWhen not sufficient funds available in the card
VisaDirectVisaDirectNotPermittedToCardHolderInformedWhen the card holder did not authorize the transaction or the card is restricted for this usage
VisaDirectVisaDirectAmountLimitNotAuthorizedWhen the limit informed invalid, too high or exceeds the withdrawal frequency limit, too many transactions for this card in the current period
VisaDirectVisaDirectRejectedAmlOrFraudWhen visa identified this transaction as AML or potential fraud
VisaDirectVisaDirectWaitingSettlementIntoClientsAccountsWaiting for funds to be settled into client's account
VisaDirectVisaDirectSettledIntoClientsAccountWhen visa funds are settled into client's account
VisaDirectVisaDirectInvalidCardNumberWhen the card has an invalid number
VisaDirectVisaDirectChargebackWhen the card number is invalid
VisaDirectVisaDirectReenterTransactionWhen an error happened. Retry creating the transaction
VisaDirectVisaDirectInvalidTransactionWhen transaction was considered invalid by visa direct
VisaDirectVisaDirectIssuerOrSwitchInoperativeWhen issuer or switch is inoperative
VisaDirectVisaDirectUnsupportedCardTypeWhen a type card is not supported
VisaDirectVisaDirectRejectedAccountLimitExceededWhen an account limit reaches the exceed amount
VisaDirectVisaDirectInvalidExpiryDateWhen a VisaDirect transaction due to invalid expiration dates
VisaDirectVisaDirectInvalidPINWhen a VisaDirect transaction due to invalid pin
VisaDirectVisaDirectInvalidSecretWhen a VisaDirect transaction due to invalid secret
VisaDirectVisaDirectTimeoutLimitReachedErrorWhen a VisaDirect transaction timeout limit reached
---------------------
InteracInteracSentWhen the transaction is sent to interac
InteracInteracAcknowledgedCreditWhen a credit transaction is received by interac
InteracInteracAcknowledgedDebitWhen a debit transaction is received by interac
InteracInteracFailedRecipientContactInfoMissingNeed to add recipient email or mobile phone number
InteracInteracFailedInvalidEmailFormatIf the email provided is not valid. * We minimize this error by validating it before
InteracInteracFailedInvalidPhoneNumberIf the phone number provided is not valid
InteracInteracFailedMultipleTransferLevelErrorsIf there is more than one error in the file
InteracInteracFailedRevokedWhen the transaction is revoked
InteracInteracFailedBulkCancellationRequestWhen the transaction was cancelled by request
InteracInteracFailedRecipientRejectedWhen the transaction was cancelled due to recipient having declined receipt of funds
InteracInteracFailedAuthenticationTransfer cancelled due to maximum number of unsuccessful attempts to answer the security question by the recipient
InteracInteracFailedReachedCancellationCutOffTransfer cancelled due to expiry
InteracInteracFailedNotificationDeliveryFailureTransfer cancelled due to maximum number of failed email notification attempts reached
InteracInteracFailedAmountGreaterThanMaxIf the transaction amount exceeds the maximum allowed
InteracInteracFailedDebtorRejectedThe debtor rejected the request
InteracInteracFailedFundsDepositFailedThe funds deposit failed
InteracInteracFailedClientEmailedToRequestCancellationClient emailed to request cancellation
InteracInteracFailedGenericErrorWhen Interac Network is unavailable - * We have never seen this
InteracInteracWaitingSettlementIntoWalletWaiting for funds to be settled into wallet
InteracInteracSettledIntoWalletWhen Interac funds are settled into wallet
InteracInteracFailedNameMismatchWhen the debtor name used to fulfill the Interac is different than the name on file
InteracInteracFraudAlertRespondedWhen a fraud alert responded for that transaction
InteracInteracFundsHeldForValidationUser needs to contact their Financial Institution to validate the transfer and release of funds
InteracInteracFailedInvalidAccountNumberWhen the account number provided is invalid
InteracInteracFailedRequestBlockedByUserWhen the transaction failed since the user has blocked some or all Interac requests coming to their email
---------------------
CreditCardCreditCardDeclinedTransaction declined by the issuing bank
CreditCardCreditCardErrorThe card information, address, CVV is not correct
CreditCardCreditCardHeldForReviewTransaction is pre-approved, it might take a few hours to approve completely. This is rare
CreditCardCreditCardGenericErrorThe credit card network is unavailable
CreditCardCreditCardUnknownResponseNo clear response from the issuing bank
CreditCardCreditCardHoldCallOrPickUpCardCredit card is considered lost or stolen by the issuing bank
CreditCardCreditCardSecViolationRestrictions were placed on the credit card by the issuing bank possibly due to a security violation
CreditCardCreditCardServNotAllowedThe merchant account or credit card processor is not set up for this operation
CreditCardCreditCardCvvMismatchTransaction rejected since CVV provided is invalid
CreditCardCreditCardInvalidMerchantIdThe account is not approved for credit card transactions
CreditCardCreditCardAmountExceededThe amount exceeds the maximum allowed by the credit card provider
CreditCardCreditCardRefundAmountExceededTransaction amount exceeds refund limit
CreditCardCreditCardCashbackNotAppCashback not applicable on card
CreditCardCreditCardExpiredCardTransaction rejected since the card has expired
CreditCardCreditCardNoAccountFoundTransaction rejected since the account was not found
CreditCardCreditCardNotPermittedToCardHolderInformedThe card holder did not authorize the transaction or the card is restricted for this usage
CreditCardCreditCardInvalidCardNumberTransaction rejected since card number provided is invalid
CreditCardCreditCardRejectedAmlOrFraudTransaction is identified as AML or potential fraud
CreditCardCreditCardTypeNotAcceptedCard type not accepted for the transaction
CreditCardCreditCardDomesticDebitDeclinedDomestic debits are not allowed on the card
CreditCardCreditCardClosedAccountTransaction rejected since the account has been closed

Search a transaction#

Use this endpoint if you want the search for a specific transaction.

This endpoint will return transactions based on the filters provided. Transactions are returned with pagination, which means that if you need to retrieve all transactions you need to call the same endpoint incrementing the CurrentPage.

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

ParameterTypeMandatoryDescription
IdguidnoTransaction id
GenericSearchstringnoFilter transactions by user name, user email, client transaction id, transaction id and memo
ZumRailsTypestringnoTransaction type
TransactionMethodstringnoThe transaction method
TransactionStatusstringnoTransaction status
FailedTransactionEventstringnoTransaction event (column Event from the "Transaction Events" table)
DateTypestringnoThe type of date on which the date-filter applies.
CreatedAtFromdatetimenoStart date (This field is only used when the operator is between)
CreatedAtTodatetimenoEnd date (This field is only used when the operator is between)
CreatedAtdatetimenoCreated date
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
UserIdstringnoUser id
ClientTransactionIdstringnoThe Transaction id you informed in the creation of the transaction
MemostringnoMemo field
CommentstringnoComment field
FraudAlertActionTakenbooleannoFilter transactions for which the fraud alert action was taken
FraudAlertReportedbooleannoFilter transactions that were reported for fraud through internal analysis
Paginationno
PageNumbernumbernoThe respective page, starting at 1

Date Operators

TypeDescription
IsInTheLastFilter records on or after
ExactlyMatchesFilter records with exact date
IsBetweenFilters records in range
IsAfterFilter records after date
IsOnOrAfterFilter records on or after
IsBeforeFilter records before date
IsBeforeOrOnFilter records before or on date

Date Types

TypeDescription
CreatedAtFilter records based on date when transactions were created
CompletedAtFilter records based on date when transactions were completed
CancelledAtFilters records based on date when transactions were cancelled
FailedAtFilter records based on date when transactions were failed

Response

ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of transactions
IdguidTransaction id
CreatedAtdatetimeWhen the transaction was created
MemostringTransaction memo
CommentstringTransaction comment
AmountdecimalTransaction amount
ZumRailsTypestringTransaction type
TransactionMethodstringTransaction method
TransactionStatusstringIndicate the status of the transaction
RecurrentTransactionIdguidThe id of the recurrent transaction that created this transaction (null if inexistent)
FailedTransactionEventstringIf the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDatedateThe date transaction will be sent to the financial institution
ClientTransactionIdstringThe Transaction id you informed in the creation of the transaction
tip

If you need to search for a specific transaction, we recommend for you to retrieve the transaction id and then use the GET specific transaction endpoint to retrieve the detailed information about the transaction.

Delete 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
  • For EFT, transactions can only be deleted and cancelled if it's not transmitted to the financial institution. We send transactions to the financial institution multiple times a day.
  • For Interac, the transactions are not canceled right away since we need to wait for the providers’ response. We will return 200 (OK) meaning that the cancellation request was successful. Also, transactions can only be deleted and cancelled 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

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

{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"Id": "82536c13...5f1cbb98c6c3",
"CreatedAt": "2022-07-19T16:57:48.505577Z",
"Memo": "Refund",
"Comment": "78f8f734...d7f8408596c9",
"Amount": 2.74,
"Customer": {
"Id": "e15bbe9b...dc256ba3a247",
"CompanyName": "Sam's Gym"
},
"User": {
"Id": "c11cc378...8f34ac8173be",
"FirstName": "John",
"LastName": "111",
"Email": "lxtkzblpk12wurb4tczfy@gmail.com",
"IsActive": true
},
"Wallet": {
"Id": "1790e62a...fda052b74341",
"Type": "Unified"
},
"ZumRailsType": "Refund",
"TransactionMethod": "CreditCard",
"TransactionHistory": [
{
"Id": "152ab24d...9b936225368a",
"CreatedAt": "2022-07-19T16:57:48.5981359Z",
"Event": "Started",
"EventDescription": "Transaction with type Refund started, from Zūm Wallet to User John 111 - (************2446) with amount: $2.74"
},
{
"Id": "c45a7cb5...b0cc3db894fb",
"CreatedAt": "2022-07-19T16:57:50.2792507Z",
"Event": "Succeeded",
"EventDescription": "Transaction completed"
}
],
"TransactionStatus": "Completed",
"From": "Zūm Wallet",
"To": "User John 111 - (************2446)",
"CompletedAt": "2022-07-19T16:57:50.2889607Z",
"IsRefundable": false
}
}
{
"Amount": 9.99
}

Response

Same response details of get transaction API.

caution

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.

Take Action for Interac Transactions#

This end point is used if you have "Under Review" Interac transactions and want to take appropriate action. The action you can take per transaction : Confirmed legitimate, Presumed legitimate, Confirmed fraud or Scam.

Method: PUT

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

{
"TransactionInReviewActionChosen": "ConfirmedLegitimate"
}

Input parameters

ParameterTypeMandatoryDescription
TransactionInReviewActionChosenstringyesIn Review Action (column Type from the "In Review Actions" table)

In Review Actions#

Zūm Rails offers 4 main actions for transactions in review:

In Review Actions

TypeDescription
ConfirmedLegitimateConfirm the transaction is legitimate.
PresumedLegitimatePresume the transaction is legitimate.
ConfirmedFraudConfirm the transaction is fraud.
ScamConfirm the transactions is scam.