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.

Pre-filling the form

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

Name Description
accountType Personal or Business
firstName User first name, when the account type is Personal
lastName User last name, when the account type when is Personal
email User email
companyName Company name, when the account type is Business
memo Transaction memo that will be created with the request funds.
comment Transaction comment that will be created with the request funds.
allowEft To display only EFT payment method.
allowInterac To display only INTERAC payment method.
allowVisaDirect To display only VISA DIRECT payment method.
allowCreditCard To display only CREDIT CARD payment method.
displayTermsAndCondition To display the terms and conditions checkbox or not.
displayDetailsColumn To display the left side column with transaction details, amount and recurrency
displayZumRailsLogo To display the powered by Zũm Rails logo
displayPhoneNumber To display the phone number field

Examples:

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

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

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

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

Event Listener

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

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

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

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

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

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

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

Zūm Wallet

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

If you’re using EFT and/or Interac: Zūm Wallet - EFT Interac
If you’re using Visa Direct: Zūm Wallet - Visa Direct
If you’re using credit cards: Zūm Wallet - Credit Cards

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

Note: Some accounts have two EFT wallets, one for accounts payable and one for accounts receivable. If this is your case, then 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.

Api Introduction

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

Postman Collection

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

Once you have access to your sandbox portal:

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

2) Download and install the Postman app

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

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

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"
  },
  "CreditCardInformation": {
    "Number": "1234123412341234",
    "ExpireMonth": "01",
    "ExpireYear": "2020",
    "CVV": "123",
    "AddressLine1": "123 street",
    "AddressLine2": "Apartment 123",
    "AddressPostalCode": "A1A 1A1",
    "AddressCountry": "Canada",
    "AddressCity": "Toronto",
    "AddressState": "ON"
  }
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19",
        "FirstName": "John",
        "LastName": "Doe",
        "CompanyName": null
    }
}

Method: POST

Endpoint: {{env}}/api/user

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

Input parameters

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

Response

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

Update user

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

Method: PATCH

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

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

Input parameters

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

Response

Parameter Type Description
id guid User id

Update bank account information

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

Method: PATCH

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

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

Input parameters

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

Response

Parameter Type Description
id guid User id

Update credit card information

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

Method: PATCH

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

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

Input parameters

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

Response

Parameter Type Description
id guid User id

Get a specific user

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

Method: GET

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

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

Response

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

AggregationStatus

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

Delete a user

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

Method: DEL

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

Use this endpoint if you want 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

Funding Sources

Search a funding source

> Payload example:
{
    "CustomerId": "f60d848a-5a45-4649-8968-48a83332d5bd"
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": [
        {
            "Id": "d0108969-37b2-4798-a9b5-cb1d3b3e10dd",
            "Customer": {
                "Id": "08661d6a-82d0-4314-921d-08339b3bb29c",
                "CompanyName": "First Customer"
            },
            "Number": "123 12321 1212312",
            "Name": "Your Company",
            "CreatedAt": "2020-10-22T16:19:40.575727",
            "AggregationStatus": "NotConnected",
            "LastTimeRefreshed": null,
            "FundingSourceType": "BankAccount"
        }
    ]
}

Method: POST

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

Use this endpoint if you want to search for funding sources.

Input parameters

Parameter Type Mandatory Description
CustomerId guid no The customer id

Response

Parameter Type Description
Id guid Funding source id
Number string Funding source number (institution number, transit number, account number)
Name string If account is personal, first and last name; if it's business, company name
AggregationStatus string Aggregation status
LastTimeRefreshed datetime When the last refresh happened
FundingSourceType string BankAccount
Customer
Id guid Customer id
CompanyName string Customer's company name

Get a specific funding source

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

Method: GET

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

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

Response

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

AccountType

Type Description
Personal Personal account
Business Business account

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 Users, use ZumRailsType UserTransfer and inform:
    • UserId
    • TargetUserId

Payment methods v2

Creating a new transaction

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

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

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

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

Method: POST

Endpoint: {{env}}/api/transaction

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

Input parameters

