NAV Navbar
json

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

Zūm Connect

Connect flow

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 and contains a prompt for the user to agree to the PAD. Then, the user will go through the financial data aggregation platform, which is currently Flinks.

Connect iframe

Your specific settings will be available under your profile in Zūm Rails portal. You need to add a DIV element and javascript file, then if you want, you can capture the zum user id by listening an event message.

Connect portal

After a user creates and links his account, you will be able to view the bank account information at the Zūm Rails portal, API, or through webhooks.

Zūm Wallet

Every Zūm Rails account comes with two Zūm Wallets.

There are two types of wallets because if your organization wants to preload your AP Accounts Payable Wallet to allow for faster payments (Zūm doesn’t need to pull the funds to initiate the push) you can keep your transaction separate from your AR Accounts Receivable wallet.

In the case of AR Accounts Receivable you can receive multiple receivables during the day and also specify an automatic daily withdraw form your AR wallet at the end of the day.

Zūm Wallets can also be used to help dictate traffic, so in the example of marketplace applications one can pull from a user AR, but then split the payment accordingly to the wallet.

Wallets

Environments

Production:

Sandbox:

API Specifics

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 successful
result The json response for your API call

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 represents 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. 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 more information about Zūm Connect, click here:

The /User endpoint allows users to be created, removed, and updated.

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",
    "firstName": "John",
    "lastName": "Doe"
  }
}
> 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. Remember that this user's bank account information won't be verified, meaning that you have to control the PAD on your side.

Input parameters

Parameter Type Mandatory Description
firstName string yes User first name
lastName string yes User last name
companyName string no Company name, in case it's a company
email string yes User e-mail
phoneNumber string no Phone number
BankAccountInformation yes
institutionNumber string yes Institution Number
transitNumber string yes Transit Number
accountNumber string yes Account Number

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

Editing a user

> Payload example:
{
  "firstName": "John",
  "lastName": "doe",
  "companyName": null,
  "email": "johndoe@zumrails.com",
  "phoneNumber": "514-123-1234",
  "BankAccountInformation": {
    "institutionNumber": "111",
    "transitNumber": "12345",
    "accountNumber": "1234567",
    "firstName": "John",
    "lastName": "Doe"
  }
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19",
        "FirstName": "John",
        "LastName": "Doe",
        "CompanyName": null
    }
}

Method: PUT

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

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

Input parameters

Parameter Type Mandatory Description
firstName string yes User first name
lastName string yes User last name
companyName string no Company name, in case it's a company
email string yes User e-mail
phoneNumber string no Phone number
BankAccountInformation yes
institutionNumber string yes Institution Number
transitNumber string yes Transit Number
accountNumber string yes Account Number

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

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": "FlinksCapital",
            "InstitutionNumber": "777",
            "TransitNumber": "77777",
            "AccountNumber": "1111000",
            "FirstName": null,
            "LastName": null,
            "AggregationStatus": "Connected",
            "LastTimeRefreshed": "2020-05-13T14:24:05.82614",
            "AggregationFailedReason": "None",
            "AggregationBalance": 50007.98
        }
    }
}

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

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

Search for a user

> Payload example:
{
    "StartCreationDate":"2020-05-13T04:00:00.000Z","EndCreationDate":"2020-05-13T04:00:00.000Z",
    "FirstName":"john",
    "LastName":"Doe",
    "Email":"johndoe@gmail.com"
}
> Response example:
{
    "statusCode":200,
    "message":"POST Request successful.",
    "isError":false,
    "result":
    [
        {
            "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

Input parameters

Parameter Type Mandatory Description
Name string no First and/or Last name
StartCreationDate xdatetime no Start date
EndCreationDate datetime no End date
Email string no User email

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
Email string Last name
BankAccountInformation
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

Zūm Rails is integrated with its aggregation partner Flinks. That way, you can use Zum 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).

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 Doe",
        "HolderCivicAddress": "1275 avenue des Canadiens-de-Montréal",
        "HolderCity": "Montréal",
        "HolderProvince": "QC",
        "HolderPostalCode": "H3B 5E8",
        "HolderCountry": "CA",
        "HolderEmail": "johndoe@flinks.io",
        "HolderPhoneNumber": "(514) 333-7777",
        "Institution": "FlinksCapital",
        "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": "77777",
                "InstitutionNumber": "777",
                "AccountNumber": "1111000",
                "Title": "Chequing CAD",
                "Balance": 50007.98,
                "Category": "Operations",
                "Type": "Chequing",
                "Currency": "CAD",
                "IsEftEligible": true
            }
        ],
        "LastRefresh": "2020-05-13T14:23:52.323512",
        "BankAccountInformationOrigin": "Flinks",
        "ProviderCardId": "694e916b-262e-4139-07db-08d7a8df789b",
        "CustomerId": "7c1d97c2-72c7-4216-a10b-a2a23af28e24"
    }
}

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
BankAccountInformationOrigin string Aggregation provider
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

Transactions

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

  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
