Users

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

Zūm Rails recommends using Zūm Connect for the below reasons:

  • 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 that we reduce your PCI scope.

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

Creating a new 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.

{
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@zumrails.com",
"companyName": null,
"phoneNumber": "5141231234",
"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"
},
"ShippingSameAsBilling": false,
"Addresses":[
{
"AddressCity": "User City",
"AddressCountry": "Canada",
"AddressLine1": "user address 122",
"AddressLine2": "test222",
"AddressPostalCode": "J4V0A3",
"AddressState": "QC",
"AddressType": "Shipping"
}]
}

Method: POST

Endpoint: {{env}}/api/user

Input parameters

ParameterTypeEFT (Mandatory)Interac (Mandatory)Credit Card (Mandatory)Visa Direct (Mandatory)Description
FirstNamestringyesyesyesyesUser first name
LastNamestringyesyesyesyesUser last name
CompanyNamestringnoyesyesyesCompany name, in case it's a company
EmailstringyesyesyesyesUser e-mail
PhoneNumberstringnonononoPhone number (maximum 10 characters, no special characters accepted)
BankAccountInformationyes
InstitutionNumberstringyesnononoInstitution Number, 3 digits
TransitNumberstringyesnononoTransit Number, 5 digits
AccountNumberstringyesnononoAccount Number
CreditCardInformationyesyes
Numberstringnonoyesyes
ExpireMonthnumbernonoyesyesCard expiry month, 2 digits
ExpireYearnumbernonoyesyesCard expiry year, 4 digits
CVVstringnonoyesyesSecurity code, 3 or 4 digits
AddressLine1stringnonoyesnoBilling address line 1 (maximum 30 characters)
AddressLine2stringnonoyesnoBilling address line 2 (maximum 30 characters)
AddressPostalCodestringnonoyesnoBilling address postal code
AddressCountrystringnonoyesnoBilling address country
AddressCitystringnonoyesnoBilling address city (maximum 20 characters)
AddressStatestringnonoyesnoBilling address state/province
caution

CVV and Expire Month/Year are mandatory for all transaction types with the Visa Direct/Credit Card payment methods.

Response

ParameterTypeDescription
idguidUser id
firstNamestringFirst name
lastNamestringLast name
companyNamestringCompany name, in case it's a company

Update user#

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.

{
"firstName": "John",
"lastName": "Doe",
"companyName": null,
"email": "johndoe@zumrails.com",
"phoneNumber": "5141231234"
}

Method: PATCH

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

Input parameters

ParameterTypeEFT (Mandatory)Interac (Mandatory)Credit Card (Mandatory)Visa Direct (Mandatory)Description
FirstNamestringyesyesyesyesUser first name
LastNamestringyesyesyesyesUser last name
CompanyNamestringnoyesyesyesCompany name, in case it's a company
EmailstringyesyesyesyesUser e-mail
PhoneNumberstringnonononoPhone number (maximum 10 characters, no special characters accepted)

Response

ParameterTypeDescription
idguidUser id

Update bank account information#

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.

{
"institutionNumber": "111",
"transitNumber": "12345",
"accountNumber": "1234567"
}

Method: PATCH

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

Input parameters

ParameterTypeEFT (Mandatory)Description
InstitutionNumberstringyesInstitution Number, 3 digits
TransitNumberstringyesTransit Number, 5 digits
AccountNumberstringyesAccount Number

Response

ParameterTypeDescription
idguidUser id

Update credit card information#

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

{
"Number": "4242424242424242",
"ExpireMonth": "01",
"ExpireYear": "2025",
"CVV": "111",
"AddressLine1": "123 street",
"AddressLine2": "Apartment 123",
"AddressPostalCode": "A1A 1A1",
"AddressCountry": "Canada",
"AddressCity": "Toronto",
"AddressState": "ON"
}

Method: PATCH

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

Input parameters

ParameterTypeCredit Card (Mandatory)Visa Direct (Mandatory)Description
Numberstringyesyes
ExpireMonthnumberyesyesCard expiry month, 2 digits
ExpireYearnumberyesyesCard expiry year, 4 digits
CVVstringyesyesSecurity code, 3 or 4 digits
AddressLine1stringnoyesBilling address line 1 (maximum 30 characters)
AddressLine2stringnoyesBilling address line 2 (maximum 30 characters)
AddressPostalCodestringnoyesBilling address postal code
AddressCountrystringnoyesBilling address country (Canada)
AddressCitystringnoyesBilling address city (maximum 20 characters)
AddressStatestringnoyesBilling address state/province