Parameter Type Mandatory Description
ZumRailsType string yes Transaction type
TransactionMethod string yes Transaction method
Amount decimal yes Transaction amount
Memo string yes if customer transaction description type is "PerTransaction" Memo description. If customer transaction description type is "PerTransaction", this will be shown at the bank statements. Maximum of 15 characters. Only letters, numbers, dash, space and underscore are allowed
Comment string no Internal comment you might want to add
FundingSourceId guid no Funding Source Id
WalletId guid no Wallet Id
UserId guid no User Id
User User input no It's possible to create a transaction without adding a user first. Simply pass the user object (instead of the UserId) into the transaction body. For reference, check the payload example of the user object here and pass this when you create a transaction (check interac transaction payload example). Only available for etf and interac transaction methods
InteracHasSecurityQuestionAndAnswer boolean no Indicate if there will be a question and answer for Interac
InteracSecurityQuestion string yes if InteracHasSecurityQuestionAndAnswer is true The question for the user to process the interac request
InteracSecurityAnswer string yes if InteracHasSecurityQuestionAndAnswer is true The answer for the user to process the interac request
ScheduledStartDate date no The date when the transaction will be sent to the financial institution. Must be greater than today
ClientTransactionId string no This field can be used to store the Transaction id created in your system when the Transaction is initiated

Response

Parameter Type Description
Id guid Transaction id

ZumRailsType

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

TransactionMethod

Type
Eft
Interac
VisaDirect
CreditCard 
> Transaction that will succeed example:
{
    "ZumRailsType":"FundZumWallet",
    "TransactionMethod":"Eft",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction will succeed because there's no keyword",
    "FundingSourceId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297"
}
> Transaction that will fail example:
{
    "ZumRailsType":"FundZumWallet",
    "a":"Eft",
    "Amount":123.45,
    "Memo":"Memo description",
    "Comment":"This transaction will fail (EftFailedNoDebitAllowed)",
    "FundingSourceId":"1d431e8b-...85452adb4eee",
    "WalletId":"8ebd932b-...b92633e14297"
}

Keywords to simulate a transaction failure

