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.

Method: POST

Endpoint: {{env}}/api/user

Payload
Response

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@zumrails.com",
  "companyName": null,
  "phoneNumber": "5141231234",
  "clientUserId": "*",
  "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"
    }
  ]
}

Input parameters

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

caution

When creating a user, provide FirstName and LastName if the user is an individual, or provide CompanyName if the user is a business.
CVV and Expire Month/Year are mandatory for all transaction types with the Visa Direct/Credit Card payment methods.

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

Creating a New User for Aggregators#

Use this endpoint if you want to add a new user to your account. Only if you are using a third-party aggregator.

Method: POST

Endpoint: {{env}}/api/user

Payload
Response

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "johndoe@zumrails.com",
  "AuthCode": "N_8_TAx[RD_QqDQy6oBCEMZuFTsSg39qysvuMKuVA28nyx-Z"
}

Input parameters

Parameter	Type	Mandatory	Description
FirstName	string	yes	User first name
LastName	string	yes	User last name
Email	string	yes	User e-mail
AuthCode	string	yes	Key used to get an access_code

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.

Method: PATCH

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

Payload
Response

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

Input parameters

Parameter	Type	EFT (Mandatory)	Interac (Mandatory)	Credit Card (Mandatory)	Visa Direct (Mandatory)	Description
FirstName	string	yes	yes	yes	yes	User first name. Character limit is 120.
LastName	string	yes	yes	yes	yes	User last name. Character limit is 120.
CompanyName	string	no	yes	yes	yes	Company name, in case it's a company. Character limit is 120.
Email	string	yes	yes	yes	yes	User e-mail
PhoneNumber	string	no	no	no	no	Phone number (maximum 10 characters, no special characters accepted)
ClientUserId	string	no	no	no	no	External Client User Identifier

Response

Parameter	Type	Description
id	guid	User 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.

Method: PATCH

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

Payload
Response

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

Input parameters

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

Response

Parameter	Type	Description
id	guid	User id

Update credit card information#

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.

Method: PATCH

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

Payload
Response

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

Input parameters

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

Response

Parameter	Type	Description
id	guid	User 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.

Method: PATCH

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

Payload
Response

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

Input parameters

Parameter	Type	Credit Card (Mandatory)	Visa Direct (Mandatory)	Description
AddressLine1	string	no	yes	Billing address line 1 (maximum 60 characters)
AddressLine2	string	no	yes	Billing address line 2 (maximum 60 characters)
AddressPostalCode	string	no	yes	Billing address postal code
AddressCountry	string	no	yes	Billing address country (Canada)
AddressCity	string	no	yes	Billing address city (maximum 32 characters)
AddressState	string	no	yes	Billing address state/province

Response

Parameter	Type	Description
id	guid	User id

Update user shipping address information#

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.

Method: PATCH

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

info

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

Payload
Response

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

Input parameters

Parameter	Type	Credit Card (Mandatory)	Visa Direct (Mandatory)	Description
AddressLine1	string	no	yes	shipping address line 1 (maximum 60 characters)
AddressLine2	string	no	yes	shipping address line 2 (maximum 60 characters)
AddressPostalCode	string	no	yes	shipping address postal code
AddressCountry	string	no	yes	shipping address country (Canada)
AddressCity	string	no	yes	shipping address city (maximum 32 characters)
AddressState	string	no	yes	shipping address state/province

Response

Parameter	Type	Description
id	guid	User id
sameAsBilling	boolean	Use the billing address as shipping address if true

Get a specific user#

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

Method: GET

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

Response

{
  "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",
    "ClientUserId": "*",
    "LastRefresh": "0001-01-01T00:00:00",
    "AggregationRequestId": "15bb883e-e0bb-4a58-9a2c-f8ff234033b4",
    "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,
      "NameMatch": {
        "Score": 90,
        "Result": "Matched"
      }      
    },
    "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
    }
  }
}

Response

