Introduction

Welcome to Zūm Rails Documentation!

Zūm Rails has built an easy to use EFT payment gateway that allows your organization to push and pull funds in the way that best suits your organization.

This includes using our Zūm Connect portal to instantly capture users banking info and details using our aggregation engine.

The other options are to pass through to us the existing banking details you may already have. No matter how you want to process the choice is yours, even if it is a mixture of our various solutions.

This documentation provides both a high-level view of the process as well as the steps to successfully call the API.

Moving Funds

Zūm Rails and its direct integration to its partners allow funds to move more quickly than anyone else in Canada with visibility over the status of each transaction. That means there is no waiting 2-3 days just to find out whether a transaction is successful.

Funds are moved between 3 stakeholders:

Stakeholders v2

Funding Source: This is your bank account, to be able to start moving funds you will need to link your bank account information using Zūm Portal.
Zūm Wallet: This is a virtual account, we will provide to you a Zūm Wallet, so that you can use to manage funds. If you need to move funds directly from a Funding Source to User, or the opposite, the funds will pass through Zūm Wallet automatically.
User: Represents the payee for accounts payable, or the payer for accounts receivable. More details can be found under the User’s' section.

Payment Methods

Zūm Rails offers multiple payment methods depending on our agreement.

Payment methods v2

Method	Description	Duration	Send Funds	Request Funds
EFT	Electronic funds transfer between banks	3 times a day	Yes	Yes
Interac	Online e-transfers, user receives an e-mail or SMS	Immediately *	Yes	Yes
Visa Direct	Visa rails to send and pull funds directly to visa debit card	Immediately	Yes	Yes*
Credit Card	Credit Card payments/checkout to collect funds	Immediately	No	Yes

Zūm Connect

The best way to add a user to the Zūm Rails platform is through Zūm Connect. It consists of an iFrame website, hosted by Zūm Rails and referenced in your website.

The Zūm Connect iframe will display a form to capture the user's basic information (Full Name and Email) so that we can create an identity.

Connect flow v2

Depending on your business contract with Zūm, the user will be prompt to:

Method	User action required
EFT	Link the bank account using financial data aggregation
Interac	The phone number (Name and Email are captured independent of the method)
Visa Direct	Credit Card information and Address
Credit Card	Credit Card information and Address

Your specific settings will be available under your profile in Zūm Rails portal. Depending on your need you can capture the new user using our webhook mechanism or if you need it right at the moment we redirect back to your flow, you can capture the Zūm user id (token) by listening to an event message as described in your portal settings.

After a user creates and links his account, you will be able to view it in the Zūm Rails portal or use the API to filter and get a specific user.

Pre-filling the form

To help streamline the Zūm Connect experience, it is possible to pass information that you already have through optional parameters in the url:

Name	Description
accountType	Personal or Business
firstName	User first name, when the account type is Personal
lastName	User last name, when the account type when is Personal
email	User email
companyName	Company name, when the account type is Business
memo	Transaction memo that will be created with the request funds.
comment	Transaction comment that will be created with the request funds.
allowEft	To display only EFT payment method.
allowInterac	To display only INTERAC payment method.
allowVisaDirect	To display only VISA DIRECT payment method.
allowCreditCard	To display only CREDIT CARD payment method.
displayTermsAndCondition	To display the terms and conditions checkbox or not.
displayDetailsColumn	To display the left side column with transaction details, amount and recurrency
displayZumRailsLogo	To display the powered by Zũm Rails logo
displayPhoneNumber	To display the phone number field
displayAccountType	To display account type option
displayFullName	To display a full name field instead of first and last name fields when the user chooses Personal as account type. (It can be pre-filled with firstName query param)
hideRailsName	To hide the rails name when there is just one
hideFirstName*	To hide the first name field
hideLastName*	To hide the last name field
hideFullName*	To hide the full name field
hideEmail*	To hide the email field
hideCreditCardAddress*	To hide all the credit card address fields
language	Change the connect language. There are two available options: en (english) and fr (french). If not set, the language will be chosen according to the browser language. English is applied if the given language is not available
backgroundColor	Change the background color around the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)
disablePreFilledFields	Disable all fields that received a value by query parameter (Example: firstName, lastName...)

Examples:

{{env}}/connect/{{customerId}}?accountType=personal&firstname=Name&lastname=Last&email=user@zumrails.com

{{env}}/connect/{{customerId}}/{{requestFundsId}}?accountType=personal&memo=memo&comment=here%20is%20an%20example%20comment

{{env}}/connect/{{customerId}}?allowEft=true&language=fr

{{env}}/connect/{{customerId}}?allowEft=true&allowInterac=true

Event Listener

When a new user is added or a request funds is fulfilled, Zũm Connect will trigger an event to provide to your application the UserId, TransacitonId or RecurrentTransactionId.

To listen to the event in js, your website must refer to Zũm Connect using an iFrame, and then your website should have the script/example described at the right.

User added: {origin: "ZUM_RAILS", userId: "c18dd952-...-9bd6a46eb1c4"}

Request funds: {origin: "ZUM_RAILS", userId: "c18dd952-...-9bd6a46eb1c4", transactionId: "b0db65fd-...-55a57b9a7c69"}

Recurrent request funds: {origin: "ZUM_RAILS", userId: "c18dd952-...-9bd6a46eb1c4", recurrentTransactionId: "10446f5e-...-9b939cb8ab72"}

> Javascript example:
<script>
window.addEventListener('message', function(e) {

    var data = e.data;
    if (data && data.origin && data.origin === 'ZUM_RAILS') {
        console.log(data);
    }
});
</script>

If you use Connect to onboard users, listen for the field userId
If you use Connect with request funds, listen for the userId and transactionId
If you use Connect with recurrent request funds, listen for the userId and recurrentTransactionId

Zūm Wallet

Every Zūm Rails account comes with one Zūm Wallet.

The goal of the Zūm Wallet is to help you manage funds. You can preload the wallet for faster disbursement or collect multiple transactions and then send one aggregate transaction to your funding source, or split the funds. For EFT, using the wallet is optional. For Visa Direct and Credit Cards payment methods, the funds are sent to the wallet and will settle in a merchant account at the end of the day.

Api Introduction

Environments

Production:

Live Portal: https://app.zumrails.com
Live API base Url: https://api-app.zumrails.com

Sandbox:

Sandbox Portal: https://sandbox.zumrails.com
Sandbox API base Url: https://api-sandbox.zumrails.com

API Specifics

All datetime fields are stored and returned as UTC format;
All API requests must pass the header Content-type: application/json;

API Structure

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

All API endpoints return the same response, containing 4 important pieces of information:

Field	Description
statusCode	The http status code
message	A message describing if the response was successful
isError	true/false to indicate if the request was successfullly processed
result	The json response for your API call
responseException	In case the isError is true, the exception indicating the problem

Postman Collection

Follow these steps to quickly get started with the Zũm Rails API:

Once you have access to your sandbox portal:

1) Login in your sandbox portal, navigate to Settings -> Technical Information -> API Settings. Grab your api username and password

2) Download and install the Postman app

3) Install the Zũm Rails Postman Collection. Click the "Run in Postman" button below to install

4) In Postman find the endpoint /Authorize, paste your api username and password and it's all set.

This Postman Collection is already prepared to set the authorization token as an environment variable, so that you don't need to copy and paste the authorization token every time. If you need to change this configuration, go to Authorize endpoint in the Postman Collection, and open the Tests tab to view how this tweak is done.

Authentication

> Payload example:
{
  "Username": "abc...123",
  "Password": "xyz...321"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Role": "API",
        "Token": "eyJhbG...tOTuvNvJc",
        "CustomerId": "3012...042f2",
        "CompanyName": "Test Company Inc."
    }
}

Method: POST

Endpoint: {{env}}/api/authorize

All API requests are using the Bearer Token Authorization. A Bearer Token will last up to an hour from the time it is generated, allowing multiple API calls to be made securely without authorizing each time.