Eft VisaDirect Interac CreditCard
EftFailedValidationRejection VisaDirectGenericError InteracFailedRecipientContactInfoMissing CreditCardDeclined
EftFailedInsufficientFunds VisaDirectDoNotHonor InteracFailedInvalidEmailFormat CreditCardError
EftFailedCannotLocateAccount VisaDirectInsufficientFunds InteracFailedInvalidPhoneNumber CreditCardHeldForReview
EftFailedStopPayment VisaDirectNotPermittedToCardHolderInformed InteracFailedMultipleTransferLevelErrors CreditCardGenericError
EftFailedAccountClosed VisaDirectAmountLimitNotAuthorized InteracFailedRevoked
EftFailedNoDebitAllowed VisaDirectRejectedAmlOrFraud InteracFailedBulkCancellationRequest
EftFailedFundsNotFree InteracFailedRecipientRejected
EftFailedCurrectAccountMismatch InteracFailedAuthentication
EftFailedPayorPayeeDeceased InteracFailedReachedCancellationCutOff
EftFailedFrozenAccount InteracFailedNotificationDeliveryFailure
EftFailedInvalidErrorAccountNumber InteracFailedAmountGreaterThanMax
EftFailedErrorPayorPayeeName InteracFailedDebtorRejected
EftFailedRefusedNoAgreement InteracFailedFundsDepositFailed
EftFailedNotInAccountAgreementP InteracFailedClientEmailedToRequestCancellation
EftFailedNotInAccountAgreementE InteracFailedGenericError
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)
ScheduledStartDate date The date transaction will be sent to the financial institution
ClientTransactionId string The Transaction id you informed in the creation of this transaction
InteracUrl string The interac URL to complete the transaction, if available
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
Cancelled Indicates the transaction has canceled
Scheduled Indicates the transaction is scheduled

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 VisaDirectGenericError When a generic error happened in the network
VisaDirect VisaDirectDoNotHonor When the information provided was inconsistent, such as address or name on card
VisaDirect VisaDirectInsufficientFunds When not sufficient funds available in the card
VisaDirect VisaDirectNotPermittedToCardHolderInformed When the card holder did not authorize the transaction or the card is restricted for this usage
VisaDirect VisaDirectAmountLimitNotAuthorized When the limit informed invalid, too high or exceeds the withdrawal frequency limit, too many transactions for this card in the current period
VisaDirect VisaDirectRejectedAmlOrFraud When visa identified this transaction as AML or potential fraud
VisaDirect VisaDirectWaitingSettlementIntoClientsAccounts When visa funds are waiting to settle into client's account
VisaDirect VisaDirectSettledIntoClientsAccount When visa funds are settled into client's account
------- ------- -------
Interac InteracSent When the transaction is sent to interac
Interac InteracAcknowledgedCredit When a credit transaction is received by interac
Interac InteracAcknowledgedDebit When a debit transaction is received by interac
Interac InteracFailedRecipientContactInfoMissing Need to add recipient email or mobile phone number
Interac InteracFailedInvalidEmailFormat If the email provided is not valid. * We minimize this error by validating it before
Interac InteracFailedInvalidPhoneNumber If the phone number provided is not valid
Interac InteracFailedMultipleTransferLevelErrors If there is more than one error in the file
Interac InteracFailedRevoked When the transaction is revoked
Interac InteracFailedBulkCancellationRequest When the transaction was cancelled by request
Interac InteracFailedRecipientRejected When the transaction was cancelled due to recipient having declined receipt of funds
Interac InteracFailedAuthentication Transfer cancelled due to maximum number of unsuccessful attempts to answer the security question by the recipient
Interac InteracFailedReachedCancellationCutOff Transfer cancelled due to expiry
Interac InteracFailedNotificationDeliveryFailure Transfer cancelled due to maximum number of failed email notification attempts reached
Interac InteracFailedAmountGreaterThanMax If the transaction amount exceeds the maximum allowed
Interac InteracFailedDebtorRejected The debtor rejected the request
Interac InteracFailedFundsDepositFailed The funds deposit failed
Interac InteracFailedClientEmailedToRequestCancellation Client emailed to request cancellation
Interac InteracFailedGenericError When Interac Network is unavailable - * We have never seen this
Interac InteracWaitingSettlementIntoWallet When Interac funds are waiting to settle into wallet
Interac InteracSettledIntoWallet When Interac funds are settled into wallet
------- ------- -------
CreditCard CreditCardDeclined Not available balance in the card
CreditCard CreditCardError The card information, address, CVV is not correct
CreditCard CreditCardHeldForReview When the transaction is pre-approved, it might take a few hours to approve completely. This is rare
CreditCard CreditCardGenericError When the credit card network is unavailable - * We have never seen this

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",
    "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
ClientTransactionId string no The Transaction id you informed in the creation of the transaction
Pagination no
PageNumber number no The respective page, starting at 1

Response

Parameter Type Description
CurrentPage number The current page
PageSize number The amount of rows returned in the current page
TotalCount number The total rows the filter returns
Items
Id guid Transaction id
CreatedAt datetime When the transaction was created
Memo string Transaction memo
Comment string Transaction comment
Amount decimal Transaction amount
ZumRailsType string Transaction type
TransactionMethod string Transaction method
TransactionStatus string Indicate the status of the transaction
RecurrentTransactionId guid The id of the recurrent transaction that created this transaction (null if inexistent)
FailedTransactionEvent string If the transaction has failed, the transaction event that caused it (null otherwise)
ScheduledStartDate date The date transaction will be sent to the financial institution
ClientTransactionId string The Transaction id you informed in the creation of the transaction

Delete a transaction

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

Method: DELETE

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

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

Recurrent Transactions

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

Creating a new recurrent transaction using API

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

Method: POST

Endpoint: {{env}}/api/transaction

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

Input parameters

Parameter Type Mandatory Description
ZumRailsType string yes Transaction type
TransactionMethod string yes Transaction method
Amount string yes Transaction amount
Memo string no Memo description. Note: maximum length 15 characters
Comment string no Internal comment you might want to add
FundingSourceId guid no Funding Source Id
WalletId guid no Wallet Id
UserId guid no User Id
InteracHasSecurityQuestionAndAnswer 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
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
StartDate date yes/no When the recurrency must begin. yyyy-mm-dd
EndDate date yes/no When the recurrency must stop. yyyy-mm-dd

Response

Parameter Type Description
Id guid Transaction id

