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:
- Funding Source: This is your bank account, to be able to start moving funds you will need to link your bank account information using Zūm Portal.
- Zūm Wallet: This is a virtual account, we will provide to you a Zūm Wallet, so that you can use to manage funds. The Zūm Wallet is divided into Accounts Receivable (AR) and Accounts Payable (AP). If you need to move funds directly from a Funding Source to User, or the opposite, the funds will pass through Zūm Wallet automatically.
- User: Represents the payee for accounts payable, or the payer for accounts receivable. More details can be found under the User’s' section.
Payment Methods
Zūm Rails offers multiple payment methods depending on our agreement.
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.
Depending on your business contract with Zūm, the user will be prompt to:
Method | User action required |
---|---|
EFT | Link the bank account using financial data aggregation |
Interac | The phone number (Name and Email are captured independent of the method) |
Visa Direct | Credit Card information and Address |
Credit Card | Credit Card information and Address |
Your specific settings will be available under your profile in Zūm Rails portal. Depending on your need you can capture the new user using our webhook mechanism or if you need it right at the moment we redirect back to your flow, you can capture the Zūm user id (token) by listening an event message as described in your portal settings.
After a user creates and links his account, you will be able to view it in the Zūm Rails portal or use the API to filter and get a specific user.
Zūm Wallet
Every Zūm Rails account comes with two Zūm Wallets.
- AP - Accounts Payable
- AR - Accounts Receivable
There are two types of wallets because if your organization wants to preload your AP Accounts Payable Wallet to allow for faster payments (Zūm doesn’t need to pull the funds to initiate the push) you can keep your transaction separate from your AR Accounts Receivable wallet.
In the case of AR Accounts Receivable you can receive multiple receivables during the day and also specify an automatic daily withdraw form your AR wallet at the end of the day.
Zūm Wallets can also be used to help dictate traffic, so in the example of marketplace applications one can pull from a user AR, but then split the payment accordingly to the wallet.
Environments
Production:
- Live Portal: https://app.zumrails.com
- Live API base Url: https://api-app.zumrails.com
Sandbox:
- Sandbox Portal: https://sandbox.zumrails.com
- Sandbox API base Url: https://api-sandbox.zumrails.com
API Specifics
- All datetime fields are stored and returned as UTC format;
- All API requests must pass the header Content-type: application/json;
API Structure
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {}
}
All API endpoints return the same response, containing 4 important pieces of information:
Field | Description |
---|---|
statusCode | The http status code |
message | A message describing if the response was successful |
isError | true/false to indicate if the request was successful |
result | The json response for your API call |
Authentication
> Payload example:
{
"Username": "abc...123",
"Password": "xyz...321"
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"Role": "API",
"Token": "eyJhbG...tOTuvNvJc",
"CustomerId": "3012...042f2",
"CompanyName": "Test Company Inc."
}
}
Method: POST
Endpoint: {{env}}/api/authorize
All API requests are using the Bearer Token Authorization. A Bearer Token will last up to an hour from the time it is generated, allowing multiple API calls to be made securely without authorizing each time.
To be able to get your token access, open the Settings page in the Portal, then navigate to the section API settings. You will need the username and password.
Input parameters
Parameter | Type | Description |
---|---|---|
Username | string | Your API username |
Password | string | Your API password |
Responses
Parameter | Description |
---|---|
Role | The role this login belongs to |
Token | The authorization token that needs to be used in any other API request |
CustomerId | The customer id this login belongs to |
CompanyName | The company name this login belongs to |
Users
At Zūm, Users represents the payee for accounts payable, or the payer for accounts receivable. There are 3 ways of ingesting users, API, Portal, and Zūm Connect.
Zūm Rails recommends using Zūm Connect
- For EFT, it offers the end user the possibility to link his bank account, ensuring that the bank account information will be verified to avoid transaction failures.
- For Credit Card and Visa Direct, it's required so that we reduce your PCI scope.
For more information about Zūm Connect, click here:
Creating a new user
> Payload example:
{
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@zumrails.com",
"companyName": null,
"phoneNumber": "514-123-1234",
"BankAccountInformation": {
"institutionNumber": "111",
"transitNumber": "12345",
"accountNumber": "1234567"
},
"CreditCardInformation": {
"Number": "1234123412341234",
"ExpireMonth": "01",
"ExpireYear": "2020",
"CVV": "123",
"AddressLine1": "123 street",
"AddressLine2": "Apartment 123",
"AddressPostalCode": "A1A 1A1",
"AddressCountry": "Canada",
"AddressCity": "Toronto",
"AddressState": "ON"
}
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"Id": "0bc9894d-b37b-4ae0-af70-f691024aca19",
"FirstName": "John",
"LastName": "Doe",
"CompanyName": null
}
}
Method: POST
Endpoint: {{env}}/api/user
Use this endpoint if you want to add a new user to your account. For Credit Card and Visa Direct, if you want to add a user through API, please contact Zūm support.
Input parameters
Parameter | Type | EFT | Interac | Credit Card | Visa Direct | Description |
---|---|---|---|---|---|---|
FirstName | string | yes | yes | yes | yes | User first name |
LastName | string | yes | yes | yes | yes | User last name |
CompanyName | string | no | yes | yes | yes | Company name, in case it's a company |
string | yes | yes | yes | yes | User e-mail | |
PhoneNumber | string | no | yes | no | no | Phone number |
BankAccountInformation | yes | |||||
InstitutionNumber | string | yes | no | no | no | Institution Number, 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 | yes | Billing address line 1 |
AddressLine2 | string | no | no | yes | yes | Billing address line 2 |
AddressPostalCode | string | no | no | yes | yes | Billing address postal code |
AddressCountry | string | no | no | yes | yes | Billing address country |
AddressCity | string | no | no | yes | yes | Billing address city |
AddressState | string | no | no | yes | yes | Billing address state/province |
- If the user will be sending funds to Zūm (pull from a card) via Via Direct transaction, ExpireMonth and ExpireYear are required
- If the user will be receiving funds from Zūm (push from a card), ExpireMonth, ExpireYear, and CVV are optional
Response
Parameter | Type | Description |
---|---|---|
id | guid | User id |
firstName | string | First name |
lastName | string | Last name |
companyName | string | Company name, in case it's a company |
Update user
> Payload example:
{
"firstName": "John",
"lastName": "Doe",
"companyName": null,
"email": "johndoe@zumrails.com",
"phoneNumber": "514-123-1234"
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": "0bc9894d-....-f691024aca19"
}
Method: PATCH
Endpoint: {{env}}/api/user/UpdateBasicInformation/{user_id}
Use this endpoint if you want to edit the basic information for an existing user. The user id is informed in the url and the body payload contains the user information. This endpoint does not update the bank account information or the credit card information.
Input parameters
Parameter | Type | EFT | Interac | Credit Card | Visa Direct | Description |
---|---|---|---|---|---|---|
FirstName | string | yes | yes | yes | yes | User first name |
LastName | string | yes | yes | yes | yes | User last name |
CompanyName | string | no | yes | yes | yes | Company name, in case it's a company |
string | yes | yes | yes | yes | User e-mail | |
PhoneNumber | string | no | yes | 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 Req. | 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 Req. | Visa Direct Req. | 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"
},
"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 |
string | Last name | |
LastRefresh | datetime | Last name |
BankAccountInformation | ||
Institution | string | Institution name |
InstitutionNumber | string | Institution Number |
TransitNumber | string | Transit Number |
AccountNumber | string | Account Number |
FirstName | string | Last name |
LastName | string | Last name |
AggregationStatus | string | Indicate if the account is Connected |
LastTimeRefreshed | datetime | When the last refresh happened |
AggregationFailedReason | string | If failed, informs the failure reason |
AggregationBalance | decimal | EFT account current balance |
CreditCardInformation | ||
Number | string | Last for digits only |
ExpireMonth | number | Card expiry month, 2 digits |
ExpireYear | number | ard expiry year, 4 digits |
CVV | string | Security code, 3 or 4 digits |
AddressLine1 | string | Billing address line 1 |
AddressLine2 | string | Billing address line 2 |
AddressPostalCode | string | Billing address postal code |
AddressCountry | string | Billing address country |
AddressCity | string | Billing address city |
AddressState | string | Billing address state/province |
TransactionsMethodsAvailable | ||
Eft | Boolean | Indicate if this user can do EFT transactions |
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 |
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 |
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 |
- The AggregationStatus domain can be found under the User’s section.
Get a specific funding source
> Response example:
{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"Id": "447c3213-759b-40e4-a424-382f558dea4c",
"Customer": {
"Id": "acbcc52c-eb1b-4248-85a7-31fee8f3a3ca",
"CompanyName": "Your Company"
},
"Institution": "Bank Name",
"InstitutionNumber": "123",
"TransitNumber": "12345",
"AccountNumber": "1234567",
"AccountType": "Personal",
"Name": "John Smith",
"CompanyName": null,
"FirstName": "John",
"LastName": "Smith",
"CreatedAt": "2020-10-22T19:02:26.777304",
"AggregationStatus": "Connected",
"LastTimeRefreshed": "2020-10-22T19:02:58.061333",
"AggregationFailedReason": "None",
"AggregationBalance": 50017.58,
"AggregationCard": {
"Id": "2babb324-3a80-4a35-a1cc-b3795d294d18",
"HolderName": "John Smith",
"HolderCivicAddress": "1234 Street 01",
"HolderCity": "Toronto",
"HolderProvince": "ON",
"HolderPostalCode": "A0A 1A1",
"HolderCountry": "CA",
"HolderEmail": "email@zumrails.com",
"HolderPhoneNumber": "(123) 123-1234",
"Institution": "Bank Name",
"Accounts": [
{
"Id": "4e399a3d-7562-4008-b074-16991f14cc72",
"ProviderAccountId": "729e24f0-6458-40f2-4afa-08d7a8df7f42",
"Transactions": [
{
"Id": "02464c54-9ce4-4912-a426-a8c440b9a996",
"ProviderTransactiontId": "00000000-0000-0000-0000-000000000000",
"Date": "2020-05-09T00:00:00",
"Description": "TrxChe@Cr15.91",
"Debit": null,
"Credit": 15.91,
"Balance": 50007.96
},
{
"Id": "047c6bab-50fe-4420-a46f-beeb32408a06",
"ProviderTransactiontId": "00000000-0000-0000-0000-000000000000",
"Date": "2020-03-09T00:00:00",
"Description": "TrxChe@De15.30",
"Debit": 15.3,
"Credit": null,
"Balance": 49992.35
}
],
"TransitNumber": "12345",
"InstitutionNumber": "123",
"AccountNumber": "1234567",
"Title": "Chequing Account",
"Balance": 123.45,
"Category": "Operations",
"Type": "Chequing",
"Currency": "CAD",
"IsEftEligible": true
}
],
"LastRefresh": "2020-10-22T19:02:29.63879",
"BankAccountInformationOrigin": "Origin",
"ProviderCardId": "694e916b-262e-4139-07db-08d7a8df789b",
"CustomerId": "acbcc52c-eb1b-4248-85a7-31fee8f3a3ca"
},
"HasMinimumInformationForEft": true
}
}
Method: GET
Endpoint: {{env}}/api/fundingsource/{fundingsource_id}
Use this endpoint if you want to get a specific funding source's detailed information. The funding source id is informed in the url.
Response
Parameter | Type | Description |
---|---|---|
Id | guid | Customer id |
Institution | string | Institution name |
InstitutionNumber | string | Institution Number |
TransitNumber | string | Transit Number |
AccountNumber | string | Account Number |
AccountType | string | Account type |
Name | string | If it's a personal account, name will be FirstName + LastName; if it's business, name will be CompanyName |
CompanyName | string | Company's name (only if it's a business count) |
FirstName | string | First name (only if it's personal account) |
LastName | string | Last name (only if it's personal account) |
AggregationStatus | string | Aggregation status |
LastTimeRefreshed | datetime | When the last refresh happened |
AggregationFailedReason | string | If failed, informs the failure reason |
AggregationBalance | decimal | EFT account current balance |
HasMinimumInformationForEft | boolean | If funding source has the minimum information to allow EFT transactions to be performed |
Customer | ||
Id | guid | Customer id |
CompanyName | string | Customer's company name |
AccountType
Type | Description |
---|---|
Personal | Personal account |
Business | Business account |
- The AggregationStatus domain can be found under the User’s section.
- The AggregationCard domain can be found under the Aggregation’s section.
Transactions
At Zūm Rails, there are 5 ways to create transactions, when using the portal or via API. When creating a transaction via API, the transaction type “ZumRailsType” must be specified.
There are five transaction types (ZumRailsType):
- FundZumWallet
- WithdrawZumWallet
- AccountsPayable
- AccountsReceivable
- WalletTransfer
- If you want to send money from your Funding Source to Zūm Wallet, use ZumRailsType FundZumWallet and inform:
- FundingSourceId
- WalletId
- If you want to withdraw money from Zūm Wallet to your Funding Source, use ZumRailsType WithdrawZumWallet and inform:
- FundingSourceId
- WalletId
- If you want to send money (accounts payable) from your Zūm Wallet to a User, use ZumRailsType AccountsPayable and inform:
- UserId
- WalletId
- If you want to send money (accounts payable) from your Funding Source to a User, use ZumRailsType AccountsPayable and inform:
- UserId
- FundingSourceId
- If you want to withdraw money (accounts receivable) from a User to your Zūm Wallet, use ZumRailsType AccountsReceivable and inform:
- UserId
- WalletId
- If you want to withdraw money (accounts receivable) from a User to your Funding Source, use ZumRailsType AccountsReceivable and inform:
- UserId
- FundingSourceId
- If you want to move money between your Zūm Wallets, use ZumRailsType WalletTransfer and inform:
- WalletId
- TargetWalletId
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 | string | yes | Transaction amount |
Memo | string | yes if customer transaction description type is "PerTransaction" | Memo description. If customer transaction description type is "PerTransaction", this will be shown at the bank statements. Maximum of 15 characters. Only letters, numbers, dash, space and underscore are allowed |
Comment | string | no | Internal comment you might want to add |
FundingSourceId | guid | no | Funding Source Id |
WalletId | guid | no | Wallet Id |
TargetWalletId | guid | no | The wallet that will receive money from the source wallet (WalletId), if transaction type is "WalletTransfer" |
UserId | guid | no | User Id |
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 |
Response
Parameter | Type | Description |
---|---|---|
Id | guid | Transaction id |
ZumRailsType
Type | Description |
---|---|
FundZumWallet | Send money to your Zūm Wallet |
WithdrawZumWallet | Withdraw from your Zūm Wallet |
AccountsPayable | Execute accounts payable AP |
AccountsReceivable | Execute accounts receivable AR |
WalletTransfer | Move money between your wallets |
TransactionMethod
Type |
---|
Eft |
Interac |
VisaDirect |
CreditCard |
> Transaction that will succeed example:
{
"ZumRailsType":"FundZumWallet",
"TransactionMethod":"Eft",
"Amount":123.45,
"Memo":"Memo description",
"Comment":"This transaction will succeed because there's no keyword",
"FundingSourceId":"1d431e8b-...85452adb4eee",
"WalletId":"8ebd932b-...b92633e14297"
}
> Transaction that will fail example:
{
"ZumRailsType":"FundZumWallet",
"a":"Eft",
"Amount":123.45,
"Memo":"Memo description",
"Comment":"This transaction will fail (EftFailedNoDebitAllowed)",
"FundingSourceId":"1d431e8b-...85452adb4eee",
"WalletId":"8ebd932b-...b92633e14297"
}
Keywords to simulate a transaction failure
Eft | VisaDirect | Interac | CreditCard |
---|---|---|---|
EftFailedValidationRejection | VisaDirectGenericError | InteracFailedRecipientContactInfoMissing | CreditCardDeclined |
EftFailedInsufficientFunds | VisaDirectNetworkTimeout | InteracFailedInvalidEmailFormat | CreditCardError |
EftFailedCannotLocateAccount | VisaDirectNetworkDeclined | InteracFailedInvalidPhoneNumber | CreditCardHeldForReview |
EftFailedStopPayment | InteracFailedMultipleTransferLevelErrors | CreditCardGenericError | |
EftFailedAccountClosed | InteracFailedRevoked | ||
EftFailedNoDebitAllowed | InteracFailedBulkCancellationRequest | ||
EftFailedFundsNotFree | InteracFailedRecipientRejected | ||
EftFailedCurrectAccountMismatch | InteracFailedAuthentication | ||
EftFailedPayorPayeeDeceased | InteracFailedReachedCancellationCutOff | ||
EftFailedFrozenAccount | InteracFailedNotificationDeliveryFailure | ||
EftFailedInvalidErrorAccountNumber | InteracFailedAmountGreaterThanMax | ||
EftFailedErrorPayorPayeeName | InteracFailedDebtorRejected | ||
EftFailedRefusedNoAgreement | InteracFailedFundsDepositFailed | ||
EftFailedNotInAccountAgreementP | InteracFailedClientEmailedToRequestCancellation | ||
EftFailedNotInAccountAgreementE | InteracFailedApiCancelation | ||
EftFailedAgreementRevoked | InteracFailedInicialization | ||
EftFailedDefaultByAFinancialInstitution | InteracFailedGenericError | ||
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 |
User | If transaction has a user - * Not all information from an user is returned in this endpoint | |
Id | guid | The user id |
First Name | string | User first name |
Last Name | string | User last name |
Company Name | string | User company name |
Wallet | If transaction has a wallet * Not all information from an user is returned in this endpoint | |
Id | guid | The wallet id |
Type | string | The wallet type |
FundingSource | If transaction has a funding source * Not all information from an user is returned in this endpoint | |
Id | guid | The funding source id |
Institution | string | The institution name |
InstitutionNumber | string | The institution number |
TransitNumber | string | The transit number |
AccountNumber | string | The account number |
TargetWallet | If transaction has a target wallet | |
Id | guid | The target wallet id |
Type | string | The target wallet type |
EventHistory | The transaction history events | |
CreatedAt | datetime | When the transaction event happened |
Event | string | The event happened |
EventDescription | string | The event description |
Status and events
Zūm Rails offers 3 main states for transactions:
Transaction Status
Type | Description |
---|---|
InProgress | Indicates the transaction is being processed |
Completed | Indicates the transaction is completed |
Failed | Indicates the transaction has failed |
Transaction Events
Zūm Rails also offers a more detailed transaction event, to indicate every step the transaction passed. Depending on the transaction methods, the events will change.
Method | Event | Description |
---|---|---|
All | Started | When the transaction started |
All | Succeded | When the transaction succed, when it finishesm without any error |
All | WalletFunded | When the transaction funds a wallet |
All | WalletWithdrawn | When the transaction withdrawn a wallet |
------- | ------- | ------- |
Eft | EFTFileCreated | When an EFT file is created. One transaction might have up to 2 files |
Eft | EFTFileUploaded | When an EFT file is uploaded |
Eft | EFTAnswerReceived | When an EFT file response is received |
Eft | EFTAnswerProcessed | When an EFT file is processed |
Eft | EftFailedValidationRejection | When EFT could not be created, due an invalid information provided |
Eft | EftFailedInsufficientFunds | When transaction is rejected, due non sufficient funds available |
Eft | EftFailedCannotLocateAccount | When account is not located, account, transit or institution numbers are invalid |
Eft | EftFailedStopPayment | Account do not allow EFT |
Eft | EftFailedAccountClosed | When account is closed |
Eft | EftFailedNoDebitAllowed | Account do not allow EFT |
Eft | EftFailedFundsNotFree | When transaction is rejected, due non sufficient funds available |
Eft | EftFailedCurrectAccountMismatch | When account is not located, account, transit or institution numbers are invalid |
Eft | EftFailedPayorPayeeDeceased | Account do not allow EFT |
Eft | EftFailedFrozenAccount | Account do not allow EFT |
Eft | EftFailedInvalidErrorAccountNumber | When account is not located, account numbers are invalid |
Eft | EftFailedErrorPayorPayeeName | When account is not located, first, last or company name (business) mismatch |
Eft | EftFailedRefusedNoAgreement | Account do not allow EFT |
Eft | EftFailedNotInAccountAgreementP | Account do not allow EFT |
Eft | EftFailedNotInAccountAgreementE | Account do not allow EFT |
Eft | EftFailedAgreementRevoked | Account do not allow EFT |
Eft | EftFailedDefaultByAFinancialInstitution | Generic error provided by the financial institution |
------- | ------- | ------- |
VisaDirect | VisaDirectNetworkTimeout | When Visa Network is unavailable - * We have never seen this :) |
VisaDirect | VisaDirectGenericError | When user data is invalid and rejected by Visa |
VisaDirect | VisaDirectNetworkDeclined | When there's no funds available, card do no allow Visa Direct or the account is closed |
------- | ------- | ------- |
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 | InteracFailedApiCancelation | Cancellation via API |
Interac | InteracFailedInicialization | Failed inicialization |
Interac | InteracFailedGenericError | When Interac Network is unavailable - * We have never seen this |
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 |
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 |
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 description",
"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 |
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 | When the recurrency must begin. yyyy-mm-dd |
EndDate | date | yes | When the recurrency must stop. yyyy-mm-dd |
Response
Parameter | Type | Description |
---|---|---|
Id | guid | Transaction id |
RecurrenceType
Type | Description |
---|---|
Monthly | A new transaction will be created once a month |
Biweekly | A new transaction will be created once every 2 weeks |
Weekly | A new transaction will be created per week |
DayOfWeek
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
Get recurrent transaction
> Response example:
{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"Id": "e60deffd-...-e9504f6a3a81",
"CreatedAt": "2020-04-28T14:48:06.916779",
"Memo": "",
"Comment": "",
"Amount": 0.01,
"ZumRailsType": "FundZumWallet",
"TransactionMethod": "Interac",
"StartDate": "2020-01-20T03:00:00",
"EndDate": "2021-08-28T04:00:00",
"RecurrenceType": "Weekly",
"DayOfWeek": "Monday",
"DayOfMonth": null,
"From": "Funding Source (RBC-01234-1234567)",
"To": "Zūm Wallet (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 |
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 | string | 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": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKg0KSm9objE7RG9lMTs7MTIzOzIzNDUxOzEyMzQ1NjcxOzEwMDtJbnRlcm5hbCBtZXNzYWdlIDE7TWVtbyBtZXNzYWdlIDENCkpvaG4yO0RvZTI7OzEyMzsyMzQ1MjsxMjM0NTY3MjsyMDA7SW50ZXJuYWwgbWVzc2FnZSAyO01lbW8gbWVzc2FnZSAyDQpKb2huMztEb2UzOzsxMjM7MjM0NTM7MTIzNDU2NzM7MzAwO0ludGVybmFsIG1lc3NhZ2UgMztNZW1vIG1lc3NhZ2UgMw0KSm9objQ7RG9lNDs7MTIzOzIzNDU0OzEyMzQ1Njc0OzQwMDtJbnRlcm5hbCBtZXNzYWdlIDQ7TWVtbyBtZXNzYWdlIDQNCkpvaG41O0RvZTU7OzEyMzsyMzQ1NTsxMjM0NTY3NTs1MDA7SW50ZXJuYWwgbWVzc2FnZSA1O01lbW8gbWVzc2FnZSA1IA0KSm9objY7RG9lNjs7MTIzOzIzNDU2OzEyMzQ1Njc2OzYwMDtJbnRlcm5hbCBtZXNzYWdlIDY7TWVtbyBtZXNzYWdlIDYNCkpvaG43O0RvZTc7OzEyMzsyMzQ1NzsxMjM0NTY3Nzs3MDA7SW50ZXJuYWwgbWVzc2FnZSA3O01lbW8gbWVzc2FnZSA3DQpKb2huODtEb2U4OzsxMjM7MjM0NTg7MTIzNDU2Nzg7ODAwO0ludGVybmFsIG1lc3NhZ2UgODtNZW1vIG1lc3NhZ2UgOA0KSm9objk7RG9lOTs7MTIzOzIzNDU5OzEyMzQ1Njc5OzkwMDtJbnRlcm5hbCBtZXNzYWdlIDk7TWVtbyBtZXNzYWdlIDkNCkpvaG4xMDtEb2UxMDs7MTIzOzM0NTEwOzEyMzQ1NjcxMDsxMDAwO0ludGVybmFsIG1lc3NhZ2UgMTA7TWVtbyBtZXNzYWdlIDEwDQo7O0NvbXBhbnkxMTsxMjM7MjM0MTE7MTIzNDU2NzExOzExMDA7SW50ZXJuYWwgbWVzc2FnZSAxMTtNZW1vIG1lc3NhZ2UgMTENCkpvaG4xMjtEb2UxMjs7MTIzOzIzNDEyOzEyMzQ1NjcxMjsxMjAwO0ludGVybmFsIG1lc3NhZ2UgMTI7TWVtbyBtZXNzYWdlIDEyDQpKb2huMTM7RG9lMTM7OzEyMzsyMzQxMzsxMjM0NTY3MTM7MTMwMDtJbnRlcm5hbCBtZXNzYWdlIDEzO01lbW8gbWVzc2FnZSAxMyA="
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"InvalidTransactions": "0",
"Status": "Ok",
"TotalAmount": 6,
"Transactions": [
{
"AccountNumber": "12345671",
"Amount": 1,
"Comment": "Internal message 1",
"CompanyName": "",
"CustomerId": null,
"FirstName": "John1",
"InstitutionNumber": "123",
"LastName": "Doe1",
"Memo": "Memo message 1",
"Status": "Ok",
"TransitNumber": "23451",
},
{
"AccountNumber": "12345672",
"Amount": 2,
"Comment": "Internal message 2",
"CompanyName": "",
"CustomerId": null,
"FirstName": "John2",
"InstitutionNumber": "123",
"LastName": "Doe2",
"Memo": "Memo message 2",
"Status": "Ok",
"TransitNumber": "23452",
},
{
"AccountNumber": "12345673",
"Amount": 3,
"Comment": "Internal message 3",
"CompanyName": "",
"CustomerId": null,
"FirstName": "John3",
"InstitutionNumber": "123",
"LastName": "Doe3",
"Memo": "Memo message 3",
"Status": "Ok",
"TransitNumber": "23453",
}
],
"ValidTransactions": 13
}
}
Method: POST
Endpoint: {{env}}/api/transaction/ValidateBatchFile
Use this endpoint if you want to validate a transactions batch file.
Input parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
TransactionType | string | yes | Transaction type |
WalletId | string | no | The Wallet Id, according to TransactionType |
FundingSourceId | string | no | The Funding Source Id |
Bytes | string | yes | The file's blob |
- Concerning
FundingSourceId
andWalletId
, just one of them must be sent
Response
Parameter | Type | Description |
---|---|---|
InvalidTransactions | string | The amount of invalid transactions |
ValidTransactions | int | The amount of valid transactions |
Status | string | The validation status |
TotalAmout | decimal | The sum of all transactions amount |
Transactions | ||
AccountNumber | string | The account number |
Amount | decimal | The transaction's amount |
Comment | string | The transaction's comment |
CompanyName | string | Company's name |
CustomerId | string | Customer id |
FirstName | string | User's first name |
LastName | string | User's last name |
InstitutionNumber | string | Institution's number |
Memo | string | The transaction's memo |
Status | string | The status |
TransitNumber | string | Transit number |
Each transaction will return a Status property explaining what is wrong with it
Status
Description |
---|
Ok |
First Name, Last Name or Company name are mandatory |
Either First and Last Name or Company Name should be informed |
Institution, Transit and Account numbers are mandatory |
Institution Number min length is 3 characters |
Transit Number length needs to be 5 characters |
Account Number min length is 5 characters |
Account Number max length is 12 characters |
Invalid amount |
Amount must be greater than zero |
Duplicated transaction |
Creating transactions through batch file
> Payload example:
{
"TransactionType": "AccountsReceivable",
"WalletAndFundingSource": "30126b59-ab21-491c-8033-008376504210",
"Bytes": "Zmlyc3RfbmFtZSo7bGFzdF9uYW1lKjtidXNpbmVzc19uYW1lO2luc3RpdHV0aW9uX251bWJlcio7YnJhbmNoX251bWJlcio7YWNjb3VudF9udW1iZXIqO2Ftb3VudF9pbl9jZW50cyo7dHJhbnNhY3Rpb25fY29tbWVudDttZW1vKg0KSm9objE7RG9lMTs7MTIzOzIzNDUxOzEyMzQ1NjcxOzEwMDtJbnRlcm5hbCBtZXNzYWdlIDE7TWVtbyBtZXNzYWdlIDENCkpvaG4yO0RvZTI7OzEyMzsyMzQ1MjsxMjM0NTY3MjsyMDA7SW50ZXJuYWwgbWVzc2FnZSAyO01lbW8gbWVzc2FnZSAyDQpKb2huMztEb2UzOzsxMjM7MjM0NTM7MTIzNDU2NzM7MzAwO0ludGVybmFsIG1lc3NhZ2UgMztNZW1vIG1lc3NhZ2UgMw0KSm9objQ7RG9lNDs7MTIzOzIzNDU0OzEyMzQ1Njc0OzQwMDtJbnRlcm5hbCBtZXNzYWdlIDQ7TWVtbyBtZXNzYWdlIDQNCkpvaG41O0RvZTU7OzEyMzsyMzQ1NTsxMjM0NTY3NTs1MDA7SW50ZXJuYWwgbWVzc2FnZSA1O01lbW8gbWVzc2FnZSA1IA0KSm9objY7RG9lNjs7MTIzOzIzNDU2OzEyMzQ1Njc2OzYwMDtJbnRlcm5hbCBtZXNzYWdlIDY7TWVtbyBtZXNzYWdlIDYNCkpvaG43O0RvZTc7OzEyMzsyMzQ1NzsxMjM0NTY3Nzs3MDA7SW50ZXJuYWwgbWVzc2FnZSA3O01lbW8gbWVzc2FnZSA3DQpKb2huODtEb2U4OzsxMjM7MjM0NTg7MTIzNDU2Nzg7ODAwO0ludGVybmFsIG1lc3NhZ2UgODtNZW1vIG1lc3NhZ2UgOA0KSm9objk7RG9lOTs7MTIzOzIzNDU5OzEyMzQ1Njc5OzkwMDtJbnRlcm5hbCBtZXNzYWdlIDk7TWVtbyBtZXNzYWdlIDkNCkpvaG4xMDtEb2UxMDs7MTIzOzM0NTEwOzEyMzQ1NjcxMDsxMDAwO0ludGVybmFsIG1lc3NhZ2UgMTA7TWVtbyBtZXNzYWdlIDEwDQo7O0NvbXBhbnkxMTsxMjM7MjM0MTE7MTIzNDU2NzExOzExMDA7SW50ZXJuYWwgbWVzc2FnZSAxMTtNZW1vIG1lc3NhZ2UgMTENCkpvaG4xMjtEb2UxMjs7MTIzOzIzNDEyOzEyMzQ1NjcxMjsxMjAwO0ludGVybmFsIG1lc3NhZ2UgMTI7TWVtbyBtZXNzYWdlIDEyDQpKb2huMTM7RG9lMTM7OzEyMzsyMzQxMzsxMjM0NTY3MTM7MTMwMDtJbnRlcm5hbCBtZXNzYWdlIDEzO01lbW8gbWVzc2FnZSAxMyA="
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false
}
Method: POST
Endpoint: {{env}}/api/transaction/ProcessBatchFile
Use this endpoint if you want to create transactions using a batch file
Input parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
TransactionType | string | yes | Transaction type |
WalletId | string | no | The Wallet Id, according to TransactionType |
FundingSourceId | string | no | The Funding Source Id |
Bytes | string | yes | The file's blob |
- Concerning
FundingSourceId
andWalletId
, just one of them must be sent
TransactionType
Type | Description |
---|---|
AccountsReceivable | Execute accounts receivable AR |
AccountsPayable | Execute accounts payable AP |
Request Funds - Checkout form
Zūm Request Funds, or Zūm Checkout is a prebuilt, hosted payment page optimized for conversion. You can use it to automatically onboard new users and automatically initiate online payments.
We allow you to collect payments online, accepting multiples payment methods :)
Creating a request funds form - checkout form
> Payload example:
{
"RequestFundsType": "Fixed",
"Amount": 123.45,
"WalletId": "30126b59-...-008376504211",
"AllowMoreThanOneTransaction": true
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"Id": "0bc9894d-....-f691024aca19",
"RequestFundsType": "Fixed",
"Amount": 123.45,
"WalletId": "30126b59-...-008376504211",
"ConnectUrl": "https://sandbox.zumrails.com/connect/...",
"QrCodeBytes": "iVBORw0K...",
"AllowMoreThanOneTransaction": 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 |
---|---|---|---|
RequestFundsType | string | yes | Determine if it's a fixed amount or variable (user inform at the checkout) |
Amount | string | no | Amount, in case RequestFundsType it's fixed |
WalletId | string | no | The WalletId if you want funds go to your wallet |
FundingSourceId | string | no | The FundingSourceId, if you want funds go directly to your funding source |
AllowMoreThanOneTransaction | boolean | no | If this request allows more than one transaction to be created |
Get a specific request funds - checkout form
> Response example:
{
"statusCode":200,
"message":"GET Request successful.",
"isError":false,
"result":
{
"Id":"017b530c-59f6-4f87-be26-524245efa0fd",
"CreatedAt":"2020-08-30T21:38:18.361931",
"RequestFundsType":"Fixed",
"Amount":123.45,
"WalletId":"5f515f01-...-8911a7c321a4",
"ConnectUrl":"https://sandbox.zumrails.com/#/connect/cf2ab7ae-...-be26-524245efa0fd",
"QrCodeBytes":"iVBORw0KGg..."
"TransactionsIds":[
"57cb547a-...-d169d5921d6a
"],
"AllowMoreThanOneTransaction": 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.
Response
Parameter | Type | Description |
---|---|---|
Id | guid | guid |
CreatedAt | datetime | When the form was created |
RequestFundsType | string | Determine if it's a fixed amount or variable (user inform at the checkout) |
Amount | string | Amount, in case RequestFundsType it's fixed |
WalletId | string | The WalletId if you want funds go to your wallet |
FundingSourceId | string | The FundingSourceId, if you want funds go directly to your funding source |
ConnectUrl | string | The url to open the request funds - checkout form |
QrCodeBytes | string | The representation of the ConnectUrl in byte array |
TransactionsIds | array | The list of transactions id that were initiated with this form |
AllowMoreThanOneTransaction | boolean | If the request allows more than 1 transaction to be created |
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:
- Users (only available for customers)
- Transactions (only available for customers)
- Customers (only available for partners)
> 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 webbook 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 |
The payload sent by the webhook has the same JSON format for the get User, Transaction and Customer.
Verifying authenticity
When Zūm Rails sends data to external services (e.g. when triggering a webhook to a service owned by you), the payload will be authenticated with a hash-based message authentication code (HMAC).
The key used to create the HMAC is your Webhook Secret, and you verify it by running the algorithm yourself with the payload and the key to re-create the HMAC. Your Webhook Secret can be found in the portal under your settings.
The signature is always sent with the webhook in a header named zumrails-signature
You can verify the authenticity of the webhook response by using HMAC. The HMAC verification process is as follows:
- You receive a POST request via the webhook
- Your app computes a signature based on paylod received, using your Webhook Secret
- You verify that your signature matches the zumrails-signature in the request
Here are the steps to validate a request coming from Zum Rails You’ll need the zumrails-signature sent by the webhook and your key (which is your Webhook Secret):
- Retrieve the zumrails-signature header
- Retrieve json body of the request. Make sure you are not adding any new spaces or formats.
- Using HMAC SHA256 implemented in your programming language, calculate the signature in your side. The body is the payload and the secret is your Webhook Secret.
- Compare your hash with the value provided under the zumrails-signature in the request, they should match.
A few examples on how to calculate HMAC in different languages: https://github.com/danharper/hmac-examples
Retry in case of failure
In the event of a failure to 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.
With the partner portal credentials in hand, you’ll first need to authorize with the api keys found in your /settings page. After that, you can call most of the APIs described here to view information from each one of your customers.
Need a partner account? Talk with us, it take seconds to send you a partner account invitation.
Creating a new customer
> Payload example:
{
"CompanyName": "Example Customer Company",
"TransactionDescriptionType": "Fixed",
"TransactionDescription": "Description",
"FirstName": "John",
"LastName": "Doe",
"PhoneNumber": "514-123-1234",
"Email": "examplecompany@zumrails.com",
"SendConfirmationEmail": false,
"Password": "examplePassword123",
"CustomerBillingType": "BuyRate",
"MonthlyCost": 16,
"CostPerTransaction": 1,
"CostPerUser": 2,
"CostPerBankRefresh": 4,
"CostPerNSF": 8,
"AddressStreet": "Street 01",
"AddressCity": "Toronto",
"AddressProvince": "ON",
"AddressPostalCode": "A1A-1A1",
"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",
"MonthlyCost": 16,
"CostPerTransaction": 1,
"CostPerUser": 2,
"CostPerBankRefresh": 4,
"CostPerNSF": 8,
"PercentagePerTransaction": 0,
"PercentagePerUser": 0,
"PercentagePerBankRefresh": 0,
"PercentagePerNSF": 0,
"CustomerAccountStatus": "PendingActivation",
"CustomerBillingType": "BuyRate",
"PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
"WebhookUrl": null,
"WebhookConfigurations":
[
{
"WebhookType": "Transaction",
"Name": "Succeeded",
"StatusValue": 8
},
{
"WebhookType": "User",
"Name": "Connected",
"StatusValue": 1
}
],
"WebhookConfigurations":
[
{
"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 |
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 |
CustomerBillingType | Customer Billing Type | yes | Defines how the billing will work (must be the same as the partner) |
MonthlyCost | number | yes | Monthly cost of the customer |
CostPerTransaction | number | yes | Cost/Percentage per transaction completed of the customer (must be greater than the partners cost per transaction) |
CostPerUser | number | yes | Cost/Percentage per user added of the customer (must be greater than the partners cost per user) |
CostPerBankRefresh | number | yes | Cost/Percentage per aggregation of the customer (must be greater than the partners cost per aggregation) |
CostPerNSF | number | yes | Cost/Percentage per NSF of the customer (must be greater than the partners cost per NSF) |
WebhookConfigurations | list of Webhook Configurations | no | A list containing webhook configurations. For more information, check Webhooks |
WebhookType | Webhook Type | yes | Type of the webhook |
StatusValue | int | yes | Value of the webhook |
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 |
Customer Billing Type
Type | Description |
---|---|
BuyRate | Fixed value for each operation |
PercentageSplit | Percentage from the quantity of each operation - Not available right now |
Webhook Configurations
WebhookType | Value | Name |
---|---|---|
User | 0 | NotConnected |
User | 1 | Connected |
User | 2 | Connecting |
User | 3 | Refreshing |
User | 4 | RefreshFailed |
Customer | 0 | Active |
Customer | 1 | PendingFundingSource |
Customer | 2 | PendingActivation |
Customer | 3 | PendingUnderwriting |
Transaction | 1 | Started |
Transaction | 8 | Succeeded |
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 | 301 | CreditCardError |
Transaction | 302 | CreditCardDeclined |
Transaction | 303 | CreditCardHeldForReview |
Transaction | 304 | CreditCardGenericError |
Transaction | 101 | VisaDirectNetworkDeclined |
Transaction | 102 | VisaDirectNetworkTimeout |
Transaction | 103 | VisaDirectGenericError |
Notification Method
Type | Description |
---|---|
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 |
E-mail of the company (also customer login) | ||
AddressStreet | string | Address street |
AddressCity | string | Address city |
AddressProvince | string | Address province |
AddressPostalCode | string | Address postal code |
WebhookUrl | string | Url to receive webhooks |
CustomerBillingType | Customer Billing Type | Defines how the billing will work |
MonthlyCost | number | Monthly cost of the customer |
CostPerTransaction | number | Cost per transaction completed of the customer (must be greater than the partners cost per transaction) |
CostPerUser | number | Cost per user added of the customer (must be greater than the partners cost per user) |
CostPerBankRefresh | number | Cost per aggregation of the customer (must be greater than the partners cost per aggregation) |
CostPerNSF | number | Cost per NSF of the customer (must be greater than the partners cost per NSF) |
PercentagePerTransaction | number | Percentage per transaction completed of the customer (must be greater than the partners cost per transaction) |
PercentagePerUser | number | Percentage per user added of the customer (must be greater than the partners cost per user) |
PercentagePerBankRefresh | number | Percentage per aggregation of the customer (must be greater than the partners cost per aggregation) |
PercentagePerNSF | number | Percentage per NSF of the customer (must be greater than the partners cost per NSF) |
PartnerId | guid | Partner id |
ActivationDate | datetime | The date when the customer was activated |
CreatedAt | datetime | When the customer was created |
CustomerAccountStatus | Customer Account Status | The customer account status |
WebhookConfigurations | List of webhook configurations of the customer | |
WebhookType | Webhook Type | Type of the webhook |
Name | string | Name of the webhook |
StatusValue | int | Value of the webhook |
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",
"PhoneNumber": "514-123-1234",
"Email": "examplecompany@zumrails.com",
"CustomerBillingType": "BuyRate",
"MonthlyCost": 20,
"CostPerTransaction": 1,
"CostPerUser": 2,
"CostPerBankRefresh": 4,
"CostPerNSF": 16,
"AddressCity": "City",
"AddressPostalCode": "88888888",
"AddressProvince": "Province",
"AddressStreet": "Street"
}
> Response example:
{
"statusCode": 200,
"message": "PUT Request successful.",
"isError": false,
"result": {
"Id": "f60d848a-5a45-4649-8968-48a83332d5bd",
"CompanyName": "Example Customer Company",
"TransactionDescriptionType": "Fixed",
"TransactionDescription": "Description",
"FirstName": "John",
"LastName": "Doe",
"Email": "examplecompany10@zumrails.com",
"PhoneNumber": "514-123-1234",
"AddressCity": "City",
"AddressPostalCode": "88888888",
"AddressProvince": "Province",
"AddressStreet": "Street",
"MonthlyCost": 20,
"CostPerTransaction": 1,
"CostPerUser": 2,
"CostPerBankRefresh": 4,
"CostPerNSF": 16,
"PercentagePerTransaction": 0,
"PercentagePerUser": 0,
"PercentagePerBankRefresh": 0,
"PercentagePerNSF": 0,
"CustomerAccountStatus": "Active",
"CustomerBillingType": "BuyRate",
"PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
"WebhookUrl": null,
"WebhookConfigurations": [],
"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 |
PhoneNumber | string | yes | Phone number |
yes | E-mail of the company (will be used as the customer login) | ||
AddressStreet | string | no | Address street |
AddressCity | string | no | Address city |
AddressProvince | string | no | Address province |
AddressPostalCode | string | no | Address postal code |
WebhookUrl | string | no | Url to receive webhooks |
CustomerBillingType | Customer Billing Type | yes | Defines how the billing will work (must be the same as the partner) |
MonthlyCost | number | yes | Monthly cost of the customer |
CostPerTransaction | number | yes | Cost/Percentage per transaction completed of the customer (must be greater than the partners cost per transaction) |
CostPerUser | number | yes | Cost/Percentage per user added of the customer (must be greater than the partners cost per user) |
CostPerBankRefresh | number | yes | Cost/Percentage per aggregation of the customer (must be greater than the partners cost per aggregation) |
CostPerNSF | number | yes | Cost/Percentage per NSF of the customer (must be greater than the partners cost per NSF) |
WebhookConfigurations | list of Webhook Configurations | yes | A list containing webhook configurations. For more information, check Webhooks |
WebhookType | Webhook Type | yes | Type of the webhook |
StatusValue | int | yes | Value of the webhook |
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 |
E-mail of the company (also customer login) | ||
AddressStreet | string | Address street |
AddressCity | string | Address city |
AddressProvince | string | Address province |
AddressPostalCode | string | Address postal code |
WebhookUrl | string | Url to receive webhooks |
CustomerBillingType | Customer Billing Type | Defines how the billing will work |
MonthlyCost | number | Monthly cost of the customer |
CostPerTransaction | number | Cost per transaction completed of the customer (must be greater than the partners cost per transaction) |
CostPerUser | number | Cost per user added of the customer (must be greater than the partners cost per user) |
CostPerBankRefresh | number | Cost per aggregation of the customer (must be greater than the partners cost per aggregation) |
CostPerNSF | number | Cost per NSF of the customer (must be greater than the partners cost per NSF) |
PercentagePerTransaction | number | Percentage per transaction completed of the customer (must be greater than the partners cost per transaction) |
PercentagePerUser | number | Percentage per user added of the customer (must be greater than the partners cost per user) |
PercentagePerBankRefresh | number | Percentage per aggregation of the customer (must be greater than the partners cost per aggregation) |
PercentagePerNSF | number | Percentage per NSF of the customer (must be greater than the partners cost per NSF) |
PartnerId | guid | Partner id |
ActivationDate | datetime | The date when the customer was activated |
CreatedAt | datetime | When the customer was created |
CustomerAccountStatus | Customer Account Status | The customer account status |
WebhookConfigurations | List of webhook configurations of the customer | |
WebhookType | Webhook Type | Type of the webhook |
Name | string | Name of the webhook |
StatusValue | int | Value of the webhook |
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",
"MonthlyCost": 16,
"CostPerTransaction": 1,
"CostPerUser": 2,
"CostPerBankRefresh": 4,
"CostPerNSF": 8,
"PercentagePerTransaction": 0,
"PercentagePerUser": 0,
"PercentagePerBankRefresh": 0,
"PercentagePerNSF": 0,
"CustomerAccountStatus": "Active",
"CustomerBillingType": "BuyRate",
"PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
"WebhookUrl": null,
"WebhookConfigurations": [],
"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",
}
}
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 |
E-mail of the company (also customer login) | ||
AddressStreet | string | Address street |
AddressCity | string | Address city |
AddressProvince | string | Address province |
AddressPostalCode | string | Address postal code |
WebhookUrl | string | Url to receive webhooks |
CustomerBillingType | Customer Billing Type | Defines how the billing will work |
MonthlyCost | number | Monthly cost of the customer |
CostPerTransaction | number | Cost per transaction completed of the customer (must be greater than the partners cost per transaction) |
CostPerUser | number | Cost per user added of the customer (must be greater than the partners cost per user) |
CostPerBankRefresh | number | Cost per aggregation of the customer (must be greater than the partners cost per aggregation) |
CostPerNSF | number | Cost per NSF of the customer (must be greater than the partners cost per NSF) |
PercentagePerTransaction | number | Percentage per transaction completed of the customer (must be greater than the partners cost per transaction) |
PercentagePerUser | number | Percentage per user added of the customer (must be greater than the partners cost per user) |
PercentagePerBankRefresh | number | Percentage per aggregation of the customer (must be greater than the partners cost per aggregation) |
PercentagePerNSF | number | Percentage per NSF of the customer (must be greater than the partners cost per NSF) |
PartnerId | guid | Partner id |
ActivationDate | datetime | The date when the customer was activated |
CreatedAt | datetime | When the customer was created |
CustomerAccountStatus | Customer Account Status | The customer account status |
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",
"Status": "PendingActivation",
"Pagination": {
"PageNumber": 1
}
}
> Response example:
{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"CurrentPage": 1,
"PageSize": 8,
"TotalCount": 1,
"Items": [
{
"Id": "49a5b2ef-4297-4b22-b97e-c0ce677dbc66",
"CompanyName": "Example Customer Company",
"TransactionDescriptionType": "Fixed",
"TransactionDescription": "Description",
"FirstName": "John",
"LastName": "Doe",
"Email": "examplecompany7@zumrails.com",
"PhoneNumber": "514-123-1234",
"AddressStreet": null,
"AddressCity": null,
"AddressProvince": null,
"AddressPostalCode": null,
"MonthlyCost": 16,
"CostPerTransaction": 1,
"CostPerUser": 2,
"CostPerBankRefresh": 4,
"CostPerNSF": 8,
"PercentagePerTransaction": 0,
"PercentagePerUser": 0,
"PercentagePerBankRefresh": 0,
"PercentagePerNSF": 0,
"CustomerAccountStatus": "PendingActivation",
"CustomerBillingType": "BuyRate",
"PartnerId": "e2fc8f54-ce6f-4f4c-8367-2eea0aca7ffd",
"WebhookUrl": null,
"WebhookConfigurations": [],
"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 |
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 |
E-mail of the company (also customer login) | ||
AddressStreet | string | Address street |
AddressCity | string | Address city |
AddressProvince | string | Address province |
AddressPostalCode | string | Address postal code |
WebhookUrl | string | Url to receive webhooks |
CustomerBillingType | Customer Billing Type | Defines how the billing will work |
MonthlyCost | number | Monthly cost of the customer |
CostPerTransaction | number | Cost per transaction completed of the customer (must be greater than the partners cost per transaction) |
CostPerUser | number | Cost per user added of the customer (must be greater than the partners cost per user) |
CostPerBankRefresh | number | Cost per aggregation of the customer (must be greater than the partners cost per aggregation) |
CostPerNSF | number | Cost per NSF of the customer (must be greater than the partners cost per NSF) |
PercentagePerTransaction | number | Percentage per transaction completed of the customer (must be greater than the partners cost per transaction) |
PercentagePerUser | number | Percentage per user added of the customer (must be greater than the partners cost per user) |
PercentagePerBankRefresh | number | Percentage per aggregation of the customer (must be greater than the partners cost per aggregation) |
PercentagePerNSF | number | Percentage per NSF of the customer (must be greater than the partners cost per NSF) |
PartnerId | guid | Partner id |
ActivationDate | datetime | The date when the customer was activated |
CreatedAt | datetime | When the customer was created |
CustomerAccountStatus | Customer Account Status | The customer account status |
WebhookConfigurations | List of webhook configurations of the customer | |
WebhookType | Webhook Type | Type of the webhook |
Name | string | Name of the webhook |
StatusValue | int | Value of the webhook |
Underwriting - Upload a document
> Request example:
{
"FileName": "File.txt",
"CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
"UnderwritingType": "VoidCheque",
"Bytes": "dGVzdA=="
}
> Response example:
{
"isError": false,
"message": "POST Request successful.",
"statusCode": 200,
"result": {
"CreatedAt": "2020-08-21T20:33:41.8367114Z",
"FileName": "File.txt",
"CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
"Id": "f6ba6f0a-cd6d-47c3-b9b4-2d9f8d406870",
"UnderwritingType": "VoidCheque"
}
}
Method: POST
Endpoint: {{env}}/api/underwriting
Use this endpoint if you want to upload an underwriting file for a specific customer.
Input parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
FileName | string | yes | The name of the file |
CustomerId | guid | yes | Customer id |
UnderwritingType | Underwriting Type | yes | The type of the underwriting file |
Bytes | string byte array | yes | A string byte array that represents the file |
Underwriting Type
Type | Description |
---|---|
VoidCheque | Void cheque |
DriversLicenseCopy | Driver's License copy |
ProofBusinessRegistrationCopy | Proof of Business Registration copy |
GovernmentPhotoId | Government photo ID |
Response
Parameter | Type | Description |
---|---|---|
Id | guid | Underwriting id |
FileName | string | The name of the file |
CustomerId | guid | Customer id |
UnderwritingType | Underwriting Type | The type of the underwriting file |
CreatedAt | date | When the underwriting was created |
Underwriting - Retrieve customer's documents
> Response example:
{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": [
{
"Customer": {
"Id": "30126b59-ab21-491c-8033-0083765042f2",
"CompanyName": "Company To Test"
},
"Id": "ec665bd9-d16b-4160-9504-9dd7c149e406",
"CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
"FileName": "testfile1.xlsx",
"UnderwritingType": "DriversLicenseCopy",
"CreatedAt": "2020-09-30T15:33:11.001283"
},
{
"Customer": {
"Id": "30126b59-ab21-491c-8033-0083765042f2",
"CompanyName": "Company To Test"
},
"Id": "bf57ba0e-cd09-42ce-8c92-605d1359aa68",
"CustomerId": "30126b59-ab21-491c-8033-0083765042f2",
"FileName": "testfile2.xlsx",
"UnderwritingType": "GovernmentPhotoId",
"CreatedAt": "2020-09-30T15:33:04.256208"
}
]
}
Method: GET
Endpoint: {{env}}/api/underwriting/customer/{customer_id}
Use this endpoint if you want to retrieve all uploaded underwriting files from a specific customer. The customer id is informed in the url.
Response
Parameter | Type | Description |
---|---|---|
Id | guid | The underwriting id |
CustomerId | guid | The customer id |
FileName | string | The underwriting's file name |
UnderwritingType | string | The underwriting's type (VoidCheque, DriversLicenseCopy, ProofBusinessRegistrationCopy or GovernmentPhotoId) |
CreatedAt | datetime | When the underwriting was created |
Customer | Customer's information | |
Id | guid | Customer id |
CompanyName | string | The company name |
Underwriting - Retrieve specific underwriting file
> Response example:
{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": "dGVzdCBjYXNlcw0KMS4gdXNlciAxIHJlY2VpdmVzIDk..."
}
Method: GET
Endpoint: {{env}}/api/underwriting/{underwriting_id}
Use this endpoint if you want to retrieve a specific underwriting file. The underwriting id is informed in the url.
Response
Type | Description |
---|---|
string byte array | A string byte array that represents the file |
Idempotency
In Zūm APIs, idempotency means that requests that have been previously processed successfully are not reprocessed again. The response for the completed processing is reported instead.
All POST
requests accept idempotency keys. Sending idempotency keys in GET
and DELETE
requests will have no effect, as these type of requests are idempotent by definition.
To submit a request with idempotent processing, add the key idempotency-key
in the header. The value for this key should be a unique identifier for the message with a maximum of 36 characters (we recommend a UUID). If you don't receive a response (for example, in case of a timeout), you can safely retry the request with the same header. If we have already processed the request, the response to the first attempt will be returned without duplicating the request in our database.
Idempotency keys are persisted in Zūm Rails side for 1 year, 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. |