> Payload example:
{
    "Amount":123.45,
    "ZumRailsType": "AccountsPayable",
    "Memo":"This is a test",
    "Comment":"",
    "FundingSourceId":"f55cd40b-...-6f7e40192b70",
    "User": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "johndoe@zumrails.com",
        "BankAccountInformation": {
            "institutionNumber": "001",
            "transitNumber": "12345",
            "accountNumber": "1234567"
        }
    }
}

If you want to create a new user directly while creating a transaction, instead of informting the UserId, you can inform a new user object itself. This will create a new user and the aggregation status will be, not connected.

Creating a new transaction

> Payload example:
{
    "ZumRailsType":"FundZumWallet",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction is just a test",
    "FundingSourceId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297"
}
> 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
Amount string 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

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

Keywords to simulate a transaction failure

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 the platform",
        "Amount": 123.45,
        "User": null,
        "Wallet": {
            "Id": "8ebd932b...b92633e14297",
            "Type": "AccountsReceivable"
        },
        "FundingSource": {
            "Id": "1d431e8b...85452adb4eee",
            "Institution": "FlinksCapital",
            "InstitutionNumber": "777",
            "TransitNumber": "77777",
            "AccountNumber": "1111000"
        },
        "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 (AccountsReceivable) with amount: $123.45",
            }
        ],
        "ZumRailsType": "FundZumWallet",
        "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)
User
Id guid The user id
First Name string User first name
Last Name string User last name
Company Name string User company name
Wallet
Id guid The wallet id
Type string The wallet type
FundingSource
Id guid The funding source id
Institution string The institution name
FundingSource The transaction history events
EventHistory
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
Failed Indicates the transaction has failed

Transaction Events

Zūm Rails also offers a more detailed transaction event, to indicate every step the transaction passed. Not all events are described here. Contact us if you want a more detailed list.

Event Description
Started When the transaction started
Succeded When the transaction succed, when it finish
EFTFileCreated When an EFT file is created. One transaction might have up to 2 files
EFTFileUploaded When an EFT file is uploaded
EFTAnswerReceived When an EFT file response is received
EFTAnswerProcessed When an EFT file is processed
WalletFunded When the transaction funds a wallet
WalletWithdrawn When the transaction withdrawn a wallet
EftFailedValidationRejection When EFT could not be created, due an invalid information provided
EftFailedInsufficientFunds When transaction is rejected, due non sufficient funds available
EftFailedCannotLocateAccount When account is not located, account, transit or institution numbers are invalid
EftFailedStopPayment Account do not allow EFT
EftFailedAccountClosed When account is closed
EftFailedNoDebitAllowed Account do not allow EFT
EftFailedFundsNotFree When transaction is rejected, due non sufficient funds available
EftFailedCurrectAccountMismatch When account is not located, account, transit or institution numbers are invalid
EftFailedPayorPayeeDeceased Account do not allow EFT
EftFailedFrozenAccount Account do not allow EFT
EftFailedInvalidErrorAccountNumber When account is not located, account numbers are invalid
EftFailedErrorPayorPayeeName When account is not located, first, last or company name (business) mismatch
EftFailedRefusedNoAggrement Account do not allow EFT
EftFailedNotInAccountAggrementP Account do not allow EFT
EftFailedNotInAccountAgreementE Account do not allow EFT
EftFailedAgreementRevoked Account do not allow EFT
EftFailedDefaultByAFinancialInstitution Generic error provided by the financial institution

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 increamenting the CurrentPage.

> Payload example:
{
    "Id": "c7a8a909...364e8836409d",
    "StartCreationDate":"2020-05-13T04:00:00.000Z",
    "EndCreationDate":"2020-05-13T04:00:00.000Z",
    "UserId":"4085e4dc...20522aab5e1b",
    "ZumRailsType":"FundZumWallet",
    "TransactionStatus":"Completed",
    "FailedTransactionEvent" : "EftFailedValidationRejection",
    "Pagination": {
        "PageNumber": 1
    }
}
> Response example:
{
    "statusCode":200,
    "message":"POST Request successful.",
    "isError":false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 8,
        "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",
                "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",
                "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
ZumRailsType string no Transaction type
TransactionStatus string no Transaction status
FailedTransactionEvent string no Transaction event (column Event from the "Transaction Events" table)
StartCreationDate datetime no Start date
EndCreationDate datetime no End date
UserId string no User id
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
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)

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",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction is just a test",
    "FundingSourceId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297",
    "IsRecurrent": true,
    "RecurrenceType": "Montly",
    "DayOfWeek": "Monday",
    "DayOfMonth": "1",
    "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
Amount string yes Transaction amount
Memo string no Memo description
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
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
EndDate date yes 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

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",
        "EndDate": "2021-08-28T04:00:00",
        "RecurrenceType": "Weekly",
        "DayOfWeek": "Monday",
        "DayOfMonth": null,
        "From": "Funding Source (RBC-01234-1234567)",
        "To": "Zūm Wallet (AccountsPayable)",
        "UserId": null,
        "FundingSourceId": "c7f77ae5-...-14b6c3fd7ad1",
        "WalletId": "30126b59-...-008376504211",
        "TransactionsIds": [
            "47996650-...-0d082ee63b5e",
            "d88d3f2a-...-d0a0f146d1e8"
        ]
    }
}

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