Response

ParameterTypeDescription
idguidUser id

Update credit card billing address information#

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

{
"AddressLine1": "123 street",
"AddressLine2": "Apartment 123",
"AddressPostalCode": "A1A 1A1",
"AddressCountry": "Canada",
"AddressCity": "Toronto",
"AddressState": "ON"
}

Method: PATCH

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

Input parameters

ParameterTypeCredit Card (Mandatory)Visa Direct (Mandatory)Description
AddressLine1stringnoyesBilling address line 1 (maximum 30 characters)
AddressLine2stringnoyesBilling address line 2 (maximum 30 characters)
AddressPostalCodestringnoyesBilling address postal code
AddressCountrystringnoyesBilling address country (Canada)
AddressCitystringnoyesBilling address city (maximum 20 characters)
AddressStatestringnoyesBilling address state/province

Response

ParameterTypeDescription
idguidUser id

Update user shipping address information#

{
"AddressLine1": "123 street",
"AddressLine2": "Apartment 123",
"AddressPostalCode": "A1A 1A1",
"AddressCountry": "Canada",
"AddressCity": "Toronto",
"AddressState": "ON"
}

Method: PATCH

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

Use this endpoint if you want to update the shipping address information from a user. The user id is informed in the url and the body payload contains the address information.

info

The boolean sameAsBilling informs us to use the billing address as shipping address.

Input parameters

ParameterTypeCredit Card (Mandatory)Visa Direct (Mandatory)Description
AddressLine1stringnoyesshipping address line 1 (maximum 30 characters)
AddressLine2stringnoyesshipping address line 2 (maximum 30 characters)
AddressPostalCodestringnoyesshipping address postal code
AddressCountrystringnoyesshipping address country (Canada)
AddressCitystringnoyesshipping address city (maximum 20 characters)
AddressStatestringnoyesshipping address state/province

Response

ParameterTypeDescription
idguidUser id
sameAsBillingbooleanUse the billing address as shipping address if true

Get a specific user#

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

Method: GET

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

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

Response

ParameterTypeDescription
Idguidguid
CreatedAtdatetimeWhen the user was created
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
PhoneNumberstringLast name
EmailstringLast name
LastRefreshdatetimeLast name
BankAccountInformation
InstitutionstringInstitution name
InstitutionNumberstringInstitution Number
TransitNumberstringTransit Number
AccountNumberstringAccount Number
FirstNamestringLast name
LastNamestringLast name
AggregationStatusstringIndicate if the account is Connected
LastTimeRefresheddatetimeWhen the last refresh happened
AggregationFailedReasonstringIf failed, informs the failure reason
AggregationBalancedecimalEFT account current balance
CreditCardInformation
NumberstringLast for digits only
ExpireMonthnumberCard expiry month, 2 digits
ExpireYearnumberCard expiry year, 4 digits
CVVstringSecurity code, 3 or 4 digits
AddressLine1stringBilling address line 1 (maximum 30 characters)
AddressLine2stringBilling address line 2 (maximum 30 characters)
AddressPostalCodestringBilling address postal code
AddressCountrystringBilling address country
AddressCitystringBilling address city (maximum 20 characters)
AddressStatestringBilling address state/province
BrandNamestringThe brand, Visa, Master, etc.
InstitutionstringThe institution of the card, valid for Visa Direct when using aggregation
VerifyCreditCardStatusstringIf it is credit card and the card is verified
TransactionsMethodsAvailable
EftBooleanIndicate if this user can do EFT transactions
VisaDirectPullBooleanIndicate if this user can do Visa Direct PULL transactions
VisaDirectPushBooleanIndicate if this user can do Visa Direct PUSH transactions
InteracBooleanIndicate if this user can do Interac transactions
CreditCardBooleanIndicate if this user can do Credit Card transactions

AggregationStatus

StatusDescription
NotConectedThe account is not linked using Zūm Connect
ConnectedAccount is fully connected and ready to be used
ConnectingProcess underway to link account
RefreshingThe account is linked, but the aggregation service is still refreshing/connecting the account.
RefreshFailedThe account was linked but the aggregation service could not refresh the most updated information
info

When a new user is added using Zūm Connect, with financial data aggregation, it might take a few minutes until the account is completely connected. The Field BankAccountInformation. AggregationStatus will indicate when the account is connected. If the response is: Refreshing, call this endpoint again after 30 seconds.

tip

Some credit cards do not allow Visa Direct, if they have a credit card informed and it allows Visa Direct, the field CreditCardInformation.VisaDirect will be true.