RecurrenceType

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

DayOfWeek

Get recurrent transaction

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

Method: GET

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

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

Response

Parameter Type Description
Id guid Transaction id
CreatedAt datetime When the transaction was created
Memo string Transaction memo
Comment string Transaction comment
Amount decimal Transaction amount
ZumRailsType string Transaction type
TransactionMethod string Transaction method
UserId guid The user id
WalletId guid The wallet id
FundingSourceId guid The funding source id
RecurrenceType string The frequency
DayOfWeek string Which day of the week transactions will be created
DayOfMonth int Which day transactions will be created
StartDate date When the recurrency must begin. yyyy-mm-dd
EndDate date When the recurrency must stop. yyyy-mm-dd
From string Description of where funds are coming from
To string Description of where funds are going
TransactionsIds array of guids An array containing the ids of the transactions originated by the recurrent transaction
OriginalStartDate date The start date used as backup (updated when ResetToOriginalValues is set to false)
OriginalEndDate date The end date used as backup (updated when ResetToOriginalValues is set to false)
OriginalAmount decimal The amount used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfWeek string The week day used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfMonth int The month day used as backup (updated when ResetToOriginalValues is set to false)
ResetToOriginalValues bool If start date, end date, amount, day of week, day of month will be restores to the previous values after next transacation is created

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",
            "TransactionMethod": "Interac",
            "TransactionType": "Eft",
            "StartDate": "2020-08-20T00:00:00",
            "EndDate": "2021-08-28T04:00:00",
            "RecurrenceType": "Weekly",
            "DayOfWeek": "Monday",
            "DayOfMonth": null,
            "From": "Funding Source (RBC-01234-1234567)",
            "To": "Zūm Wallet (AccountsPayable)",
            "UserId": null,
            "FundingSourceId": "c7f77ae5-...-14b6c3fd7ad1",
            "WalletId": "30126b59-...-008376504211",
            "OriginalStartDate": "2020-01-20T03:00:00",
            "OriginalEndDate": "2020-08-28T04:00:00",
            "OriginalAmount": 2.22,
            "OriginalDayOfWeek": "Monday",
            "OriginalDayOfMonth": null,
            "ResetToOriginalValues": false  
        }]
    }
}

Method: POST

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

Recurrent transactions are returned with pagination, which means that if you need to retrieve all recurrent transactions you need to call the same endpoint 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 beginning start date
EndingStartDate datetime no Recurring transaction end starting 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
TransactionMethod string no The transaction method
Pagination no
PageNumber number no The respective page, starting at 1

Response

Parameter Type Description
CurrentPage number The current page
PageSize number The amount of rows returned in the current page
TotalCount number The total rows the filter returns
Items
Id guid Transaction id
CreatedAt datetime When the transaction was created
Memo string Transaction memo
Comment string Transaction comment
Amount decimal Transaction amount
ZumRailsType string Transaction type
UserId guid The user id
WalletId guid The wallet id
FundingSourceId guid The funding source id
RecurrenceType string The frequency
DayOfWeek string Which day of the week transactions will be created
DayOfMonth int Which day transactions will be created
StartDate date When the recurrency must begin
EndDate date When the recurrency must stop
From string Description of where funds are coming from
To string Description of where funds are going
OriginalStartDate date The start date used as backup (updated when ResetToOriginalValues is set to false)
OriginalEndDate date The end date used as backup (updated when ResetToOriginalValues is set to false)
OriginalAmount decimal The amount used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfWeek string The week day used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfMonth int The month day used as backup (updated when ResetToOriginalValues is set to false)
ResetToOriginalValues bool If start date, end date, amount, day of week, day of month will be restores to the previous values after next transacation is created

Editing a recurrent transaction using API

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

Method: PUT

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

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

Input parameters

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

Response