To be able to get your token access, open the Settings page in the Portal, then navigate to the section API settings. You will need the username and password.

Input parameters

Parameter	Type	Description
Username	string	Your API username
Password	string	Your API password

Responses

Parameter	Description
Role	The role this login belongs to
Token	The authorization token that needs to be used in any other API request
CustomerId	The customer id this login belongs to
CompanyName	The company name this login belongs to

Users

At Zūm, Users represent the payee for accounts payable, or the payer for accounts receivable. There are 3 ways of ingesting users, API, Portal, and Zūm Connect.

Zūm Rails recommends using Zūm Connect

For EFT, it offers the end user the possibility to link his bank account, ensuring that the bank account information will be verified to avoid transaction failures.
For Credit Card and Visa Direct, it's required so that we reduce your PCI scope.

For more information about Zūm Connect, click here:

Creating a new user

> Payload example:
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@zumrails.com",
  "companyName": null,
  "phoneNumber": "514-123-1234",
  "BankAccountInformation": {
    "institutionNumber": "111",
    "transitNumber": "12345",
    "accountNumber": "1234567"
  },
  "CreditCardInformation": {
    "Number": "1234123412341234",
    "ExpireMonth": "01",
    "ExpireYear": "2020",
    "CVV": "123",
    "AddressLine1": "123 street",
    "AddressLine2": "Apartment 123",
    "AddressPostalCode": "A1A 1A1",
    "AddressCountry": "Canada",
    "AddressCity": "Toronto",
    "AddressState": "ON"
  }
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19",
        "FirstName": "John",
        "LastName": "Doe",
        "CompanyName": null
    }
}

Method: POST

Endpoint: {{env}}/api/user

Use this endpoint if you want to add a new user to your account. For Credit Card and Visa Direct, if you want to add a user through API, please contact Zūm support.

Input parameters

Parameter	Type	EFT (Mandatory)	Interac (Mandatory)	Credit Card (Mandatory)	Visa Direct (Mandatory)	Description
FirstName	string	yes	yes	yes	yes	User first name
LastName	string	yes	yes	yes	yes	User last name
CompanyName	string	no	yes	yes	yes	Company name, in case it's a company
Email	string	yes	yes	yes	yes	User e-mail
PhoneNumber	string	no	no	no	no	Phone number
BankAccountInformation		yes
InstitutionNumber	string	yes	no	no	no	Institution Number, 3 digits
TransitNumber	string	yes	no	no	no	Transit Number, 5 digits
AccountNumber	string	yes	no	no	no	Account Number
CreditCardInformation				yes	yes
Number	string	no	no	yes	yes
ExpireMonth	number	no	no	yes	yes	Card expiry month, 2 digits
ExpireYear	number	no	no	yes	yes	Card expiry year, 4 digits
CVV	string	no	no	yes	yes	Security code, 3 or 4 digits
AddressLine1	string	no	no	yes	no	Billing address line 1
AddressLine2	string	no	no	yes	no	Billing address line 2
AddressPostalCode	string	no	no	yes	no	Billing address postal code
AddressCountry	string	no	no	yes	no	Billing address country
AddressCity	string	no	no	yes	no	Billing address city
AddressState	string	no	no	yes	no	Billing address state/province

If the user will be sending funds to Zūm (pull from a card) via Via Direct transaction, ExpireMonth and ExpireYear are required
If the user will be receiving funds from Zūm (push from a card), ExpireMonth, ExpireYear, and CVV are optional

Response

Parameter	Type	Description
id	guid	User id
firstName	string	First name
lastName	string	Last name
companyName	string	Company name, in case it's a company

Update user

> Payload example:
{
  "firstName": "John",
  "lastName": "Doe",
  "companyName": null,
  "email": "johndoe@zumrails.com",
  "phoneNumber": "514-123-1234"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": "0bc9894d-....-f691024aca19"
}

Method: PATCH

Endpoint: {{env}}/api/user/UpdateBasicInformation/{user_id}

Use this endpoint if you want to edit the basic information for an existing user. The user id is informed in the url and the body payload contains the user information. This endpoint does not update the bank account information or the credit card information.

Input parameters

Parameter	Type	EFT (Mandatory)	Interac (Mandatory)	Credit Card (Mandatory)	Visa Direct (Mandatory)	Description
FirstName	string	yes	yes	yes	yes	User first name
LastName	string	yes	yes	yes	yes	User last name
CompanyName	string	no	yes	yes	yes	Company name, in case it's a company
Email	string	yes	yes	yes	yes	User e-mail
PhoneNumber	string	no	no	no	no	Phone number

Response

Parameter	Type	Description
id	guid	User id

Update bank account information

> Payload example:
{
    "institutionNumber": "111",
    "transitNumber": "12345",
    "accountNumber": "1234567"
 }
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": "0bc9894d-....-f691024aca19"
}

Method: PATCH

Endpoint: {{env}}/api/user/UpdateBankAccountInformation/{user_id}

Use this endpoint if you want to edit the bank account information from a user. The user id is informed in the url and the body payload contains the user information.

Input parameters

Parameter	Type	EFT (Mandatory)	Description
InstitutionNumber	string	yes	Institution Number, 3 digits
TransitNumber	string	yes	Transit Number, 5 digits
AccountNumber	string	yes	Account Number

Response

Parameter	Type	Description
id	guid	User id

Update credit card information

> Payload example:
{
    "Number": "4242424242424242",
    "ExpireMonth": "01",
    "ExpireYear": "2025",
    "CVV": "111",
    "AddressLine1": "123 street",
    "AddressLine2": "Apartment 123",
    "AddressPostalCode": "A1A 1A1",
    "AddressCountry": "Canada",
    "AddressCity": "Toronto",
    "AddressState": "ON"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": "0bc9894d-....-f691024aca19"
}

Method: PATCH

Endpoint: {{env}}/api/user/UpdateCreditCardInformation/{user_id}

Use this endpoint if you want to edit the credit card information from a user. The user id is informed in the url and the body payload contains the user information.

Input parameters

Parameter	Type	Credit Card (Mandatory)	Visa Direct (Mandatory)	Description
Number	string	yes	yes
ExpireMonth	number	yes	yes	Card expiry month, 2 digits
ExpireYear	number	yes	yes	Card expiry year, 4 digits
CVV	string	yes	yes	Security code, 3 or 4 digits
AddressLine1	string	no	yes	Billing address line 1
AddressLine2	string	no	yes	Billing address line 2
AddressPostalCode	string	no	yes	Billing address postal code
AddressCountry	string	no	yes	Billing address country (Canada)
AddressCity	string	no	yes	Billing address city
AddressState	string	no	yes	Billing address state/province

Response

Parameter	Type	Description
id	guid	User id

Get a specific user

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "Id": "03dcefc9-4aad-4184-a93f-dd734a1e9ddc",
        "CreatedAt": "2020-05-13T14:23:32.809446",
        "FirstName": "john",
        "LastName": "Doe",
        "CompanyName": null,
        "PhoneNumber": null,
        "Email": "johndoe@gmail.com",
        "LastRefresh": "0001-01-01T00:00:00",
        "BankAccountInformation": {
            "Institution": "Bank Name",
            "InstitutionNumber": "123",
            "TransitNumber": "12345",
            "AccountNumber": "1234567",
            "FirstName": null,
            "LastName": null,
            "AggregationStatus": "Connected",
            "LastTimeRefreshed": "2020-05-13T14:24:05.82614",
            "AggregationFailedReason": "None",
            "AggregationBalance": 50007.98
        },
        "CreditCardInformation": {
            "Number": "************1234",
            "ExpireMonth": "01",
            "ExpireYear": "2020",
            "AddressLine1": "123 street",
            "AddressLine2": "Apartment 123",
            "AddressPostalCode": "A1A 1A1",
            "AddressCountry": "Canada",
            "AddressCity": "Toronto",
            "AddressState": "ON",
            "BrandName": "Visa",
            "Institution": "TD",
            "VerifyCreditCardStatus": "NotVerified"
        },
        "TransactionsMethodsAvailable": {
            "Eft": true,
            "VisaDirectPull": false,
            "VisaDirectPush": false,
            "Interac": true, 
            "CreditCard": true
        }
    }
}