Parameter	Type	Description
Id	guid	User id
CreatedAt	datetime	When the user was created
FirstName	string	First name
LastName	string	Last name
CompanyName	string	Company name
PhoneNumber	string	Last name
Email	string	Last name
ClientUserId	string	External Client User Identifier
LastRefresh	datetime	Last name
AggregationRequestId	guid	Unique identifier of the aggregation request
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
NameMatch.Score	number	A numerical value between 0 and 100 indicating the similarity between the provided user name and the name on the bank account. Scores exceeding 90 suggest a high degree of match
NameMatch.Result	string	A description of the name-match score. It can be “Matched” or “Not Matched”
CreditCardInformation
Number	string	Last for digits only
ExpireMonth	number	Card expiry month, 2 digits
ExpireYear	number	Card expiry year, 4 digits
CVV	string	Security code, 3 or 4 digits
AddressLine1	string	Billing address line 1 (maximum 60 characters)
AddressLine2	string	Billing address line 2 (maximum 60 characters)
AddressPostalCode	string	Billing address postal code
AddressCountry	string	Billing address country
AddressCity	string	Billing address city (maximum 32 characters)
AddressState	string	Billing address state/province
BrandName	string	The brand, Visa, Master, etc.
Institution	string	The institution of the card, valid for Visa Direct when using aggregation
VerifyCreditCardStatus	string	If it is credit card and the card is verified
TransactionsMethodsAvailable
Eft	Boolean	Indicate if this user can do EFT transactions
VisaDirectPull	Boolean	Indicate if this user can do Visa Direct PULL transactions
VisaDirectPush	Boolean	Indicate if this user can do Visa Direct PUSH transactions
Interac	Boolean	Indicate if this user can do Interac transactions
CreditCard	Boolean	Indicate if this user can do Credit Card transactions

AggregationStatus

Status	Description
NotConnected	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

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 router number eligible. The user id is informed in the url.

Method: GET

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

Response

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

Response

Parameter	Type	Description
RequireSecurityQuestionAndAnswer	boolean	Indicate if security questions are required for the informed user in order to create an Interac Send Funds
AutomaticDepositAvailable	boolean	If true, means this user email is registered for Interac automatic deposit
AccountNumberRoutingAvailable	boolean	If true, means this user can accept Interac Account Routing ANR. The user needs to have the bank account information on file.

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.

Method: PATCH

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

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.

Payload
Response

{}

note

After the request for registration is initiated, 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 previously 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}

Payload
Response

{}

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 previously registered for automatic deposit and you want to know the status of the registration.

Method: GET

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

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.

Payload
Response

{}

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

Status	Description
PENDING	Pending user to confirm the email received from Interac
ACTIVE	Auto deposit active with Zūm Rails
IN_REVIEW	The request is being reviewed by Interac
NOT_ACTIVE	The request is not active anymore
EXPIRED	The request is expired
DECLINED	The request declined the email received from Interac
REPORTED	The user or Interac reported this request as not valid

Delete a user#

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.

Method: DELETE

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

Response

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

Search for a user#

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.

Method: POST

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

Payload
Response

  {
      "CreatedAtOperator": "isBetween",
      "CreatedAtFrom":"2020-05-13T04:00:00.000Z",
      "CreatedAtTo":"2020-05-13T04:00:00.000Z",
      "UserName":"John Doe",
      "Email":"johndoe@gmail.com",
      "ClientUserIdOperator": "contains",
      "ClientUserId": "*"
      "Pagination": {
          "PageNumber": 1
      }
  }

Date operators

Type	Description
IsInTheLast	Filter records on or after
ExactlyMatches	Filter records with exact date
IsBetween	Filters records in range
IsAfter	Filter records after date
IsOnOrAfter	Filter records on or after
IsBefore	Filter records before date
IsBeforeOrOn	Filter records before or on date

Input parameters

Parameter	Type	Mandatory	Description
GenericSearch	string	no	Filter users by user name and user email
UserName	string	no	First and/or Last name
CreatedAt	datetime	no	Create date
CreatedAtFrom	datetime	no	Start date (This field is only used when the operator is between)
CreatedAtTo	datetime	no	End date (This field is only used when the operator is between)
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties
Email	string	no	User email
ClientUserId	string	no	External Client User Identifier
ClientUserIdOperator	string	Operator to filter with ClientUserId
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		List of users
Id	guid	User id
CreatedAt	datetime	When the user was created
FirstName	string	First name
LastName	string	Last name
CompanyName	string	Company name
Email	string	Last name
ClientUserId	string	External Client User Identifier
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
NameMatch.Score	number	A numerical value between 0 and 100 indicating the similarity between the provided user name and the name on the bank account. Scores exceeding 90 suggest a high degree of match
NameMatch.Result	string	A description of the name-match score. It can be “Matched” or “Not Matched”

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.