List all recurrent transactions

> 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",
            "EndDate": "2021-08-28T04:00:00",
            "RecurrenceType": "Weekly",
            "DayOfWeek": "Monday",
            "DayOfMonth": null,
            "From": "Funding Source (RBC-01234-1234567)",
            "To": "Zūm Wallet (AccountsPayable)",
            "UserId": null,
            "FundingSourceId": "c7f77ae5-...-14b6c3fd7ad1",
            "WalletId": "30126b59-...-008376504211"
        }]
    }
}

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 increamenting the CurrentPage.

Input parameters

Parameter Type Mandatory Description
NotExpired bool no If true, will retrieve only recurrent transactions that its end date is not expired
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
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

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",
    "WalletAndFundingSource": "30126b59-ab21-491c-8033-008376504210",
    "Bytes": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKg0KSm9objE7RG9lMTs7MTIzOzIzNDUxOzEyMzQ1NjcxOzEwMDtJbnRlcm5hbCBtZXNzYWdlIDE7TWVtbyBtZXNzYWdlIDENCkpvaG4yO0RvZTI7OzEyMzsyMzQ1MjsxMjM0NTY3MjsyMDA7SW50ZXJuYWwgbWVzc2FnZSAyO01lbW8gbWVzc2FnZSAyDQpKb2huMztEb2UzOzsxMjM7MjM0NTM7MTIzNDU2NzM7MzAwO0ludGVybmFsIG1lc3NhZ2UgMztNZW1vIG1lc3NhZ2UgMw0KSm9objQ7RG9lNDs7MTIzOzIzNDU0OzEyMzQ1Njc0OzQwMDtJbnRlcm5hbCBtZXNzYWdlIDQ7TWVtbyBtZXNzYWdlIDQNCkpvaG41O0RvZTU7OzEyMzsyMzQ1NTsxMjM0NTY3NTs1MDA7SW50ZXJuYWwgbWVzc2FnZSA1O01lbW8gbWVzc2FnZSA1IA0KSm9objY7RG9lNjs7MTIzOzIzNDU2OzEyMzQ1Njc2OzYwMDtJbnRlcm5hbCBtZXNzYWdlIDY7TWVtbyBtZXNzYWdlIDYNCkpvaG43O0RvZTc7OzEyMzsyMzQ1NzsxMjM0NTY3Nzs3MDA7SW50ZXJuYWwgbWVzc2FnZSA3O01lbW8gbWVzc2FnZSA3DQpKb2huODtEb2U4OzsxMjM7MjM0NTg7MTIzNDU2Nzg7ODAwO0ludGVybmFsIG1lc3NhZ2UgODtNZW1vIG1lc3NhZ2UgOA0KSm9objk7RG9lOTs7MTIzOzIzNDU5OzEyMzQ1Njc5OzkwMDtJbnRlcm5hbCBtZXNzYWdlIDk7TWVtbyBtZXNzYWdlIDkNCkpvaG4xMDtEb2UxMDs7MTIzOzM0NTEwOzEyMzQ1NjcxMDsxMDAwO0ludGVybmFsIG1lc3NhZ2UgMTA7TWVtbyBtZXNzYWdlIDEwDQo7O0NvbXBhbnkxMTsxMjM7MjM0MTE7MTIzNDU2NzExOzExMDA7SW50ZXJuYWwgbWVzc2FnZSAxMTtNZW1vIG1lc3NhZ2UgMTENCkpvaG4xMjtEb2UxMjs7MTIzOzIzNDEyOzEyMzQ1NjcxMjsxMjAwO0ludGVybmFsIG1lc3NhZ2UgMTI7TWVtbyBtZXNzYWdlIDEyDQpKb2huMTM7RG9lMTM7OzEyMzsyMzQxMzsxMjM0NTY3MTM7MTMwMDtJbnRlcm5hbCBtZXNzYWdlIDEzO01lbW8gbWVzc2FnZSAxMyA="
}
> 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
WalletAndFundingSource string yes Wallet Id - Only batches CSV from and to wallet are supported now
Bytes string yes The file's blob

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",
    "WalletAndFundingSource": "30126b59-ab21-491c-8033-008376504210",
    "Bytes": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKg0KSm9objE7RG9lMTs7MTIzOzIzNDUxOzEyMzQ1NjcxOzEwMDtJbnRlcm5hbCBtZXNzYWdlIDE7TWVtbyBtZXNzYWdlIDENCkpvaG4yO0RvZTI7OzEyMzsyMzQ1MjsxMjM0NTY3MjsyMDA7SW50ZXJuYWwgbWVzc2FnZSAyO01lbW8gbWVzc2FnZSAyDQpKb2huMztEb2UzOzsxMjM7MjM0NTM7MTIzNDU2NzM7MzAwO0ludGVybmFsIG1lc3NhZ2UgMztNZW1vIG1lc3NhZ2UgMw0KSm9objQ7RG9lNDs7MTIzOzIzNDU0OzEyMzQ1Njc0OzQwMDtJbnRlcm5hbCBtZXNzYWdlIDQ7TWVtbyBtZXNzYWdlIDQNCkpvaG41O0RvZTU7OzEyMzsyMzQ1NTsxMjM0NTY3NTs1MDA7SW50ZXJuYWwgbWVzc2FnZSA1O01lbW8gbWVzc2FnZSA1IA0KSm9objY7RG9lNjs7MTIzOzIzNDU2OzEyMzQ1Njc2OzYwMDtJbnRlcm5hbCBtZXNzYWdlIDY7TWVtbyBtZXNzYWdlIDYNCkpvaG43O0RvZTc7OzEyMzsyMzQ1NzsxMjM0NTY3Nzs3MDA7SW50ZXJuYWwgbWVzc2FnZSA3O01lbW8gbWVzc2FnZSA3DQpKb2huODtEb2U4OzsxMjM7MjM0NTg7MTIzNDU2Nzg7ODAwO0ludGVybmFsIG1lc3NhZ2UgODtNZW1vIG1lc3NhZ2UgOA0KSm9objk7RG9lOTs7MTIzOzIzNDU5OzEyMzQ1Njc5OzkwMDtJbnRlcm5hbCBtZXNzYWdlIDk7TWVtbyBtZXNzYWdlIDkNCkpvaG4xMDtEb2UxMDs7MTIzOzM0NTEwOzEyMzQ1NjcxMDsxMDAwO0ludGVybmFsIG1lc3NhZ2UgMTA7TWVtbyBtZXNzYWdlIDEwDQo7O0NvbXBhbnkxMTsxMjM7MjM0MTE7MTIzNDU2NzExOzExMDA7SW50ZXJuYWwgbWVzc2FnZSAxMTtNZW1vIG1lc3NhZ2UgMTENCkpvaG4xMjtEb2UxMjs7MTIzOzIzNDEyOzEyMzQ1NjcxMjsxMjAwO0ludGVybmFsIG1lc3NhZ2UgMTI7TWVtbyBtZXNzYWdlIDEyDQpKb2huMTM7RG9lMTM7OzEyMzsyMzQxMzsxMjM0NTY3MTM7MTMwMDtJbnRlcm5hbCBtZXNzYWdlIDEzO01lbW8gbWVzc2FnZSAxMyA="
}
> 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
WalletAndFundingSource string yes Wallet Id - Only batches CSV from and to wallet are supported now
Bytes string yes The file's blob