Method: GET

Endpoint: {{env}}/api/user/{user_id}

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

Response

Parameter	Type	Description
Id	guid	guid
CreatedAt	datetime	When the user was created
FirstName	string	First name
LastName	string	Last name
CompanyName	string	Company name
PhoneNumber	string	Last name
Email	string	Last name
LastRefresh	datetime	Last name
BankAccountInformation
Institution	string	Institution name
InstitutionNumber	string	Institution Number
TransitNumber	string	Transit Number
AccountNumber	string	Account Number
FirstName	string	Last name
LastName	string	Last name
AggregationStatus	string	Indicate if the account is Connected
LastTimeRefreshed	datetime	When the last refresh happened
AggregationFailedReason	string	If failed, informs the failure reason
AggregationBalance	decimal	EFT account current balance
CreditCardInformation
Number	string	Last for digits only
ExpireMonth	number	Card expiry month, 2 digits
ExpireYear	number	ard expiry year, 4 digits
CVV	string	Security code, 3 or 4 digits
AddressLine1	string	Billing address line 1
AddressLine2	string	Billing address line 2
AddressPostalCode	string	Billing address postal code
AddressCountry	string	Billing address country
AddressCity	string	Billing address city
AddressState	string	Billing address state/province
BrandName	string	The brand, Visa, Master, etc.
Institution	string	The institution of the card, valid for Visa Direct when using aggregation
VerifyCreditCardStatus	string	If it is credit card and the card is verified
TransactionsMethodsAvailable
Eft	Boolean	Indicate if this user can do EFT transactions
VisaDirectPull	Boolean	Indicate if this user can do Visa Direct PULL transactions
VisaDirectPush	Boolean	Indicate if this user can do Visa Direct PUSH transactions
Interac	Boolean	Indicate if this user can do Interac transactions
CreditCard	Boolean	Indicate if this user can do Credit Card transactions

AggregationStatus

Status	Description
NotConected	The account is not linked using Zūm Connect
Connected	Account is fully connected and ready to be used
Connecting	Process underway to link account
Refreshing	The account is linked, but the aggregation service is still refreshing/connecting the account.
RefreshFailed	The account was linked but the aggregation service could not refresh the most updated information

Delete a user

> Response example:
{
    "statusCode": 200,
    "message": "DELETE Request successful.",
    "isError": false,
    "result": ""
}

Method: DEL

Endpoint: {{env}}/api/user/{user_id}

Use this endpoint if you want to delete a user. The user id is informed in the url. When deleting a user, all transactions already created for the respective user will remain active, but the user data will be completely erased.

Search for a user

> Payload example:
{
    "CreatedAtOperator": "isBetween",
    "CreatedAtFrom":"2020-05-13T04:00:00.000Z",
    "CreatedAtTo":"2020-05-13T04:00:00.000Z",
    "FirstName":"john",
    "LastName":"Doe",
    "Email":"johndoe@gmail.com",
    "Pagination": {
        "PageNumber": 1
    }
}
> Response example:
{
    "statusCode":200,
    "message":"POST Request successful.",
    "isError":false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 1,
        "TotalCount": 1,
        "Items": [
        {
            "Id":"4085e4dc-f4f4-41d2-8bf2-20522aab5e1b",
            "CreatedAt":"2020-05-12T15:23:24.531531",
            "FirstName":"John",
            "LastName":"Doe",
            "Email":"johndoe@gmail.com",
            "CompanyName":"",
            "BankAccountInformation":
            {
                "LastTimeRefreshed":"2020-05-12T15:23:24.496157",
                "AggregationStatus":"NotConected",
                "AggregationBalance":123.45
            }
        }]
    }
}

Method: POST

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

Use this endpoint if you want to search for a specific user. Users are returned with pagination, which means that if you need to retrieve all users you need to call the same endpoint incrementing the CurrentPage. This endpoint will not return all user information, if you need to get a specific user information, then you need to call the user/get endpoint

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

Input parameters

Parameter	Type	Mandatory	Description
GenericSearch	string	no	Filter users by user name and user email
Name	string	no	First and/or Last name
CreatedAt	datetime	no	Create date
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)
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties (Operators):
Email	string	no	User email
Pagination		no
PageNumber	number	no	The respective page, starting at 1

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
Id	guid	guid
CreatedAt	datetime	When the user was created
FirstName	string	First name
LastName	string	Last name
CompanyName	string	Company name
Email	string	Last name
BankAccountInformation		* if available
LastTimeRefreshed	datetime	Last time the account was refreshed
AggregationStatus	string	Indicates if the account is linked with the aggregation service
AggregationBalance	decimal	Account balance

Aggregation

Note on aggregation

When aggregation is enabled in your account, Zūm Rails to pull a user’s financial data for use-cases such as account verification (using kyc) and risk assessment (using 90 days of transaction history).

Zūm will then dispatch the connection to the financial data aggregator.

Get a user's bank account information

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "Id": "2babb324-3a80-4a35-a1cc-b3795d294d18",
        "HolderName": "John Smith",
        "HolderCivicAddress": "1234 Street 01",
        "HolderCity": "Toronto",
        "HolderProvince": "ON",
        "HolderPostalCode": "A0A 1A1",
        "HolderCountry": "CA",
        "HolderEmail": "email@zumrails.com",
        "HolderPhoneNumber": "(123) 123-1234",
        "Institution": "Bank Name",
        "Accounts": [
            {
                "Id": "4e399a3d-7562-4008-b074-16991f14cc72",
                "ProviderAccountId": "729e24f0-6458-40f2-4afa-08d7a8df7f42",
                "Transactions": [
                    {
                        "Id": "02464c54-9ce4-4912-a426-a8c440b9a996",
                        "ProviderTransactiontId": "00000000-0000-0000-0000-000000000000",
                        "Date": "2020-05-09T00:00:00",
                        "Description": "TrxChe@Cr15.91",
                        "Debit": null,
                        "Credit": 15.91,
                        "Balance": 50007.96
                    },
                    {
                        "Id": "047c6bab-50fe-4420-a46f-beeb32408a06",
                        "ProviderTransactiontId": "00000000-0000-0000-0000-000000000000",
                        "Date": "2020-03-09T00:00:00",
                        "Description": "TrxChe@De15.30",
                        "Debit": 15.3,
                        "Credit": null,
                        "Balance": 49992.35
                    }
                ],
                "TransitNumber": "12345",
                "InstitutionNumber": "123",
                "AccountNumber": "1234567",
                "Title": "Chequing Account",
                "Balance": 123.45,
                "Category": "Operations",
                "Type": "Chequing",
                "Currency": "CAD",
                "IsEftEligible": true
            }
        ],
        "LastRefresh": "2020-05-13T14:23:52.323512",
    }
}

Method: GET

Endpoint: {{env}}/api/user/getbankaccountinformation/{user_id}

When a user logs in through the Zūm Connect iframe, his information can be accessed by calling the user/getBankaccountinformation endpoint.

Response

Parameter	Type	Description
Id	guid	Zūm aggregation card id
HolderName	string	Account holder name
HolderCivicAddress	string	Account holder civic address
HolderCity	string	Account holder address city
HolderProvince	string	Account holder address province
HolderPostalCode	string	Account holder address postal code
HolderCountry	string	Account holder address country
HolderEmail	string	Account holder e-mail
FirstName	string	Account holder first name
HolderPhoneNumber	string	Account holder phone number
Institution	string	Institution name
LastRefresh	datetime	Last time the card was refreshed
ProviderCardId	guid	The provider card id
Accounts
Id	guid	Zūm account id
ProviderAccountId	guid	Provider account id
TransitNumber	string	Transit number
InstitutionNumber	string	InstitutionNumber
AccountNumber	string	Account number
Title	string	Account title
Balance	decimal	Account balance
Category	string	Account category
Type	string	Account type
Currency	string	Account currency
IsEftEligible	boolean	Indicates if account is EFT eligible
Transactions
Id	guid	Zūm transaction id
ProviderTransactiontId	guid	Provider transactions id
Date	datetime	Transaction date
Description	string	Transaction description
Debit	string	Transaction debit
Credit	string	Transaction credit
Balance	string	Balance

