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 v2

Payment Methods

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

Payment methods v2

Method Description Duration Send Funds Request Funds
EFT Eletronic funds transfers 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 identiy.

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

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.

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

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",
    "firstName": "John",
    "lastName": "Doe"
  },
  "CreditCardInformation": {
    "Number": "1234123412341234",
    "ExpireMonth": "01",
    "ExpireYear": "2020",
    "CVV": "123",
    "AddressLine1": "123 street",
    "AddressLine2": "Apartmnet 123",
    "AddressPostalCode": "A1A 1A1",
    "AddressCountry": "CAN",
    "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, this should only be used for testing purposes, in production we recommend using our Connect solution in order to reduce your PCI scope.

Input parameters

Parameter Type EFT Interac Credit Card Visa Direct 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 yes no no Phone number
BankAccountInformation yes
InstitutionNumber string yes no no no Institution Number
TransitNumber string yes no no no Transit Number
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 yes Billing address line 1
AddressLine2 string no no yes yes Billing address line 2
AddressPostalCode string no no yes yes Billing address postal code
AddressCountry string no no yes yes Billing address country
AddressCity string no no yes yes Billing address city
AddressState string no no yes yes Billing address state/province

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"
  },
  "CreditCardInformation": {
    "Number": "1234123412341234",
    "ExpireMonth": "01",
    "ExpireYear": "2020",
    "CVV": "123",
    "AddressLine1": "123 street",
    "AddressLine2": "Apartmnet 123",
    "AddressPostalCode": "A1A 1A1",
    "AddressCountry": "CAN",
    "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: 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 EFT Interac Credit Card Visa Direct 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 yes no no Phone number
BankAccountInformation yes
InstitutionNumber string yes yes no no Institution Number
TransitNumber string yes yes no no Transit Number
AccountNumber string yes yes 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 yes Billing address line 1
AddressLine2 string no no yes yes Billing address line 2
AddressPostalCode string no no yes yes Billing address postal code
AddressCountry string no no yes yes Billing address country
AddressCity string no no yes yes Billing address city
AddressState string no no yes yes Billing address state/province

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": "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": "Apartmnet 123",
            "AddressPostalCode": "A1A 1A1",
            "AddressCountry": "CAN",
            "AddressCity": "Toronto",
            "AddressState": "ON"
        },
        "TransactionsMethodsAvailable": {
            "Eft": true,
            "VisaDirect": true, 
            "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
TransactionsMethodsAvailable
Eft Boolean Indicate if this user can do EFT transactions
VisaDirect Boolean Indicate if this user can do Visa Direct 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 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 completelly erased.

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",
    "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 increamenting the CurrentPage. This endpoint will not return all user information, if you need to get a specif user information, then you need to call the user/get endpoint

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

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

  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
  7. If you want to move money between your Zūm Wallets, use ZumRailsType WalletTransfer and inform:
    • WalletId
    • TargetWalletId

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 an user to wallet",
    "UserId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-...f691024aca19",
    }
}

> Payload example VisaDirect:
{
    "ZumRailsType":"AccountsReceivable",
    "TransactionMethod": "VisaDirect",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction is just a test from an user to wallet",
    "UserId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-...f691024aca19",
    }
}

> Payload example Interac:
{
    "ZumRailsType":"AccountsReceivable",
    "TransactionMethod": "Interac",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction is just a test from an user to wallet",
    "UserId":"1d431e8b-...85452adb4eee",
    "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 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
TargetWalletId guid no The wallet that will receive money from the source wallet (WalletId), if transaction type is "WalletTransfer"
UserId guid no User Id
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

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
WalletTransfer Move money between your wallets

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 NetworkConnectionFailure InvalidRecipientEmailAddress NetworkConnectionFailure
EftFailedInsufficientFunds InvalidPayload InvalidRecipientPhoneNumberAddress InvalidPayload
EftFailedCannotLocateAccount Declined Revoked Declined
EftFailedStopPayment RejectedDebitTransferDueToInsufficientFunds
EftFailedAccountClosed RejectedDebitTransferDueToAccountRestraint
EftFailedNoDebitAllowed RejectedDebitTransferDueToAccountStatus
EftFailedFundsNotFree AccountNotAvailable
EftFailedCurrectAccountMismatch ClientsAccountHasInsufficientFunds
EftFailedPayorPayeeDeceased UnexpectedException
EftFailedFrozenAccount
EftFailedInvalidErrorAccountNumber
EftFailedErrorPayorPayeeName
EftFailedRefusedNoAgreement
EftFailedNotInAccountAgreementP
EftFailedNotInAccountAgreementE
EftFailedAgreementRevoked
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": "AccountsReceivable"
        },
        "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 (AccountsReceivable) 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)
User If transaction has a user - * Not all information from an 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 an 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 an 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
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. Depending on the transaction methods, the events will change.

Method Event Description
All Started When the transaction started
All Succeded When the transaction succed, when it finishesm 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 NetworkConnectionFailure When Visa Network is unavailable - * We have never seen this :)
VisaDirect InvalidPayload When user data is invalid and rejected by Visa
VisaDirect Declined When there's no funds available, or the account is closed
------- ------- -------
Interac InvalidRecipientEmailAddress If the email provided is not valid. * We minimize this eror by validating it before
Interac InvalidRecipientPhoneNumberAddress If the phone number provided is not valid.
Interac Revoked When the transaction is revoked
Interac RejectedDebitTransferDueToInsufficientFunds Insufficient funds while debiting - requesting funds
Interac RejectedDebitTransferDueToAccountRestraint Rejectiong due account restrictions
Interac RejectedDebitTransferDueToAccountStatus Rejectiong due account restrictions
Interac AccountNotAvailable Rejectiong due account restrictions
Interac ClientsAccountHasInsufficientFunds Insufficient funds while crediting - sending funds
Interac UnexpectedException When Interac Network is unavailable - * We have never seen this :)
------- ------- -------
CreditCard NetworkConnectionFailure When network is unavailable - * We have never seen this :)
CreditCard InvalidPayload When user data is invalid and rejected
CreditCard Declined When there's no funds available, or the account is closed

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",
    "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
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)
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
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)

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
TransactionMethod string yes Transaction method
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
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
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