TransactionType

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

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": "AccountsReceivable",
            "Balance": 1000.50
        }
    ]
}

Method: GET

Endpoint: {{env}}/api/wallet

All the information from the Zum Wallets can be pulled with one API call. The information includes the wallet type (AP or AR), the wallet ID and the balance. A useful example for this endpoint is when using a Zum 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
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:

> 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 wehbook call is for a user status change
Transaction Indicates the wehbook call is for a transaction status change

The payload sent by the webhook has the same JSON format for the get User and get 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 API password, and you verify it by running the algorithm yourself with the payload and the key to re-create the HMAC.

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

Calculate an HMAC using:

  1. The HMAC using SHA256 function;
  2. Binary representation of the payload received, given the UTF-8 charset.
  3. Binary representation of the HMAC key (your api password), given the UTF-8 charset.

Finally, compare signatures, the one received in the header zumrails-signature should match with the one calculated by you.

Retry in case of failure

In the event of a failure to delivery 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, changed can be made.

Partners

f you have multiple sub-accounts and want to group and organize information for each one of your clients, you need a partner account (also known as master account). In the partner portal, it’s possible to create and manage accounts for each client individually.

A partner can not create users or transactions. A partner can create their own customers, and each one of these customers has a unique portal and set of api keys. The information is not shared between customers, but you can view them all in the partner portal. Partner

With the partner portal credentials in hand, you’ll first need to authorize with the api keys found in your /settings page. After that, you can call most of the APIs described here to view information from each one of your customers.

Need a partner account? Talk with us, it take seconds to send you a partner account invitation.

Creating a new customer