The AggregationStatus domain can be found under the User’s section.

Get a specific funding source

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "Id": "447c3213-759b-40e4-a424-382f558dea4c",
        "Customer": {
            "Id": "acbcc52c-eb1b-4248-85a7-31fee8f3a3ca",
            "CompanyName": "Your Company"
        },
        "Institution": "Bank Name",
        "InstitutionNumber": "123",
        "TransitNumber": "12345",
        "AccountNumber": "1234567",
        "AccountType": "Personal",
        "Name": "John Smith",
        "CompanyName": null,
        "FirstName": "John",
        "LastName": "Smith",
        "CreatedAt": "2020-10-22T19:02:26.777304",
        "AggregationStatus": "Connected",
        "LastTimeRefreshed": "2020-10-22T19:02:58.061333",
        "AggregationFailedReason": "None",
        "AggregationBalance": 50017.58,
        "AggregationCard": {
            "Id": "2babb324-3a80-4a35-a1cc-b3795d294d18",
            "HolderName": "John Smith",
            "HolderCivicAddress": "1234 Street 01",
            "HolderCity": "Toronto",
            "HolderProvince": "ON",
            "HolderPostalCode": "A0A 1A1",
            "HolderCountry": "CA",
            "HolderEmail": "email@zumrails.com",
            "HolderPhoneNumber": "(123) 123-1234",
            "Institution": "Bank Name",
            "Accounts": [
                {
                    "Id": "4e399a3d-7562-4008-b074-16991f14cc72",
                    "ProviderAccountId": "729e24f0-6458-40f2-4afa-08d7a8df7f42",
                    "Transactions": [
                        {
                            "Id": "02464c54-9ce4-4912-a426-a8c440b9a996",
                            "ProviderTransactiontId": "00000000-0000-0000-0000-000000000000",
                            "Date": "2020-05-09T00:00:00",
                            "Description": "TrxChe@Cr15.91",
                            "Debit": null,
                            "Credit": 15.91,
                            "Balance": 50007.96
                        },
                        {
                            "Id": "047c6bab-50fe-4420-a46f-beeb32408a06",
                            "ProviderTransactiontId": "00000000-0000-0000-0000-000000000000",
                            "Date": "2020-03-09T00:00:00",
                            "Description": "TrxChe@De15.30",
                            "Debit": 15.3,
                            "Credit": null,
                            "Balance": 49992.35
                        }
                    ],
                    "TransitNumber": "12345",
                    "InstitutionNumber": "123",
                    "AccountNumber": "1234567",
                    "Title": "Chequing Account",
                    "Balance": 123.45,
                    "Category": "Operations",
                    "Type": "Chequing",
                    "Currency": "CAD",
                    "IsEftEligible": true
                }
            ],
            "LastRefresh": "2020-10-22T19:02:29.63879",
            "BankAccountInformationOrigin": "Origin",
            "ProviderCardId": "694e916b-262e-4139-07db-08d7a8df789b",
            "CustomerId": "acbcc52c-eb1b-4248-85a7-31fee8f3a3ca"
        },
        "HasMinimumInformationForEft": true
    }
}

Method: GET

Endpoint: {{env}}/api/fundingsource/{fundingsource_id}

Use this endpoint if you want to get a specific funding source's detailed information. The funding source id is informed in the url.

Response

Parameter	Type	Description
Id	guid	Customer id
Institution	string	Institution name
InstitutionNumber	string	Institution Number
TransitNumber	string	Transit Number
AccountNumber	string	Account Number
AccountType	string	Account type
Name	string	If it's a personal account, name will be FirstName + LastName; if it's business, name will be CompanyName
CompanyName	string	Company's name (only if it's a business count)
FirstName	string	First name (only if it's personal account)
LastName	string	Last name (only if it's personal account)
AggregationStatus	string	Aggregation status
LastTimeRefreshed	datetime	When the last refresh happened
AggregationFailedReason	string	If failed, informs the failure reason
AggregationBalance	decimal	EFT account current balance
HasMinimumInformationForEft	boolean	If funding source has the minimum information to allow EFT transactions to be performed
Customer
Id	guid	Customer id
CompanyName	string	Customer's company name

AccountType

Type	Description
Personal	Personal account
Business	Business account

The AggregationStatus domain can be found under the User’s section.
The AggregationCard domain can be found under the Aggregation’s section.

Transactions

At Zūm Rails, there are 5 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 five transaction types (ZumRailsType):

FundZumWallet
WithdrawZumWallet
AccountsPayable
AccountsReceivable
UserTransfer

If you want to send money from your Funding Source to Zūm Wallet, use ZumRailsType FundZumWallet and inform:
- FundingSourceId
- WalletId
If you want to withdraw money from Zūm Wallet to your Funding Source, use ZumRailsType WithdrawZumWallet and inform:
- FundingSourceId
- WalletId
If you want to send money (accounts payable) from your Zūm Wallet to a User, use ZumRailsType AccountsPayable and inform:
- UserId
- WalletId
If you want to send money (accounts payable) from your Funding Source to a User, use ZumRailsType AccountsPayable and inform:
- UserId
- FundingSourceId
If you want to withdraw money (accounts receivable) from a User to your Zūm Wallet, use ZumRailsType AccountsReceivable and inform:
- UserId
- WalletId
If you want to withdraw money (accounts receivable) from a User to your Funding Source, use ZumRailsType AccountsReceivable and inform:
- UserId
- FundingSourceId
If you want to move money between your Users, use ZumRailsType UserTransfer and inform:
- UserId
- TargetUserId

Payment methods v2

Creating a new transaction

> Payload example EFT:
{
    "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"
}

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

> Payload example Interac:
{
    "ZumRailsType":"AccountsReceivable",
    "TransactionMethod": "Interac",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction is just a test from a user to wallet",
    "User": { 
        "companyName": "Example Company",
        "email": "example@company.com"
    },
    "WalletId":"8ebd932b-...b92633e14297",
    "InteracHasSecurityQuestionAndAnswer": true,
    "InteracSecurityQuestion": "Your question",
    "InteracSecurityAnswer": "Your answer"
}

> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-...f691024aca19",
    }
}

Method: POST

Endpoint: {{env}}/api/transaction

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

Input parameters

Parameter	Type	Mandatory	Description
ZumRailsType	string	yes	Transaction type
TransactionMethod	string	yes	Transaction method
Amount	decimal	yes	Transaction amount
Memo	string	*yes if customer transaction description type is "PerTransaction"	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
FundingSourceId	guid	no	Funding Source Id
WalletId	guid	no	Wallet Id
UserId	guid	no	User Id
User	User input	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
InteracHasSecurityQuestionAndAnswer	boolean	no	Indicate if there will be a question and answer for Interac
InteracSecurityQuestion	string	yes if InteracHasSecurityQuestionAndAnswer is true	The question for the user to process the interac request
InteracSecurityAnswer	string	yes if InteracHasSecurityQuestionAndAnswer is true	The answer for the user to process the interac request
ScheduledStartDate	date	no	The date when the transaction will be sent to the financial institution. 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
UseInteracANR	boolean	no	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)

Response

Parameter	Type	Description
Id	guid	Transaction id

ZumRailsType

Type	Description
FundZumWallet	Send money to your Zūm Wallet
WithdrawZumWallet	Withdraw from your Zūm Wallet
AccountsPayable	Execute accounts payable AP
AccountsReceivable	Execute accounts receivable AR
UserTransfer	Execute transfer between users

TransactionMethod

Type
Eft
Interac
VisaDirect
CreditCard