Parameter Type Description
Id guid Transaction id
CreatedAt datetime When the transaction was created
Memo string Transaction memo
Comment string Transaction comment
Amount decimal Transaction amount
ZumRailsType string Transaction type
TransactionMethod string Transaction method
UserId guid The user id
WalletId guid The wallet id
FundingSourceId guid The funding source id
RecurrenceType string The frequency
DayOfWeek string Which day of the week transactions will be created
DayOfMonth int Which day transactions will be created
StartDate date When the recurrency must begin. yyyy-mm-dd
EndDate date When the recurrency must stop. yyyy-mm-dd
From string Description of where funds are coming from
To string Description of where funds are going
TransactionsIds array of guids An array containing the ids of the transactions originated by the recurrent transaction
OriginalStartDate date The start date used as backup (updated when ResetToOriginalValues is set to false)
OriginalEndDate date The end date used as backup (updated when ResetToOriginalValues is set to false)
OriginalAmount decimal The amount used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfWeek string The week day used as backup (updated when ResetToOriginalValues is set to false)
OriginalDayOfMonth int The month day used as backup (updated when ResetToOriginalValues is set to false)
ResetToOriginalValues bool If start date, end date, amount, day of week, day of month will be restores to the previous values after next transacation is created

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

Delete a recurrent transaction

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

Method: DELETE

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

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

Transactions Batch CSV

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

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

Validating transactions from batch file

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

Method: POST

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

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

Input parameters

Parameter Type Mandatory Description
TransactionType string yes Transaction type
WalletId string no The Wallet Id, according to TransactionType
FundingSourceId string no The Funding Source Id
Bytes string yes The file's blob

Response

Parameter Type Description
InvalidTransactions string The amount of invalid transactions
ValidTransactions int The amount of valid transactions
Status string The validation status
TotalAmout decimal The sum of all transactions amount
Transactions
AccountNumber string The account number
Amount decimal The transaction's amount
Comment string The transaction's comment
CompanyName string Company's name
CustomerId string Customer id
FirstName string User's first name
LastName string User's last name
InstitutionNumber string Institution's number
Memo string The transaction's memo
Status string The status
TransitNumber string Transit number

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

Status

Description
Ok
First Name, Last Name or Company name are mandatory
Either First and Last Name or Company Name should be informed
Institution, Transit and Account numbers are mandatory
Institution Number min length is 3 characters
Transit Number length needs to be 5 characters
Account Number min length is 5 characters
Account Number max length is 12 characters
Invalid amount
Amount must be greater than zero
Duplicated transaction

Creating transactions through batch file

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

Method: POST

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

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

Input parameters

Parameter Type Mandatory Description
TransactionType string yes Transaction type
WalletId string no The Wallet Id, according to TransactionType
FundingSourceId string no The Funding Source Id
Bytes string yes The file's blob

TransactionType

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

Request Funds - Checkout form

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

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

Connect checkout flow v2

Creating a request funds form - checkout form

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

Method: POST

Endpoint: {{env}}/api/requestfunds

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

Input parameters

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

AmountType

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

RecurrenceType

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

DayOfWeek

Get a specific request funds - checkout form

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

Method: GET

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

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

Wallets

List all wallets

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": [
        {
            "Id": "30126b59-...-008376504211",
            "Type": "AccountsPayable",
            "Balance": 50000.88
        },
        {
            "Id": "30126b59-...-008376504210",
            "Type": "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 webhook call is for a user status change
Transaction Indicates the webhook call is for a transaction status change
Customer Indicates the webhook call is for a customer account status change
Recurrent Transaction Indicates the webhook call is for a recurrent transaction creation

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

Verifying authenticity

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

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

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

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

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

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

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

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

Retry in case of failure

In the event of a failure to 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",
    "AddressStreet": "Street 01",
    "AddressCity": "Toronto",
    "AddressProvince": "ON",
    "AddressPostalCode": "A1A-1A1",
    "TransacionMethodEftEnabled": true,
    "TransacionMethodInteracEnabled": false,
    "TransacionMethodVisaDirectEnabled": false,
    "TransacionMethodCreditCardEnabled": false,
    "WebhookConfigurations": 
    [
        {
            "WebhookType": "Transaction",
            "StatusValue": 8
        },
        {
            "WebhookType": "User",
            "StatusValue": 1
        }
    ],
    "NotificationConfigurations":
    [
        {
            "Method": "Email",
            "Type": "TransactionFailure",
            "Emails": ["johndoe@email.com","janedoe@email.com"]
        }
    ]
}
> 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": "Street 01",
        "AddressCity": "Toronto",
        "AddressProvince": "ON",
        "AddressPostalCode": "A1A-1A1",
        "CustomerAccountStatus": "PendingActivation",
        "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
        "WebhookUrl": null,
        "WebhookConfigurations":
        [
            {
                "WebhookType": "Transaction",
                "Name": "Succeeded",
                "StatusValue": 8
            },
            {
                "WebhookType": "User",
                "Name": "Connected",
                "StatusValue": 1
            }
        ],
        "NotificationConfigurations":
        [
            {
                "Method": "Email", 
                "Type": "TransactionFailure", 
                "Emails": ["johndoe@email.com", "janedoe@email.com"]
            }
        ],
        "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 yes Address street