> Payload example:
{
    "CompanyName": "Example Customer Company",
    "TransactionDescriptionType": "Fixed",
    "TransactionDescription": "Description",
    "FirstName": "John",
    "LastName": "Doe",
    "PhoneNumber": "514-123-1234",
    "Email": "examplecompany@zumrails.com",
    "CustomerBillingType": "BuyRate",
    "MonthlyCost": 16,
    "CostPerTransaction": 1,
    "CostPerUser": 2,
    "CostPerBankRefresh": 4,
    "CostPerNSF": 8,
    "WebhookConfigurations": 
    [
        {
            "WebhookType": "Transaction",
            "StatusValue": 8
        },
        {
            "WebhookType": "User",
            "StatusValue": 1
        }
    ]
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "f60d848a-5a45-4649-8968-48a83332d5bd",
        "CompanyName": "Example Customer Company",
        "TransactionDescriptionType": "Fixed",
        "TransactionDescription": "Description",
        "FirstName": "John",
        "LastName": "Doe",
        "Email": "examplecompany10@zumrails.com",
        "PhoneNumber": "514-123-1234",
        "AddressStreet": null,
        "AddressCity": null,
        "AddressProvince": null,
        "AddressPostalCode": null,
        "MonthlyCost": 16,
        "CostPerTransaction": 1,
        "CostPerUser": 2,
        "CostPerBankRefresh": 4,
        "CostPerNSF": 8,
        "PercentagePerTransaction": 0,
        "PercentagePerUser": 0,
        "PercentagePerBankRefresh": 0,
        "PercentagePerNSF": 0,
        "CustomerAccountStatus": "PendingActivation",
        "CustomerBillingType": "BuyRate",
        "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
        "WebhookUrl": null,
        "WebhookConfigurations":
        [
            {
                "WebhookType": "Transaction",
                "Name": "Succeeded",
                "StatusValue": 8
            },
            {
                "WebhookType": "User",
                "Name": "Connected",
                "StatusValue": 1
            }
        ],
        "ActivationDate": null,
        "CreatedAt": "2020-08-24T12:31:29.9359515Z"
    }
}

Method: POST

Endpoint: {{env}}/api/customer

Use this endpoint if you want to add a new customer to your partner account.

Input parameters

Parameter Type Mandatory Description
CompanyName string yes Name of the customer company
TransactionDescriptionType Transaction Description Type yes Defines whether the transaction's bank statements will be fixed or different for each transaction
TransactionDescription string yes if TransactionDescriptionType is "Fixed" The description which will appear on the bank statements transactions (maximum of 15 characters: only letters, numbers, dash, space and underscore are allowed)
FirstName string yes First name of the company owner
LastName string yes Last name of the company owner
PhoneNumber string yes Phone number
Email e-mail yes E-mail of the company (will be used as the customer login)
AddressStreet string no Address street
AddressCity string no Address city
AddressProvince string no Address province
AddressPostalCode string no Address postal code
WebhookUrl string no Url to receive webhooks
CustomerBillingType Customer Billing Type yes Defines how the billing will work (must be the same as the partner)
MonthlyCost number yes Monthly cost of the customer
CostPerTransaction number yes Cost/Percentage per transaction completed of the customer (must be greater than the partners cost per transaction)
CostPerUser number yes Cost/Percentage per user added of the customer (must be greater than the partners cost per user)
CostPerBankRefresh number yes Cost/Percentage per aggregation of the customer (must be greater than the partners cost per aggregation)
CostPerNSF number yes Cost/Percentage per NSF of the customer (must be greater than the partners cost per NSF)
WebhookConfigurations list of Webhook Configurations no A list containing webhook configurations. For more information, check Webhooks
WebhookType Webhook Type yes Type of the webhook
StatusValue int yes Value of the webhook

Transaction Description Type

Type Description
Fixed The string defined on the customer field "TransactionDescription" will be displayed on the bank statements
PerTransaction The bank statement of each transaction will be the content of the "Memo" transaction field

Customer Billing Type

Type Description
BuyRate Fixed value for each operation
PercentageSplit Percentage from the quantity of each operation - Not available right now

Webhook Configurations

WebhookType Value Name
User 0 NotConnected
User 1 Connected
User 2 Connecting
User 3 Refreshing
User 4 RefreshFailed
Transaction 1 Started
Transaction 8 Succeeded
Transaction 900 EftFailedValidationRejection
Transaction 901 EftFailedInsufficientFunds
Transaction 902 EftFailedCannotLocateAccount
Transaction 903 EftFailedStopPayment
Transaction 905 EftFailedAccountClosed
Transaction 907 EftFailedNoDebitAllowed
Transaction 908 EftFailedFundsNotFree
Transaction 909 EftFailedCurrectAccountMismatch
Transaction 910 EftFailedPayorPayeeDeceased
Transaction 911 EftFailedFrozenAccount
Transaction 912 EftFailedInvalidErrorAccountNumber
Transaction 914 EftFailedErrorPayorPayeeName
Transaction 915 EftFailedRefusedNoAggreement
Transaction 917 EftFailedAgreementRevokedP
Transaction 920 EftFailedAgreementRevoked
Transaction 990 EftFailedDefaultByAFinancialInstitution

Response