> Transaction that will succeed example:
{
    "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"
}
> Transaction that will fail example:
{
    "ZumRailsType":"FundZumWallet",
    "a":"Eft",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction will fail (EftFailedNoDebitAllowed)",
    "FundingSourceId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297"
}

Keywords to simulate a transaction failure

Eft	VisaDirect	Interac	CreditCard
EftFailedValidationRejection	VisaDirectGenericError	InteracFailedRecipientContactInfoMissing	CreditCardDeclined
EftFailedInsufficientFunds	VisaDirectDoNotHonor	InteracFailedInvalidEmailFormat	CreditCardError *
EftFailedCannotLocateAccount	VisaDirectInsufficientFunds	InteracFailedInvalidPhoneNumber	CreditCardHeldForReview *
EftFailedStopPayment	VisaDirectNotPermittedToCardHolderInformed	InteracFailedMultipleTransferLevelErrors	CreditCardGenericError *
EftFailedAccountClosed	VisaDirectAmountLimitNotAuthorized	InteracFailedRevoked
EftFailedNoDebitAllowed	VisaDirectRejectedAmlOrFraud	InteracFailedBulkCancellationRequest
EftFailedFundsNotFree	VisaDirectRejectedAccountLimitExceeded	InteracFailedRecipientRejected
EftFailedCurrectAccountMismatch		InteracFailedAuthentication
EftFailedPayorPayeeDeceased		InteracFailedReachedCancellationCutOff
EftFailedFrozenAccount		InteracFailedNotificationDeliveryFailure
EftFailedInvalidErrorAccountNumber		InteracFailedAmountGreaterThanMax
EftFailedErrorPayorPayeeName		InteracFailedDebtorRejected
EftFailedRefusedNoAgreement		InteracFailedFundsDepositFailed
EftFailedNotInAccountAgreementP		InteracFailedClientEmailedToRequestCancellation
EftFailedNotInAccountAgreementE		InteracFailedGenericError
EftFailedAgreementRevoked		InteracFailedNameMismatch
EftFailedDefaultByAFinancialInstitution

Get a specific transaction

> Response example:
{
    "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,
        "User": null,
        "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
    }
}

Method: GET

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

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

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 Zum 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)
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
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
EventHistory		The 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 3 main states 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. 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.

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	EftFailedCurrectAccountMismatch	When account is not located, account, transit or institution numbers are invalid
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
-------	-------	-------
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	When visa funds are waiting to settle into client's account
VisaDirect	VisaDirectSettledIntoClientsAccount	When visa funds are settled into client's account
-------	-------	-------
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	When Interac funds are waiting to settle 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
-------	-------	-------
CreditCard	CreditCardDeclined	Not available balance in the card
CreditCard	CreditCardError	The card information, address, CVV is not correct
CreditCard	CreditCardHeldForReview	When the transaction is pre-approved, it might take a few hours to approve completely. This is rare
CreditCard	CreditCardGenericError	When 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
CreditCard	CreditCardServNotAllowed	The merchant account or credit card processor is not set up for this operation
CreditCard	CreditCardCvvMismatch	CVV mismatch
CreditCard	CreditCardInvalidMerchantId	Your account is not approved for credit card transactions
CreditCard	CreditCardAmountExceeded	The amount exceeds the maximum allowed by the credit card provider

Search a transaction

This endpoint will return transactions based on the filter informed. 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.

> Payload example:
{
    "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
    }
}
> Response example:
{
    "statusCode":200,
    "message":"POST Request successful.",
    "isError":false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 1,
        "TotalCount": 2,
        "Items": [
            {
                "Id": "b7a8a505...364e8836404e",
                "CreatedAt": "2020-05-13T17:59:47.039462",
                "Memo": "Memo test",
                "Comment": "This is a transaction to test the platform",
                "Amount": 123.45,
                "ZumRailsType": "FundZumWallet",
                "TransactionMethod":"Eft",
                "TransactionStatus": "InProgress",
                "RecurrentTransactionId": "16d2406f...87d397a8356g",
                "FailedTransactionEvent" : null
            },
            {
                "Id": "c8a8a505...364e8836405f",
                "CreatedAt": "2020-05-13T17:59:47.039462",
                "Memo": "Memo test",
                "Comment": "This is a transaction to test the platform",
                "Amount": 123.45,
                "ZumRailsType": "FundZumWallet",
                "TransactionMethod":"Eft",
                "TransactionStatus": "Failed",
                "RecurrentTransactionId": null,
                "FailedTransactionEvent" : "EftFailedValidationRejection"
            }
        ]
    }
}

Method: POST

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

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

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)
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	Create date
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties (Operators)
UserId	string	no	User id
ClientTransactionId	string	no	The Transaction id you informed in the creation of the transaction
Pagination		no
PageNumber	number	no	The respective page, starting at 1

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
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

Delete a transaction

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

Method: DELETE

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

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

Recurrent Transactions

Recurring transactions can be used to automatically trigger the creation of a new transaction based on the a frequency. Zūm Rails offers weekly, bi-weekly and monthly.

Creating a new recurrent transaction using API

> Payload example:
{
    "ZumRailsType":"FundZumWallet",
    "TransactionMethod": "Interac",
    "Amount":123.45,
    "Memo":"Memo",
    "Comment":"This transaction is just a test",
    "FundingSourceId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297",
    "IsRecurrent": true,
    "RecurrenceType": "Monthly",
    "DayOfWeek": "Monday",
    "DayOfMonth": 1,
    "StartDate": "2020-01-20",
    "EndDate": "2021-06-30"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-...f691024aca19",
    }
}

Method: POST

Endpoint: {{env}}/api/transaction

To create a recurrent transaction, use the same endpoint you use to create a normal transaction, just add a few more parameters

Input parameters

Parameter	Type	Mandatory	Description
ZumRailsType	string	yes	Transaction type
TransactionMethod	string	yes	Transaction method
Amount	string	yes	Transaction amount
Memo	string	no	Memo description. Note: maximum length 15 characters
Comment	string	no	Internal comment you might want to add
FundingSourceId	guid	no	Funding Source Id
WalletId	guid	no	Wallet Id
UserId	guid	no	User Id
InteracHasSecurityQuestionAndAnswer	bool	no	Indicate if there will be a question and answer for Interac
InteracSecurityQuestion	string	yes if InteracHasSecurityQuestionAndAnswer is true	The question for the user to process the interac request
InteracSecurityAnswer	string	yes if InteracHasSecurityQuestionAndAnswer is true	The answer for the user to process the interac request
IsRecurrent	bool	yes	Indicates if it's a recurrent transaction
RecurrenceType	string	yes	The frequency
DayOfWeek	string	yes/no	This is mandatory if you inform RecurrenceType: Bi-weekly and weekly
DayOfMonth	int	yes/no	This is mandatory if you inform RecurrenceType: Monthly and LastDayOfTheMonth: false. Must be between 1 and 28
LastDayOfTheMonth	bool	no	This is optional if RecurrenceType: Monthly. If true, the transactions will be created always in the last day of the month
StartDate	date	yes/no	When the recurrency must begin. yyyy-mm-dd
EndDate	date	yes/no	When the recurrency must stop. yyyy-mm-dd

Response

Parameter	Type	Description
Id	guid	Transaction id

RecurrenceType

Type	Description
Monthly	A new transaction will be created once a month
Biweekly	A new transaction will be created once every 2 weeks
Weekly	A new transaction will be created per week

DayOfWeek

Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday

Get recurrent transaction

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "Id": "e60deffd-...-e9504f6a3a81",
        "CreatedAt": "2020-04-28T14:48:06.916779",
        "Memo": "",
        "Comment": "",
        "Amount": 0.01,
        "ZumRailsType": "FundZumWallet",
        "TransactionMethod": "Interac",
        "StartDate": "2020-01-20T03:00:00",
        "EndDate": "2021-08-28T04:00:00",
        "RecurrenceType": "Weekly",
        "DayOfWeek": "Monday",
        "DayOfMonth": null,
        "From": "Funding Source (RBC-01234-1234567)",
        "To": "Zūm Wallet",
        "UserId": null,
        "FundingSourceId": "c7f77ae5-...-14b6c3fd7ad1",
        "WalletId": "30126b59-...-008376504211",
        "TransactionsIds": [
            "47996650-...-0d082ee63b5e",
            "d88d3f2a-...-d0a0f146d1e8"
        ],
        "OriginalStartDate": "2020-01-20T03:00:00",
        "OriginalEndDate": "2020-08-28T04:00:00",
        "OriginalAmount": 2.22,
        "OriginalDayOfWeek": "Monday",
        "OriginalDayOfMonth": null,
        "ResetToOriginalValues": false
    }
}

Method: GET

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

Use this endpoint if you want to get the recurrent transaction information. The recurrent transaction id is informed in the url. Note that the endpoint is recurrenttransaction

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
TransactionMethod	string	Transaction method
UserId	guid	The user id
WalletId	guid	The wallet id
FundingSourceId	guid	The funding source id
RecurrenceType	string	The frequency
DayOfWeek	string	Which day of the week transactions will be created
DayOfMonth	int	Which day transactions will be created
LastDayOfTheMonth	bool	If the transactions will be created in the last day of the month
StartDate	date	When the recurrency must begin. yyyy-mm-dd
EndDate	date	When the recurrency must stop. yyyy-mm-dd
From	string	Description of where funds are coming from
To	string	Description of where funds are going
TransactionsIds	array of guids	An array containing the ids of the transactions originated by the recurrent transaction
OriginalStartDate	date	The start date used as backup (updated when ResetToOriginalValues is set to false)
OriginalEndDate	date	The end date used as backup (updated when ResetToOriginalValues is set to false)
OriginalAmount	decimal	The amount used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfWeek	string	The week day used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfMonth	int	The month day used as backup (updated when ResetToOriginalValues is set to false)
ResetToOriginalValues	bool	If start date, end date, amount, day of week, day of month will be restored to the previous values after next transaction is created

Search a recurrent transaction

> Payload example:
{

    "EndDateOperator":  "isBetween",
    "EndDateFrom": "2021-01-01",
    "EndDateTo": "2021-12-31",
    "Pagination":
    {
        "PageNumber":1
    }
}

> Response example:
{
    "statusCode":200,
    "message":"POST Request successful.",
    "isError":false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 8,
        "TotalCount": 1,
        "Items": [{
            "Id": "e60deffd-...-e9504f6a3a81",
            "CreatedAt": "2020-04-28T14:48:06.916779",
            "Memo": "",
            "Comment": "",
            "Amount": 0.01,
            "ZumRailsType": "FundZumWallet",
            "TransactionMethod": "Interac",
            "TransactionType": "Eft",
            "StartDate": "2020-08-20T00:00:00",
            "EndDate": "2021-08-28T04:00:00",
            "RecurrenceType": "Weekly",
            "DayOfWeek": "Monday",
            "DayOfMonth": null,
            "From": "Funding Source (RBC-01234-1234567)",
            "To": "Zūm Wallet",
            "UserId": null,
            "FundingSourceId": "c7f77ae5-...-14b6c3fd7ad1",
            "WalletId": "30126b59-...-008376504211",
            "OriginalStartDate": "2020-01-20T03:00:00",
            "OriginalEndDate": "2020-08-28T04:00:00",
            "OriginalAmount": 2.22,
            "OriginalDayOfWeek": "Monday",
            "OriginalDayOfMonth": null,
            "ResetToOriginalValues": false  
        }]
    }
}

Method: POST

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

Recurrent transactions are returned with pagination, which means that if you need to retrieve all recurrent transactions you need to call the same endpoint incrementing the CurrentPage.

Input parameters

Parameter	Type	Mandatory	Description
GenericSearch	string	no	Filter recurrent transactions by user name and user email
NotExpired	bool	no	If true, will retrieve only recurrent transactions that its end date is not expired
UserId	guid	no	User id
StartDateFrom	datetime	no	Recurring transaction beginning start date (This field is only used when the operator is between)
StartDateTo	datetime	no	Recurring transaction end starting date (This field is only used when the operator is between)
StartDate	datetime	no	Recurring transaction with the start date
StartDateOperator	string	no	Operator to filter with start date properties (Operators)
EndDateFrom	datetime	no	Recurring transaction beginning end date (This field is only used when the operator is between)
EndDateTo	datetime	no	Recurring transaction ending end date (This field is only used when the operator is between)
EndDate	datetime	no	Recurring transaction with the end date
EndDateOperator	string	no	Operator to filter with end date properties (Operators)
RecurrenceType	string	no	The recurrence type (Weekly, Biweekly, Monthly)
TransactionType	string	no	The transaction type
TransactionMethod	string	no	The transaction method
Pagination		no
PageNumber	number	no	The respective page, starting at 1

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
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
UserId	guid	The user id
WalletId	guid	The wallet id
FundingSourceId	guid	The funding source id
RecurrenceType	string	The frequency
DayOfWeek	string	Which day of the week transactions will be created
DayOfMonth	int	Which day transactions will be created
LastDayOfTheMonth	bool	If the transactions will be created in the last day of the month
StartDate	date	When the recurrency must begin
EndDate	date	When the recurrency must stop
From	string	Description of where funds are coming from
To	string	Description of where funds are going
OriginalStartDate	date	The start date used as backup (updated when ResetToOriginalValues is set to false)
OriginalEndDate	date	The end date used as backup (updated when ResetToOriginalValues is set to false)
OriginalAmount	decimal	The amount used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfWeek	string	The week day used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfMonth	int	The month day used as backup (updated when ResetToOriginalValues is set to false)
ResetToOriginalValues	bool	If start date, end date, amount, day of week, day of month will be restored to the previous values after next transaction is created

Editing a recurrent transaction using API

> Payload example:
{
    "StartDate": "2020-10-20",
    "EndDate": "2022-12-20",
    "DayOfWeek": "Monday",
    "Amount": 2000,
    "ResetToOriginalValues": false
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "e60deffd-...-e9504f6a3a81",
        "CreatedAt": "2020-04-28T14:48:06.916779",
        "Memo": "",
        "Comment": "",
        "Amount": 0.01,
        "ZumRailsType": "FundZumWallet",
        "TransactionMethod": "Interac",
        "StartDate": "2020-01-20T03:00:00",
        "EndDate": "2021-08-28T04:00:00",
        "RecurrenceType": "Weekly",
        "DayOfWeek": "Monday",
        "DayOfMonth": null,
        "From": "Funding Source (RBC-01234-1234567)",
        "To": "Zūm Wallet",
        "UserId": null,
        "FundingSourceId": "c7f77ae5-...-14b6c3fd7ad1",
        "WalletId": "30126b59-...-008376504211",
        "TransactionsIds": [
            "47996650-...-0d082ee63b5e",
            "d88d3f2a-...-d0a0f146d1e8"
        ],
        "OriginalStartDate": "2020-01-20T03:00:00",
        "OriginalEndDate": "2020-08-28T04:00:00",
        "OriginalAmount": 2.22,
        "OriginalDayOfWeek": "Monday",
        "OriginalDayOfMonth": null,
        "ResetToOriginalValues": false
    }
}

Method: PUT

Endpoint: {{env}}/api/recurrenttransaction/{recurrent_transaction_id}

Use this endpoint if you want to edit an existing recurrent transaction. The recurrent transaction id is informed in the url and the body payload contains the recurrent transaction information.

Input parameters