Interac - Send Funds options#

info

This endpoint is not available for all Zūm Rails customers, if you need to use it, make sure to talk with our team.

Use this endpoint if you want to know if the user is registered for automatic deposits, or if it's account rounter number eligible. The user id is informed in the url.

{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"RequireSecurityQuestionAndAnswer": true,
"AutomaticDepositAvailable": false,
"AccountNumberRoutingAvailable": false,
"Limit": 5000.0,
"RecipientType": "INDIVIDUAL"
}
}

Method: GET

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

Response

ParameterTypeDescription
RequireSecurityQuestionAndAnswerbooleanIndicate if security questions are required for the informed user in order to create an Interac Send Funds
AutomaticDepositAvailablebooleanIf true, means this user email is registered for Interac automatic deposit
AccountNumberRoutingAvailablebooleanIf true, means this user can accept Interac Account Routing ANR. The user needs to have the bank account information on file.
LimitdecimalThe maximum amount that can be sen't using Interac to this user
RecipientTypestringIndicate if this user is registered with Interac as INDIVIDUAL, SMALL_BUSINESS or CORPORATION

Interac - Register auto deposit#

info

This endpoint is not available for all Zūm Rails customers, if you need to use it, make sure to talk with our team.

Use this endpoint if you want to register a user for automatic deposits into your Zūm Rails wallet.

For example, if you register a user with the email john@smith.com, then any Interac Send Funds initiated to john@smith.com will be automatically deposited into your Zūm Rails wallet.

{}

Method: PATCH

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

note

After the request for registration is intiated, the user will receive an email from Interac to accept. Only after accepted, the auto deposit will be enabled.

Interac - Cancel auto deposit#

info

This endpoint is not available for all Zūm Rails customers, if you need to use it, make sure to talk with our team.

Use this endpoint if you have previosly registered a user for automatic deposit with Zūm Rails. This will send a request to unregister the user with Interac rails.

{}

Method: PATCH

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

Interac - Get auto deposit information#

info

This endpoint is not available for all Zūm Rails customers, if you need to use it, make sure to talk with our team.

Use this endpoint if you have a user that was previosly registered for automatic deposit and you want to know the status of the registration.

This endpoint can be used to get to know if the user has accepted or declined the email received from Interac right after the registration, for example.

{}

Method: GET

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

note

After you registered a user for automatic deposit, and the user has accept, at any moment the same user can go to another bank and register the same email there, when this is done, the status will change from ACTIVE to NOT_ACTIVE

Auto Deposit Status

StatusDescription
PENDINGPending user to confirm the email received from Interac
ACTIVEAuto deposit active with Zūm Rails
IN_REVIEWThe request is being reviwed by Interac
NOT_ACTIVEThe request is not active anymore
EXPIREDThe request is expired
DECLINEDThe request declined the email received from Interac
REPORTEDThe user or Interac reported this request as not valid

Delete a user#

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

Method: DELETE

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

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

Search for a user#

{
"CreatedAtOperator": "isBetween",
"CreatedAtFrom":"2020-05-13T04:00:00.000Z",
"CreatedAtTo":"2020-05-13T04:00:00.000Z",
"FirstName":"john",
"LastName":"Doe",
"Email":"johndoe@gmail.com",
"Pagination": {
"PageNumber": 1
}
}

Method: POST

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

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

Date operators

TypeDescription
IsInTheLastFilter records on or after
ExactlyMatchesFilter records with exact date
IsBetweenFilters records in range
IsAfterFilter records after date
IsOnOrAfterFilter records on or after
IsBeforeFilter records before date
IsBeforeOrOnFilter records before or on date

Input parameters

ParameterTypeMandatoryDescription
GenericSearchstringnoFilter users by user name and user email
NamestringnoFirst and/or Last name
CreatedAtdatetimenoCreate date
CreatedAtFromdatetimenoStart date (This field is only used when the operator is between)
CreatedAtTodatetimenoEnd date (This field is only used when the operator is between)
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
EmailstringnoUser email
Paginationno
PageNumbernumbernoThe respective page, starting at 1

Response

ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
Items
Idguidguid
CreatedAtdatetimeWhen the user was created
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
EmailstringLast name
BankAccountInformation* if available
LastTimeRefresheddatetimeLast time the account was refreshed
AggregationStatusstringIndicates if the account is linked with the aggregation service
AggregationBalancedecimalAccount balance
info

We recommend you search by a respective user, retrieve the user id and then use the GET specific user endpoint to retrieve the detailed information about the user.