Parameter Type Description
Id guid Customer id
CompanyName string The company name
TransactionDescriptionType Transaction Description Type Defines if the transactions bank statements will be fixed or different for each transaction
TransactionDescription string The description which will appear on the bank statements transactions (if Transaction Description Type is Fixed)
FirstName string First name of the company owner
LastName string Last name of the company owner
PhoneNumber string Phone number
Email e-mail E-mail of the company (also customer login)
AddressStreet string Address street
AddressCity string Address city
AddressProvince string Address province
AddressPostalCode string Address postal code
WebhookUrl string Url to receive webhooks
CustomerBillingType Customer Billing Type Defines how the billing will work
MonthlyCost number Monthly cost of the customer
CostPerTransaction number Cost per transaction completed of the customer (must be greater than the partners cost per transaction)
CostPerUser number Cost per user added of the customer (must be greater than the partners cost per user)
CostPerBankRefresh number Cost per aggregation of the customer (must be greater than the partners cost per aggregation)
CostPerNSF number Cost per NSF of the customer (must be greater than the partners cost per NSF)
PercentagePerTransaction number Percentage per transaction completed of the customer (must be greater than the partners cost per transaction)
PercentagePerUser number Percentage per user added of the customer (must be greater than the partners cost per user)
PercentagePerBankRefresh number Percentage per aggregation of the customer (must be greater than the partners cost per aggregation)
PercentagePerNSF number Percentage per NSF of the customer (must be greater than the partners cost per NSF)
PartnerId guid Partner id
ActivationDate datetime The date when the customer was activated
CreatedAt datetime When the customer was created
CustomerAccountStatus Customer Account Status The customer account status
WebhookConfigurations List of webhook configurations of the customer
WebhookType Webhook Type Type of the webhook
Name string Name of the webhook
StatusValue int Value of the webhook

Customer Account Status

Type Description
Active Customer is active and ready to create transactions
PendingFundingSource Customer needs a funding source (add it via aggregation)
PendingActivation Customer needs to activate account (check e-mail for activation instructions)
PendingUnderwriting Customer needs an underwriting (upload it through the settings menu or through API)

Webhook Type

Type Description
User Webhook triggered by user operations
Transaction Webhook triggered by transaction operations

Editing a customer

> Request example:
{
    "CompanyName": "Example Customer Company",
    "TransactionDescriptionType": "Fixed",
    "TransactionDescription": "Description",
    "FirstName": "John",
    "LastName": "Doe",
    "PhoneNumber": "514-123-1234",
    "Email": "examplecompany@zumrails.com",
    "CustomerBillingType": "BuyRate",
    "MonthlyCost": 20,
    "CostPerTransaction": 1,
    "CostPerUser": 2,
    "CostPerBankRefresh": 4,
    "CostPerNSF": 16,
    "AddressCity": "City",
    "AddressPostalCode": "88888888",
    "AddressProvince": "Province",
    "AddressStreet": "Street"
}
> Response example:
{
    "statusCode": 200,
    "message": "PUT Request successful.",
    "isError": false,
    "result": {
        "Id": "f60d848a-5a45-4649-8968-48a83332d5bd",
        "CompanyName": "Example Customer Company",
        "TransactionDescriptionType": "Fixed",
        "TransactionDescription": "Description",
        "FirstName": "John",
        "LastName": "Doe",
        "Email": "examplecompany10@zumrails.com",
        "PhoneNumber": "514-123-1234",
        "AddressCity": "City",
        "AddressPostalCode": "88888888",
        "AddressProvince": "Province",
        "AddressStreet": "Street",
        "MonthlyCost": 20,
        "CostPerTransaction": 1,
        "CostPerUser": 2,
        "CostPerBankRefresh": 4,
        "CostPerNSF": 16,
        "PercentagePerTransaction": 0,
        "PercentagePerUser": 0,
        "PercentagePerBankRefresh": 0,
        "PercentagePerNSF": 0,
        "CustomerAccountStatus": "Active",
        "CustomerBillingType": "BuyRate",
        "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
        "WebhookUrl": null,
        "WebhookConfigurations": [],
        "ActivationDate": null,
        "CreatedAt": "2020-08-24T12:31:29.935951"
    }
}

Method: PUT

Endpoint: {{env}}/api/customer/{customer_id}

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

Input parameters

Parameter Type Mandatory Description
CompanyName string yes Name of the customer company
TransactionDescriptionType Transaction Description Type yes Defines whether the transaction's bank statements will be fixed or different for each transaction
TransactionDescription string yes if TransactionDescriptionType is "Fixed" The description which will appear on the bank statement's transactions (maximum of 15 characters: only letters, numbers, dash, space and underscore are allowed)
FirstName string yes First name of the company owner
LastName string yes Last name of the company owner
PhoneNumber string yes Phone number
Email e-mail yes E-mail of the company (will be used as the customer login)
AddressStreet string no Address street
AddressCity string no Address city
AddressProvince string no Address province
AddressPostalCode string no Address postal code
WebhookUrl string no Url to receive webhooks
CustomerBillingType Customer Billing Type yes Defines how the billing will work (must be the same as the partner)
MonthlyCost number yes Monthly cost of the customer
CostPerTransaction number yes Cost/Percentage per transaction completed of the customer (must be greater than the partners cost per transaction)
CostPerUser number yes Cost/Percentage per user added of the customer (must be greater than the partners cost per user)
CostPerBankRefresh number yes Cost/Percentage per aggregation of the customer (must be greater than the partners cost per aggregation)
CostPerNSF number yes Cost/Percentage per NSF of the customer (must be greater than the partners cost per NSF)
WebhookConfigurations list of Webhook Configurations yes A list containing webhook configurations. For more information, check Webhooks
WebhookType Webhook Type yes Type of the webhook
StatusValue int yes Value of the webhook