AddressCity string yes Address city
AddressProvince string yes Address province
AddressPostalCode string yes Address postal code
WebhookUrl string no Url to receive webhooks
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
NotificationConfigurations list of Notification Configurations no A list containing notification configurations
Method Notification Method yes Method of the notification
Type Notification Type yes Type of the motification
Emails e-mail array yes if Method is "Email" E-mails which will be notified

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

Webhook Configurations

WebhookType Value Name
User 0 NotConnected
User 1 Connected
User 2 Connecting
User 3 Refreshing
User 4 RefreshFailed
Customer 0 Active
Customer 1 PendingFundingSource
Customer 2 PendingActivation
Customer 3 PendingUnderwriting
Transaction 1 Started
Transaction 8 Succeeded
Transaction 9 Cancelled
Transaction 3 EFTFileUploaded
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
Transaction 200 InteracSent
Transaction 201 InteracAcknowledgedCredit
Transaction 202 InteracAcknowledgedDebit
Transaction 203 InteracFailedGenericError
Transaction 204 InteracFailedRecipientContactInfoMissing
Transaction 205 InteracFailedInvalidEmailFormat
Transaction 206 InteracFailedInvalidPhoneNumber
Transaction 207 InteracFailedMultipleTransferLevelErrors
Transaction 208 InteracFailedRevoked
Transaction 209 InteracFailedBulkCancellationRequest
Transaction 210 InteracFailedRecipientRejected
Transaction 211 InteracFailedAuthentication
Transaction 212 InteracFailedReachedCancellationCutOff
Transaction 213 InteracFailedNotificationDeliveryFailure
Transaction 214 InteracFailedAmountGreaterThanMax
Transaction 215 InteracFailedDebtorRejected
Transaction 216 InteracFailedFundsDepositFailed
Transaction 217 InteracFailedClientEmailedToRequestCancellation
Transaction 218 InteracFailedApiCancelation
Transaction 219 InteracFailedInicialization
Transaction 220 InteracFailedSecurityQuestionNeededForProvidedEmail
Transaction 223 InteracSettledIntoWallet
Transaction 301 CreditCardError
Transaction 302 CreditCardDeclined
Transaction 303 CreditCardHeldForReview
Transaction 304 CreditCardGenericError
Transaction 101 VisaDirectGenericError
Transaction 102 VisaDirectDoNotHonor
Transaction 103 VisaDirectInsufficientFunds
Transaction 104 VisaDirectNotPermittedToCardHolderInformed
Transaction 105 VisaDirectAmountLimitNotAuthorized
Transaction 106 VisaDirectRejectedAmlOrFraud
Transaction 108 VisaDirectSettledIntoClientsAccount

Notification Method

Type Description
Email Notifications will be sent via e-mail

Notification Type

Type Description
TransactionFailure When a transaction fails, a notification will be sent

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
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
NotificationConfigurations list of Notification Configurations A list containing notification configurations
Method Notification Method Method of the notification
Type Notification Type Type of the motification
Emails e-mail array E-mails which will be notified

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
Customer Webhook triggered by customer account status changes

Editing a customer