Search a recurrent transaction

> Payload example:
{
    "BeginningEndDate": "2021-01-01",
    "EndingEndDate": "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",
            "TransactionType": "Eft",
            "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
UserId guid no User id
BeginningStartDate datetime no Recurring transaction creation start date
EndingStartDate datetime no Recurring transaction creation end date
BeginningEndDate datetime no Recurring transaction beginning end date
EndingEndDate datetime no Recurring transaction ending end date
RecurrenceType string no The recurrence type (Weekly, Biweekly, Monthly)
TransactionType string no The transaction type
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

Update the end date of a recurrent transaction

> Payload example:
{
    "EndDate": "2020-12-12"
}

Method: POST

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

Use this endpoint if you want to modify the end date of a recurrent transaction. The recurrent transaction id is informed in the url.

Input parameters

Parameter Type Mandatory Description
EndDate date yes The recurrent transaction's new end date

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
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",
    "WalletId": "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
WalletId string no The Wallet Id, according to TransactionType
FundingSourceId string no The Funding Source Id
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
WalletId string no The Wallet Id, according to TransactionType
FundingSourceId string no The Funding Source Id
Bytes string yes The file's blob

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:
{
  "RequestFundsType": "Fixed",
  "Amount": 123.45,
  "WalletId": "30126b59-...-008376504211"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-....-f691024aca19",
        "RequestFundsType": "Fixed",
        "Amount": 123.45,
        "WalletId": "30126b59-...-008376504211",
        "ConnectUrl": "https://sandbox.zumrails.com/connect/...",
        "QrCodeBytes": "iVBORw0K..."
    }
}

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
RequestFundsType 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
FundingSourceId string no The FundingSourceId, if you want funds go directly to your funding source

Get a specific request funds - checkout form

> Response example:
{
    "statusCode":200,
    "message":"GET Request successful.",
    "isError":false,
    "result":
    {
        "Id":"017b530c-59f6-4f87-be26-524245efa0fd",
        "CreatedAt":"2020-08-30T21:38:18.361931",
        "RequestFundsType":"Fixed",
        "Amount":123.45,
        "WalletId":"5f515f01-...-8911a7c321a4",
        "ConnectUrl":"https://sandbox.zumrails.com/#/connect/cf2ab7ae-...-be26-524245efa0fd",
        "QrCodeBytes":"iVBORw0KGg..."
        "TransactionsIds":[
            "57cb547a-...-d169d5921d6a
        "],
    }
}

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.

Response

Parameter Type Description
Id guid guid
CreatedAt datetime When the form was created
RequestFundsType string Determine if it's a fixed amount or variable (user inform at the checkout)
Amount string Amount, in case RequestFundsType it's fixed
WalletId string The WalletId if you want funds go to your wallet
FundingSourceId string The FundingSourceId, if you want funds go directly to your funding source
ConnectUrl string The url to open the request funds - checkout form
QrCodeBytes string The representation of the ConnectUrl in byte array
TransactionsIds array The list of transactions id that were initiated with this form

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 Zūm 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 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
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

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

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",
    "SendConfirmationEmail": false,
    "Password": "examplePassword123",
    "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)
SendConfirmationEmail boolean no If the customer will receive the activation email (and define the password using the link in the email)
Password string no If SendConfirmationEmail is false, customer's password is mandatory and will be defined in this parameter
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
DriversLicenseCopy Driver's License copy
ProofBusinessRegistrationCopy Proof of Business Registration copy
GovernmentPhotoId Government photo ID

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

Underwriting - Retrieve customer's documents

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": [
        {
            "Customer": {
                "Id": "30126b59-ab21-491c-8033-0083765042f2",
                "CompanyName": "Company To Test"
            },
            "Id": "ec665bd9-d16b-4160-9504-9dd7c149e406",
            "CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
            "FileName": "testfile1.xlsx",
            "UnderwritingType": "DriversLicenseCopy",
            "CreatedAt": "2020-09-30T15:33:11.001283"
        },
        {
            "Customer": {
                "Id": "30126b59-ab21-491c-8033-0083765042f2",
                "CompanyName": "Company To Test"
            },
            "Id": "bf57ba0e-cd09-42ce-8c92-605d1359aa68",
            "CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
            "FileName": "testfile2.xlsx",
            "UnderwritingType": "GovernmentPhotoId",
            "CreatedAt": "2020-09-30T15:33:04.256208"
        }
    ]
}

Method: GET

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

Use this endpoint if you want to retrieve all uploaded underwriting files from a specific customer. The customer id is informed in the url.

Response

Parameter Type Description
Id guid The underwriting id
CustomerId guid The customer id
FileName string The underwriting's file name
UnderwritingType string The underwriting's type (VoidCheque, DriversLicenseCopy, ProofBusinessRegistrationCopy or GovernmentPhotoId)
CreatedAt datetime When the underwriting was created
Customer Customer's information
Id guid Customer id
CompanyName string The company name

Underwriting - Retrieve specific underwriting file

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

Method: GET

Endpoint: {{env}}/api/underwriting/{underwriting_id}

Use this endpoint if you want to retrieve a specific underwriting file. The underwriting id is informed in the url.

Response

Type Description
string byte array A string byte array that represents the file

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.

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