Response

Parameter Type Description
Id guid Customer id
CompanyName The company name
TransactionDescriptionType Transaction Description Type Defines if the transactions bank statements will be fixed or different for each transaction
TransactionDescription string The description which will appear on the bank statements transactions (if Transaction Description Type is Fixed)
FirstName string First name of the company owner
LastName string Last name of the company owner
PhoneNumber string Phone number
Email e-mail E-mail of the company (also customer login)
AddressStreet string Address street
AddressCity string Address city
AddressProvince string Address province
AddressPostalCode string Address postal code
WebhookUrl string Url to receive webhooks
CustomerBillingType Customer Billing Type Defines how the billing will work
MonthlyCost number Monthly cost of the customer
CostPerTransaction number Cost per transaction completed of the customer (must be greater than the partners cost per transaction)
CostPerUser number Cost per user added of the customer (must be greater than the partners cost per user)
CostPerBankRefresh number Cost per aggregation of the customer (must be greater than the partners cost per aggregation)
CostPerNSF number Cost per NSF of the customer (must be greater than the partners cost per NSF)
PercentagePerTransaction number Percentage per transaction completed of the customer (must be greater than the partners cost per transaction)
PercentagePerUser number Percentage per user added of the customer (must be greater than the partners cost per user)
PercentagePerBankRefresh number Percentage per aggregation of the customer (must be greater than the partners cost per aggregation)
PercentagePerNSF number Percentage per NSF of the customer (must be greater than the partners cost per NSF)
PartnerId guid Partner id
ActivationDate datetime The date when the customer was activated
CreatedAt datetime When the customer was created
CustomerAccountStatus Customer Account Status The customer account status
WebhookConfigurations List of webhook configurations of the customer
WebhookType Webhook Type Type of the webhook
Name string Name of the webhook
StatusValue int Value of the webhook

Get a specific customer

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "Id": "f60d848a-5a45-4649-8968-48a83332d5bd",
        "CompanyName": "Example Customer Company",
        "TransactionDescriptionType": "Fixed",
        "TransactionDescription": "Description",
        "FirstName": "John",
        "LastName": "Doe",
        "Email": "examplecompany20@zumrails.com",
        "PhoneNumber": "514-123-1234",
        "AddressStreet": "Street",
        "AddressCity": "City",
        "AddressProvince": "Province",
        "AddressPostalCode": "88888888",
        "MonthlyCost": 16,
        "CostPerTransaction": 1,
        "CostPerUser": 2,
        "CostPerBankRefresh": 4,
        "CostPerNSF": 8,
        "PercentagePerTransaction": 0,
        "PercentagePerUser": 0,
        "PercentagePerBankRefresh": 0,
        "PercentagePerNSF": 0,
        "CustomerAccountStatus": "Active",
        "CustomerBillingType": "BuyRate",
        "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
        "WebhookUrl": null,
        "WebhookConfigurations": [],
        "ActivationDate": null,
        "CreatedAt": "2020-08-24T12:31:29.935951"
    }
}

Method: GET

Endpoint: {{env}}/api/customer/{customer_id}

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

Response

Parameter Type Description
Id guid Customer id
CompanyName The company name
TransactionDescriptionType Transaction Description Type Defines if the transactions bank statements will be fixed or different for each transaction
TransactionDescription string The description which will appear on the bank statements transactions (if Transaction Description Type is Fixed)
FirstName string First name of the company owner
LastName string Last name of the company owner
PhoneNumber string Phone number
Email e-mail E-mail of the company (also customer login)
AddressStreet string Address street
AddressCity string Address city
AddressProvince string Address province
AddressPostalCode string Address postal code
WebhookUrl string Url to receive webhooks
CustomerBillingType Customer Billing Type Defines how the billing will work
MonthlyCost number Monthly cost of the customer
CostPerTransaction number Cost per transaction completed of the customer (must be greater than the partners cost per transaction)
CostPerUser number Cost per user added of the customer (must be greater than the partners cost per user)
CostPerBankRefresh number Cost per aggregation of the customer (must be greater than the partners cost per aggregation)
CostPerNSF number Cost per NSF of the customer (must be greater than the partners cost per NSF)
PercentagePerTransaction number Percentage per transaction completed of the customer (must be greater than the partners cost per transaction)
PercentagePerUser number Percentage per user added of the customer (must be greater than the partners cost per user)
PercentagePerBankRefresh number Percentage per aggregation of the customer (must be greater than the partners cost per aggregation)
PercentagePerNSF number Percentage per NSF of the customer (must be greater than the partners cost per NSF)
PartnerId guid Partner id
ActivationDate datetime The date when the customer was activated
CreatedAt datetime When the customer was created
CustomerAccountStatus Customer Account Status The customer account status
WebhookConfigurations List of webhook configurations of the customer
WebhookType Webhook Type Type of the webhook
Name string Name of the webhook
StatusValue int Value of the webhook