> Request example:
{
    "CompanyName": "Example Customer Company",
    "TransactionDescriptionType": "Fixed",
    "TransactionDescription": "Description",
    "FirstName": "John",
    "LastName": "Doe",
    "SecurityPassword": "examplePassword123",
    "PhoneNumber": "514-123-1234",
    "Email": "examplecompany@zumrails.com",
    "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",
        "CustomerAccountStatus": "Active",
        "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
        "WebhookUrl": null,
        "WebhookConfigurations": [],
        "NotificationConfigurations": [],
        "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
SecurityPassword string yes Password confirmation field
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
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
NotificationConfigurations list of Notification Configurations yes A list containing notification configurations
Method Notification Method yes Method of the notification
Type Notification Type yes Type of the notification
Emails e-mail array yes if Method is "Email" E-mails which will be notified

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
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
CustomerBillingPrices List of prices configurations of the customer
WebhookType Webhook Type Type of the webhook
Name string Name of the webhook
StatusValue int Value of the webhook
NotificationConfigurations List of notification configurations of the customer
Method Notification Method Method of the notification
Type Notification Type Type of the notification
Emails e-mail array E-mails which will be notified

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",
        "CustomerAccountStatus": "Active",
        "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
        "WebhookUrl": null,
        "WebhookConfigurations": [],
        "NotificationConfigurations": [],
        "ActivationDate": null,
        "CreatedAt": "2020-08-24T12:31:29.935951",
        "ZumConnectUrl": "http://sandbox.zumrails.com/#/connect/f60d848a-5a45-4649-8968-48a83332d5bd",
        "ZumConnectFundingSourceUrl": "http://sandbox.zumrails.com/#/connect/fundingsource/f60d848a-5a45-4649-8968-48a83332d5bd",
        "CustomerBillingPrices": [
            {
                "Id": "3b7e4e3b-7403-4874-994f-790223370b72",
                "Amount": 10,
                "CustomerBillingPriceType": "InteracSuccess",
                "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
                "CustomerBillingType": "BuyRate",
                "CreatedAt": "2021-02-05T15:25:53.061356",
                "UpdatedAt": "2021-02-05T15:26:32.451891"
            },
            {
                "Id": "490214b4-a036-4904-882b-3b6bbcbbdbe1",
                "Amount": 10,
                "CustomerBillingPriceType": "MonthlyFee",
                "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
                "CustomerBillingType": "BuyRate",
                "CreatedAt": "2021-02-05T15:25:53.061357",
                "UpdatedAt": "2021-02-05T15:26:32.451891"
            },
            {
                "Id": "4cb411bc-495f-4d45-884e-cabe6e986daf",
                "Amount": 10,
                "CustomerBillingPriceType": "EFTSuccess",
                "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
                "CustomerBillingType": "BuyRate",
                "CreatedAt": "2021-02-05T15:25:53.061352",
                "UpdatedAt": "2021-02-05T15:26:32.451887"
            },
        ],
    }
}

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
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
ZumConnectUrl URL Customer unique URL to add users to his account
ZumConnectFundingSourceUrl URL Customer unique URL to add funding sources to his account
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",
    "CustomerAccountStatus": "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,
                "CustomerAccountStatus": "PendingActivation",
                "PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
                "WebhookUrl": null,
                "WebhookConfigurations": [],
                "NotificationConfigurations": [],
                "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
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 Billing

As a Zūm Rails partner you have several options for billing your customer: Successful transactions according to their type (EFT or Interac for example), new registered users, a monthly fee to be added or a monthly minimum fee.

Each customer can be billing different and with different amounts.

We have two enumerations to work with your customer's billing options:

CustomerBillingPriceType

Describe the operation

Id Type Description
1 EFTSuccess When the EFT transaction was completed with success.
2 EFTNSF When there was a failure with the EFT transaction.
3 AggregationNewUser When a new user is registered using the plaid.
7 InteracSuccess When the Interac transaction was completed with success.
8 InteracFailure When there was a failure with the Interac transaction.
11 MonthlyFee An additional monthly fee for the customer.
12 MonthlyMinimum A minimum fee for the customer, when their monthly bill is less than it, will be charged the minimum fee.


CustomerBillingType

Defines how the billing will work

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

Customer Billing - Adding a billing option to your customer

Method: POST Endpoint: {{env}}/api/customer/{customerId}/customerbillingprice/

Use this endpoint if you want to add a billing option for a customer.