Parameter	Type	Mandatory	Description
StartDate	date	no	When the recurrency must begin. yyyy-mm-dd
EndDate	date	no	When the recurrency must stop. yyyy-mm-dd
DayOfWeek	string	yes/no	This is mandatory if you inform RecurrenceType: Bi-weekly and weekly
DayOfMonth	int	yes/no	This is mandatory if you inform RecurrenceType: Monthly and LastDayOfTheMonth: false. Must be between 1 and 28
LastDayOfTheMonth	bool	no	This is optional if RecurrenceType: Monthly. If true, the transactions will be created always in the last day of the month
Amount	decimal	yes	Transaction amount
ResetToOriginalValues	bool	yes	If true, original values won't be updated and after next transaction (from this recurrent transaction) is created, the recurrent transaction's values will be restored to the previous one

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
TransactionMethod	string	Transaction method
UserId	guid	The user id
WalletId	guid	The wallet id
FundingSourceId	guid	The funding source id
RecurrenceType	string	The frequency
DayOfWeek	string	Which day of the week transactions will be created
DayOfMonth	int	Which day transactions will be created
LastDayOfTheMonth	bool	If the transactions will be created in the last day of the month
StartDate	date	When the recurrency must begin. yyyy-mm-dd
EndDate	date	When the recurrency must stop. yyyy-mm-dd
From	string	Description of where funds are coming from
To	string	Description of where funds are going
TransactionsIds	array of guids	An array containing the ids of the transactions originated by the recurrent transaction
OriginalStartDate	date	The start date used as backup (updated when ResetToOriginalValues is set to false)
OriginalEndDate	date	The end date used as backup (updated when ResetToOriginalValues is set to false)
OriginalAmount	decimal	The amount used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfWeek	string	The week day used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfMonth	int	The month day used as backup (updated when ResetToOriginalValues is set to false)
ResetToOriginalValues	bool	If start date, end date, amount, day of week, day of month will be restored to the previous values after next transaction is created

For the DayOfWeek domain, please go to Creating a new recurrent transaction .

Delete a recurrent transaction

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

Method: DELETE

Endpoint: {{env}}/api/recurrenttransaction/{recurrent_transaction_id}

Use this endpoint if you want to delete or cancel the recurrent transaction

Transactions Batch CSV

It is also possible to create transactions by uploading it using a CSV file. The template CSV file can be found in the portal.

To be able to upload, first you need to validate the file, second upload and create transactions.

Validating transactions from batch file

> Payload example:
{
    "TransactionType": "AccountsReceivable",
    "WalletId": "30126b59-ab21-491c-8033-008376504210",
    "Bytes": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKjtzY2hlZHVsZWRfZGF0ZQpKb2huO0RvZTs7MTIzOzEyMzQ1OzEyMzQ1Njc7MTAwO0ludGVybmFsIE1lc3NhZ2U7TWVtbyBtZXNzYWdlOw=="
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "InvalidTransactions": "0",
        "Status": "Ok",
        "TotalAmount": 6,
        "Transactions": [
            {
                "AccountNumber": "12345671",
                "Amount": 1,
                "Comment": "Internal message 1",
                "CompanyName": "",
                "CustomerId": null,
                "FirstName": "John1",
                "InstitutionNumber": "123",
                "LastName": "Doe1",
                "Memo": "Memo message 1",
                "Status": "Ok",
                "TransitNumber": "23451",
            },
            {
                "AccountNumber": "12345672",
                "Amount": 2,
                "Comment": "Internal message 2",
                "CompanyName": "",
                "CustomerId": null,
                "FirstName": "John2",
                "InstitutionNumber": "123",
                "LastName": "Doe2",
                "Memo": "Memo message 2",
                "Status": "Ok",
                "TransitNumber": "23452",
            },
            {
                "AccountNumber": "12345673",
                "Amount": 3,
                "Comment": "Internal message 3",
                "CompanyName": "",
                "CustomerId": null,
                "FirstName": "John3",
                "InstitutionNumber": "123",
                "LastName": "Doe3",
                "Memo": "Memo message 3",
                "Status": "Ok",
                "TransitNumber": "23453",
            }
        ],
        "ValidTransactions": 13
    }
}

Method: POST

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

Use this endpoint if you want to validate a transactions batch file.

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

Concerning FundingSourceId and WalletId, just one of them must be sent

Response

Parameter	Type	Description
InvalidTransactions	string	The amount of invalid transactions
ValidTransactions	int	The amount of valid transactions
Status	string	The validation status
TotalAmout	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 transactions through batch file

> Payload example:
{
    "TransactionType": "AccountsReceivable",
    "WalletId": "30126b59-ab21-491c-8033-008376504210",
    "Bytes": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKjtzY2hlZHVsZWRfZGF0ZQpKb2huO0RvZTs7MTIzOzEyMzQ1OzEyMzQ1Njc7MTAwO0ludGVybmFsIE1lc3NhZ2U7TWVtbyBtZXNzYWdlOw=="
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false
}

Method: POST

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

Use this endpoint if you want to create transactions using a batch file

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

Concerning FundingSourceId and WalletId, just one of them must be sent

TransactionType

Type	Description
AccountsReceivable	Execute accounts receivable AR
AccountsPayable	Execute accounts payable AP

Request Funds - Checkout form

Zūm Request Funds, or Zūm Checkout is a prebuilt, hosted payment page optimized for conversion. You can use it to automatically onboard new users and automatically initiate online payments.

We allow you to collect payments online, accepting multiples payment methods :)

Connect checkout flow v2

Creating a request funds form - checkout form

> Payload example:
{
    "Type": "Request",
    "Amount": 100.99,
    "AmountType": "Fixed",
    "WalletId": "ccf88ec8-....-dc4d06b3d263"
    "AllowMoreThanOneTransaction": false,
    "IsRecurrent": true,
    "DayOfWeek": "Monday",
    "RecurrenceType": "Weekly",
    "EndDate": "2021-03-25T04:00:00.000Z",
    "DisplayRecurrencyQuantityInConnect": true,
    "Email": "test@zumrails.com",
    "SendEmailNotification": true
}
> Response example:
{
    "Id": "9f3aa55f-...-ce8fafa79fee",
    "CreatedAt": "2021-03-07T23:18:48.0327972Z",
    "AmountType": "Fixed",
    "Amount": 123.45,
    "CustomerId": "b0db65fd-....-55a57b9a7c69",
    "Customer": {
        "Id": "b0db65fd-....-55a57b9a7c69",
        "CompanyName": "Company Name"
    },
    "ConnectUrl": "https://app.zumrails.com/#/connect/b0db65fd-...-55a57b9a7c69/9f3aa55f-...-ce8fafa79fee",
    "QrCodeBytes": "iVBORw0KGgo...SYHH",
    "AllowMoreThanOneTransaction": false,
    "TransactionAlreadyCreated": false,
    "Email": "test@zumrails.com",
    "IsRecurrent": true,
    "RecurrenceType": "Weekly",
    "DayOfWeek": "Monday",
    "EndDate": "2021-03-25T04:00:00Z",
    "DisplayRecurrencyQuantityInConnect": true
}

Method: POST

Endpoint: {{env}}/api/requestfunds

Use this endpoint if you want to create a new Request Funds - Checkout form.

Input parameters

Parameter	Type	Required	Description
AmountType	string	yes	Determine if it's a fixed amount or variable (user inform at the checkout).
Amount	string	no	Amount, in case RequestFundsType it's fixed
WalletId	string	no	The WalletId if you want funds go to your wallet. If you want to give the user all options, do not inform the walletId.
FundingSourceId	string	no	The FundingSourceId, if you want funds go directly to your funding source
AllowMoreThanOneTransaction	boolean	no	If this request allows more than one transaction to be created, if false, the link will expired after the first use
Email	boolean	no	If informed, only this e-mail can be used to complete the request funds form. A different e-mail will be rejected
SendEmailNotification	boolean	yes	If informed, an e-mail will be sent just after this endpoint is called
IsRecurrent	bool	yes	Indicates if it's a recurrent transaction
RecurrenceType	string	yes	The frequency
DayOfWeek	string	yes/no	This is mandatory if you inform RecurrenceType: Bi-weekly and weekly
DayOfMonth	int	yes/no	This is mandatory if you inform RecurrenceType: Monthly and LastDayOfTheMonth: false. Must be between 1 and 28
LastDayOfTheMonth	bool	no	This is optional if RecurrenceType: Monthly. If true, the transactions will be created always in the last day of the month
EndDate	date	yes/no	When the recurrency must stop. yyyy-mm-dd
DisplayRecurrencyQuantityInConnect	boolean	yes	If informed, the quantity of recurrences will be displayed in Connect.