Delete for a customer

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

Method: DELETE

Endpoint: {{env}}/api/customer

Use this endpoint if you want to delete a specific customer

Search a customer

> Request example:
{
    "CustomerId": "49a5b2ef-4297-4b22-b97e-c0ce677dbc66",
    "Email": "example",
    "Status": "PendingActivation",
    "Pagination": {
        "PageNumber": 1
    }
}    
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 8,
        "TotalCount": 1,
        "Items": [
            {
                "Id": "49a5b2ef-4297-4b22-b97e-c0ce677dbc66",
                "CompanyName": "Example Customer Company",
                "TransactionDescriptionType": "Fixed",
                "TransactionDescription": "Description",
                "FirstName": "John",
                "LastName": "Doe",
                "Email": "examplecompany7@zumrails.com",
                "PhoneNumber": "514-123-1234",
                "AddressStreet": null,
                "AddressCity": null,
                "AddressProvince": null,
                "AddressPostalCode": null,
                "MonthlyCost": 16,
                "CostPerTransaction": 1,
                "CostPerUser": 2,
                "CostPerBankRefresh": 4,
                "CostPerNSF": 8,
                "PercentagePerTransaction": 0,
                "PercentagePerUser": 0,
                "PercentagePerBankRefresh": 0,
                "PercentagePerNSF": 0,
                "CustomerAccountStatus": "PendingActivation",
                "CustomerBillingType": "BuyRate",
                "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
                "WebhookUrl": null,
                "WebhookConfigurations": [],
                "ActivationDate": null,
                "CreatedAt": "2020-08-21T19:03:11.474714"
            }
        ]
    }
}

Method: POST

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

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

Input parameters

Parameter Type Mandatory Description
CustomerId string no Customer id
Email string no Customer e-mail
Status Customer Status no The status of the customer
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 Customer id
CompanyName The company name
TransactionDescriptionType Transaction Description Type Defines if the transactions bank statements will be fixed or different for each transaction
TransactionDescription string The description which will appear on the bank statements transactions (if Transaction Description Type is Fixed)
FirstName string First name of the company owner
LastName string Last name of the company owner
PhoneNumber string Phone number
Email e-mail E-mail of the company (also customer login)
AddressStreet string Address street
AddressCity string Address city
AddressProvince string Address province
AddressPostalCode string Address postal code
WebhookUrl string Url to receive webhooks
CustomerBillingType Customer Billing Type Defines how the billing will work
MonthlyCost number Monthly cost of the customer
CostPerTransaction number Cost per transaction completed of the customer (must be greater than the partners cost per transaction)
CostPerUser number Cost per user added of the customer (must be greater than the partners cost per user)
CostPerBankRefresh number Cost per aggregation of the customer (must be greater than the partners cost per aggregation)
CostPerNSF number Cost per NSF of the customer (must be greater than the partners cost per NSF)
PercentagePerTransaction number Percentage per transaction completed of the customer (must be greater than the partners cost per transaction)
PercentagePerUser number Percentage per user added of the customer (must be greater than the partners cost per user)
PercentagePerBankRefresh number Percentage per aggregation of the customer (must be greater than the partners cost per aggregation)
PercentagePerNSF number Percentage per NSF of the customer (must be greater than the partners cost per NSF)
PartnerId guid Partner id
ActivationDate datetime The date when the customer was activated
CreatedAt datetime When the customer was created
CustomerAccountStatus Customer Account Status The customer account status
WebhookConfigurations List of webhook configurations of the customer
WebhookType Webhook Type Type of the webhook
Name string Name of the webhook
StatusValue int Value of the webhook

Underwriting - Upload a document

> Request example:
{ 
    "FileName": "File.txt",
    "CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
    "UnderwritingType": "VoidCheque",
    "Bytes": "dGVzdA=="    
}
> Response example:
{
    "isError": false,
    "message": "POST Request successful.",
    "statusCode": 200,
    "result": {
        "CreatedAt": "2020-08-21T20:33:41.8367114Z",
        "FileName": "File.txt",
        "CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
        "Id": "f6ba6f0a-cd6d-47c3-b9b4-2d9f8d406870",
        "UnderwritingType": "VoidCheque"        
    }
}

Method: POST

Endpoint: {{env}}/api/underwriting

Use this endpoint if you want to upload an underwriting file for a specific customer.

Input parameters

Parameter Type Mandatory Description
FileName string yes The name of the file
CustomerId guid yes Customer id
UnderwritingType Underwriting Type yes The type of the underwriting file
Bytes string byte array yes A string byte array that represents the file

Underwriting Type

Type Description
VoidCheque Void cheque

Response

Parameter Type Description
Id guid Underwriting id
FileName string The name of the file
CustomerId guid Customer id
UnderwritingType Underwriting Type The type of the underwriting file
CreatedAt date When the underwriting was created

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