> Request example:
{
    "Amount": 35,
    "CustomerBillingPriceType": "MonthlyFee",
    "CustomerBillingType": "BuyRate",
}
> Response example:
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "6dc9b3c5-975c-4132-9d04-dfabe9b5fd4c",
        "Amount": 20,
        "CustomerBillingPriceType": "VisaDirectSuccess",
        "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
        "CustomerBillingType": "BuyRate",
        "CreatedAt": "2021-02-05T19:22:40.634003Z",
        "UpdatedAt": "2021-02-05T19:22:40.634004Z"
    }
}

Input parameters

Parameter Type Mandatory Description
CustomerId guid yes Customer id (It will be send as query parameter).
Amount number no The amount that will be charged to the customer for each action.
CustomerBillingPriceType CustomerBillingPriceType yes Defines the operation that will be billed.
CustomerBillingType CustomerBillingType yes Defines how the billing will work (must be the same as the partner).

Response

Id guid Customer Price Id
Id guid Customer billing option id
CustomerId guid Customer id
CreatedAt date When the billing option was created
UpdatedAt date When the billing option was updated
CustomerBillingPriceType CustomerBillingPriceType Defines the operation that will be billed.
Amount number The amount that will be charged to the customer for each action
CustomerBillingType CustomerBillingType Defines how the billing will work (must be the same as the partner)

Customer Billing - Update your customer's billing option

Method: PATCH Endpoint: {{env}}/api/customer/{customerId}/customerbillingprice/

Use this endpoint if you want to update or create a specific billing option.

> Request example:
{
    "Amount": 35,
    "CustomerBillingPriceType": "MonthlyFee",
    "CustomerBillingType": "BuyRate",
    "Id": "5eac2745-3199-4ab4-b353-e7a0f83c4816"
}
> Response example:
{
    "statusCode": 200,
    "message": "PATCH Request successful.",
    "isError": false,
    "result": {
        "Id": "6dc9b3c5-975c-4132-9d04-dfabe9b5fd4c",
        "Amount": 30,
        "CustomerBillingPriceType": "VisaDirectSuccess",
        "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
        "CustomerBillingType": "BuyRate",
        "CreatedAt": "2021-02-05T19:22:40.634003",
        "UpdatedAt": "2021-02-05T19:29:24.648551Z"
    }
}

Input parameters

Parameter Type Mandatory Description
CustomerId guid yes Customer id (It will be send as query parameter).
Id guid no Customer billing price id.
Amount number no The amount that will be charged to the customer for each action.
CustomerBillingPriceType CustomerBillingPriceType yes Defines the operation that will be billed.
CustomerBillingType CustomerBillingType yes Defines how the billing will work (must be the same as the partner).

Customer Billing - Get the ways that your customer will be charged

Method: GET Endpoint: {{env}}/api/customer/{customerId}/customerbillingprices/

Use this endpoint if you want to get all prices added for a customer.

> Response example:
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": [
        {
            "Id": "4cb411bc-495f-4d45-884e-cabe6e986daf",
            "Amount": 10,
            "CustomerBillingPriceType": "EFTSuccess",
            "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
            "CustomerBillingType": "BuyRate",
            "CreatedAt": "2021-02-05T15:25:53.061352",
            "UpdatedAt": "2021-02-05T15:26:32.451887"
        },
        {
            "Id": "d811852b-7dc2-4a57-8806-40eb0e168639",
            "Amount": 10,
            "CustomerBillingPriceType": "EFTNSF",
            "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
            "CustomerBillingType": "BuyRate",
            "CreatedAt": "2021-02-05T15:25:53.061355",
            "UpdatedAt": "2021-02-05T15:26:32.45189"
        },
        {
            "Id": "df6af015-6b2a-4ceb-a0ba-a63902afc5c7",
            "Amount": 10,
            "CustomerBillingPriceType": "AggregationNewUser",
            "CustomerId": "343a4dce-bee8-4847-a64f-b7e81094dbda",
            "CustomerBillingType": "BuyRate",
            "CreatedAt": "2021-02-05T15:25:53.061355",
            "UpdatedAt": "2021-02-05T15:26:32.45189"
        },
    ]
}

Input parameters

Parameter Type Mandatory Description
CustomerId guid yes Customer id

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
BankStatements Bank Statement copy

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, GovernmentPhotoId or BankStatements)
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.

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

Errors

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

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