For recurrent requests, the start date will be the date the request form is completed by the end user. If this endpoint is called today, but the end user fulfill tomorrow, the start date will be tomorrow.

AmountType

Type	Description
Fixed	Amount is defined when request is created
Dynamic	Amount is defined by the end user

RecurrenceType

Type	Description
Monthly	A new transaction will be created once a month
Biweekly	A new transaction will be created once every 2 weeks
Weekly	A new transaction will be created per week

DayOfWeek

Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday

Get a specific request funds - checkout form

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "TransactionsIds": [],
        "Id": "9f3aa55f-...-ce8fafa79fee",
        "CreatedAt": "2021-03-07T23:18:48.032797",
        "Type": "Request",
        "AmountType": "Fixed",
        "Amount": 11.99,
        "CustomerId": "b0db65fd-...-55a57b9a7c69",
        "Customer": {
            "Id": "b0db65fd-...-55a57b9a7c69",
            "CompanyName": "Company Name"
        },
        "ConnectUrl": "https://app.zumrails.com/#/connect/b0db65fd-...-55a57b9a7c69/9f3aa55f-...-ce8fafa79fee",
        "QrCodeBytes": "iVBORw0KGgo...SYHH",
        "AllowMoreThanOneTransaction": false,
        "TransactionAlreadyCreated": false,
        "Email": "test@zumrails.com",
        "IsRecurrent": true,
        "RecurrenceType": "Weekly",
        "DayOfWeek": "Monday",
        "EndDate": "2021-03-25T04:00:00",
        "DisplayRecurrencyQuantityInConnect": true
    }
}

Method: GET

Endpoint: {{env}}/api/requestfunds/{request_funds_id}

Use this endpoint if you want to get all the information for a specific request funds - checkout form. The id is informed in the url.

Wallets

List all wallets

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": [
        {
            "Id": "30126b59-...-008376504211",
            "Type": "AccountsPayable",
            "Balance": 50000.88
        },
        {
            "Id": "30126b59-...-008376504210",
            "Type": "Unified",
            "Balance": 1000.50
        }
    ]
}

Method: GET

Endpoint: {{env}}/api/wallet

All the information from the Zūm Wallets can be pulled with one API call. The information includes the wallet type, the wallet ID and the balance. A useful example for this endpoint is when using a Zūm wallet for AP or AR, the Wallet ID is mandatory.

Response

Parameter	Type	Description
Id	guid	Wallet id
Type	string	Wallet type
Balance	decimal	Current balance in the wallet

Filter wallet transactions

> Payload example:
{
    "WalletId": "30126b59-...-008376504210",
    "Pagination": {
        "PageNumber": 1
    }
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": [
        {
            "CurrentPage": 1,
            "PageSize": 8,
            "TotalCount": 1,
            "Items": [
                {
                    "Id": "faa32009-...-a52cc8996b61",
                    "Description": "Funds received by Funding Source (RBC-01234-1234567)",
                    "Debit": 0,
                    "Credit": 0.01,
                    "Balance": 0.01,
                    "Type": "Credit",
                    "Authorized": true,
                    "CreatedAt": "2020-04-28T15:15:09.208515"
                }
            ]
        }
    ]
}

Method: POST

Endpoint: {{env}}/api/wallet/transactions/filter

Use this endpoint if you want to list the transactions from a specific wallet. These are the debits and credits that happened in the respective wallet.

Input parameters

Parameter	Type	Mandatory	Description
WalletId	guid	yes	Wallet id
TransactionMethod	string	no	Transaction method
ZumRailsType	string	no	Transaction Type
GenericSearch	string	no	Filter wallets by description
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	Create date
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties (Operators)
Pagination		no
PageNumber	number	no	The respective page, starting at 1

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
Id	guid	Transaction id
CreatedAt	datetime	When the transaction was created
Description	string	Transaction description
Debit	decimal	Debit amount
Credit	decimal	Credit amount
Balance	decimal	Balance at that moment
Type	string	Credit or Debit
Authorized	bool	If the transaction is completed and authorized

Webhooks

The goal of the webhooks is to give your organization a real time update on the status of users and transactions so you can automate your next call to action depending of the status of the payments.

To enable webhooks you have to open the settings page using the portal. When a URL is defined, Zūm will send a POST request each time there is a status change for:

Users (only available for customers)
Transactions (only available for customers)
Customers (only available for partners)
Recurrent Transaction (only available for customers)

> Response example:
{
    "Type": "User",
    "Data": {
        ...
    }
}

The payload has a property Type to indicate to each entity the webhook status change is coming from.

Type

Type	Description
User	Indicates the webhook call is for a user status change
Transaction	Indicates the webhook call is for a transaction status change
Customer	Indicates the webhook call is for a customer account status change
Recurrent Transaction	Indicates the webhook call is for a recurrent transaction creation

The payload sent by the webhook has the same JSON format for the get User, Transaction, Customer and Recurrent Transaction.

Verifying authenticity

When Zūm Rails sends data to external services (e.g. when triggering a webhook to a service owned by you), the payload will be authenticated with a hash-based message authentication code (HMAC).

The key used to create the HMAC is your Webhook Secret, and you verify it by running the algorithm yourself with the payload and the key to re-create the HMAC. Your Webhook Secret can be found in the portal under your settings.

The signature is always sent with the webhook in a header named zumrails-signature

You can verify the authenticity of the webhook response by using HMAC. The HMAC verification process is as follows:

You receive a POST request via the webhook
Your app computes a signature based on payload received, using your Webhook Secret
You verify that your signature matches the zumrails-signature in the request

Here are the steps to validate a request coming from Zum Rails You’ll need the zumrails-signature sent by the webhook and your key (which is your Webhook Secret):

Retrieve the zumrails-signature header
Retrieve json body of the request. Make sure you are not adding any new spaces or formats.
Using HMAC SHA256 implemented in your programming language, calculate the signature in your side. The body is the payload and the secret is your Webhook Secret.
Compare your hash with the value provided under the zumrails-signature in the request, they should match.

A few examples on how to calculate HMAC in different languages: https://github.com/danharper/hmac-examples

Retry in case of failure

In the event of a failure to deliver the webhook (!= 200) we will try again 3 times every 5 minutes in sandbox. In production we will retry 5 times every 60 minutes.

If you have anything specific in our retry policy, don't hesitate to talk with us, changes can be made.

Receiving users' financial institution details

> Response example:
{
    "Type": "Transaction",
    "Data": {
        ...
        "InteracDebtorInstitutionNumber": "999",
        "InteracDebtorInstitutionName": "Testing Financial Institution",
        "InteracDebtorFullName": "Debtor Full Name",
        ...
    }
}

For Interac transactions, you can now receive the end users' financial institution name and financial institution number which was used to complete the Interac requests. To receive this information, make sure you have configured the InteracSettledIntoWallet webhook event. (You can set this event by going to settings > webhook and API settings > Interac status change).

Idempotency

In Zūm APIs, idempotency means that requests that have been previously processed successfully are not reprocessed again. The response for the completed processing is reported instead.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests will have no effect, as these type of requests are idempotent by definition.

To submit a request with idempotent processing, add the key idempotency-key in the header. The value for this key should be a unique identifier for the message with a maximum of 36 characters (we recommend a UUID). If you don't receive a response (for example, in case of a timeout), you can safely retry the request with the same header. If we have already processed the request, the response to the first attempt will be returned without duplicating the request in our database.

Idempotency keys are persisted in Zūm Rails side for 1 hour, which means if you send the same key after 1 hour, the request will be handled as a new request.

Errors

The Zūm Rails API uses the following http error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The endpoint requested is hidden for administrators only.
404	Not Found -- The specified endpoint or entity could not be found.
429	Too Many Requests -- You reached your quota
500	Internal Server Error -- We had a problem with our server. Try again later.