Users
Last updated
Was this helpful?
Last updated
Was this helpful?
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, .
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
Input parameters
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.
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.
When an SSN is provided for a User, then IdNumber should be 9 digits.
To skip bank account verification, speak to your account executive or reach out to support.
Response (Canada)
id
guid
User id
firstName
string
First name
lastName
string
Last name
companyName
string
Company name, in case it's a company
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
FirstName*
string
First name, if the User is an individual.
LastName*
string
Last name, if User is an individual. Maximum 100 characters.
CompanyName*
string
Company name, if User is a company. Maximum 100 characters.
Email*
string
Email address
PhoneNumber
string
Phone number. Maximum 10 characters (no special characters).
ClientUserId
string
External identifier for the User.
BankAccountInformation
InstitutionNumber
string
Institution Number, 3 digits
TransitNumber
string
Transit Number, 5 digits
AccountNumber
string
Account Number
CreditCardInformation
Number
string
ExpireMonth
string
Card expiry month, 2 digits.
ExpireYear
string
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.
AddressCity
string
Billing address city. Maximum 32 characters.
AddressState
string
AddressPostalCode
string
Billing address postal code
AddressCountry
string
Billing address country
Addresses
AddressType
string
??
AddressLine1
string
Shipping address line 1. Maximum 60 characters.
AddressLine2
string
Shipping address line 2. Maximum 60 characters.
AddressCity
string
Shipping address city. Maximum 32 characters.
AddressState
string
AddressPostalCode
string
Shipping address postal code
AddressCountry
string
Shipping address country
Input parameters
FirstName
string
yes
User first name
LastName
string
yes
User last name
string
yes
User e-mail
AuthCode
string
yes
Key used to get an access_code
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}
Input parameters
FirstName
string
yes
yes
yes
yes
yes
User first name. Character limit is 100.
LastName
string
yes
yes
yes
yes
yes
User last name. Character limit is 100.
CompanyName
string
no
yes
yes
no
yes
Company name, in case it's a company. Character limit is 100.
string
yes
yes
yes
yes
yes
User e-mail
PhoneNumber
string
no
no
no
on
no
Phone number (maximum 10 characters, no special characters accepted)
ClientUserId
string
no
no
no
no
no
External Client User Identifier
DateOfBirth
date
no
no
no
yes
no
Date of birth
Response
id
guid
User id
Use this endpoint to add a payment instrument's information for an existing user. Include the user id as a path parameter in the URL and the new values in the body payload.
Method: POST
Endpoint: {{env}}/api/user/AddPaymentInstrumentInformation/{user_id}
This endpoint is only available to US customers.
Request parameters
AccountType
string
yes
-
-
Account Type can be either Checking or Savings
RoutingNumber
string
yes
-
-
Routing Number, 9 digits
AccountNumber
string
yes
-
-
Account Number
ExternallyVerified
boolean
no
-
-
Set to true to skip bank account verification
Number
string
-
yes
yes
Card number, 16 digits
ExpireMonth
string
-
yes
yes
Card expiry month, 2 digits
ExpireYear
string
-
yes
yes
Card expiry year, 4 digits
Cvv
string
-
-
yes
Credit Card verification number, 3-4 digits
AddressLine1
string
yes
yes
yes
Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2
string
no
no
no
Card address line 2 (maximum 30 characters)
AddressPostalCode
string
yes
yes
yes
Card address postal code
AddressCountry
string
yes
yes
yes
Card address country
AddressCity
string
yes
yes
yes
Card address city (maximum 32 characters)
AddressState
string
yes
yes
yes
Card address state
Response
payment_instrument_id
guid
Payment Instrument id
Use this endpoint to edit a payment instrument's information for an existing user. Include the user id as a path parameter in the URL and the new values in the body payload.
Method: PATCH
Endpoint: {{env}}/api/user/UpdatePaymentInstrumentInformation/{user_id}/{payment_instrument_id}
This endpoint is only available to US customers.
Request parameters
AccountType
string
yes
-
-
Account Type can be either Checking or Savings
RoutingNumber
string
yes
-
-
Routing Number, 9 digits
AccountNumber
string
yes
-
-
Account Number
ExternallyVerified
boolean
no
-
-
Set to true to skip bank account verification
Number
string
-
yes
yes
Card number, 16 digits
ExpireMonth
string
-
yes
yes
Card expiry month, 2 digits
ExpireYear
string
-
yes
yes
Card expiry year, 4 digits
Cvv
string
-
-
yes
Credit Card verification number, 3-4 digits
AddressLine1
string
yes
yes
yes
Card address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2
string
no
no
no
Card address line 2 (maximum 30 characters)
AddressPostalCode
string
yes
yes
yes
Card address postal code
AddressCountry
string
yes
yes
yes
Card address country
AddressCity
string
yes
yes
yes
Card address city (maximum 32 characters)
AddressState
string
yes
yes
yes
Card address state
Response
user_id
guid
User id
payment_instrument_id
guid
Payment Instrument 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.
Method: PATCH
Endpoint: {{env}}/api/user/UpdateBankAccountInformation/{user_id}
Input parameters
InstitutionNumber
string
yes
Institution Number, 3 digits
TransitNumber
string
yes
Transit Number, 5 digits
AccountNumber
string
yes
Account Number
Response
id
guid
User id
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}
Note that this endpoint is restricted to Canadian customers.
Input parameters
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
id
guid
User id
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}
Note that this endpoint is restricted to Canadian customers.
Input parameters
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
id
guid
User id
Use this endpoint to update the billing address information attached to a user.
Method: PUT
Endpoint: {{env}}/api/User/UpdatePrepaidCardInformation/{{userId}}
UserId
Guid
Yes
User Id
AddressLine1
String
Yes
Address
AddressLine2
String
No
Second Address
AddressPostalCode
String
Yes
Postal code
AddressCountry
String
No
Country Code (CA is only available for Baas)
AddressCity
String
Yes
City
AddressState
String
Yes
Province
CardNumber
String
Card number
ExpireMonth
String
Month card expires on
ExpireYear
String
Year card expires on
CustomerId
Guid
Customers Id
PrepaidCardUser
Id
Guid
Id of prepaid card
UserId
Guid
UserId of prepaid card
FirstName
String
First name
LastName
String
Last name
CardApplicationStatus
String
Card application status
OnboardStatus
String
Card onboarding status
CardNumber
String
Card number
CardStatus
String
Card status
CardReferenceId
String
Card reference id
CardProgramId
String
Card program id
AvailableBalance
Number
Current balance of the card
CustomerId
Guid
Customer Id
OnboardId
Guid
Onboarding Id
String
Email on card
CardApplicationStatus
String
Status of card application
CardStatus
String
Card status
CardRegistrationStatus
String
Status of card registration
AvailableBalance
Number
Current balance of the card
LedgerBalance
Number
Ledger balance of the card
CardHolderId
String
Card Holder Id
CardReferenceId
String
Card Reference Id
CardRegistered
Boolean
Flag for if the card is registered
AddressLine1
String
Address
AddressLine2
String
Second Address
AddressPostalCode
String
Postal code
AddressCountry
String
Country Code
AddressCity
String
City
AddressState
String
Province
IsZumCardActive
Boolean
Flag for if the zum card for this user is active
Use this endpoint to approve a user’s prepaid card and add a new card to the user.
Method: POST
Endpoint: {{env}}/api/user/approveZumCard
UserId
Guid
Yes
User Id
CardProgramId
String
Yes
Customer Card Program Id
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}
Input parameters
AddressLine1
string
no
yes
yes
shipping address line 1 (maximum 60 characters)
AddressLine2
string
no
yes
no
shipping address line 2 (maximum 60 characters)
AddressPostalCode
string
no
yes
yes
shipping address postal code
AddressCountry
string
no
yes
no
shipping address country (Canada)
AddressCity
string
no
yes
yes
shipping address city (maximum 32 characters)
AddressState
string
no
yes
yes
shipping address state/province
sameAsBilling
boolean
no
no
no
shipping address is as the Billing Address
Response
id
guid
User id
sameAsBilling
boolean
Use the billing address as shipping address if true
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
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
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
PrepaidCardUser
Id
Guid
Id of prepaid card
UserId
Guid
UserId of prepaid card
FirstName
String
First name
LastName
String
Last name
CardApplicationStatus
String
Card application status
OnboardStatus
String
Card onboarding status
CardNumber
String
Card number
CardStatus
String
Card status
CardReferenceId
String
Card reference id
CardProgramId
String
Card program id
AvailableBalance
String
Current balance of the card
CustomerId
Guid
Customer Id
OnboardId
Guid
Onboarding Id
String
Email on card
HasPrepaidCardUser
Boolean
Flag for if user has prepaid card
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
ZumCard
Boolean
Indicate if this user can do Zum Card transactions
AggregationStatus
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
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}
Use this endpoint to search for specific users. Results are returned with pagination, so to retrieve all users, you must make successive calls to this endpoint while incrementing the PageNumber parameter.
Method: POST
Endpoint: {{env}}/api/user/filter
Operators
Use these operators to filter by UserName, ClientUserId, CustomerName and CustomerId
contains
Filter records that contains the value
excludes
Filter records that does not contains the value
exactly matches
Filter records that exactly matches the value
Date operators
Use these operators to filter by CreatedAt
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
GenericSearch
string
no
Filter users by user name and user email
UserName
string
no
First and/or Last name
UserNameOperator
string
no
Operator to filter with UserName property
CreatedAt
datetime
no
Create date
CreatedAtFrom
datetime
no
Start date (This field is only used when the operator is IsBetween)
CreatedAtTo
datetime
no
End date (This field is only used when the operator is IsBetween)
CreatedAtOperator
string
no
Operator to filter with CreatedAt properties
string
no
User email
ClientUserId
string
no
External Client User Identifier
ClientUserIdOperator
string
no
Operator to filter with ClinetUserId property
CustomerName
string
no
Customer name (for partners only)
CustomerNameOperator
string
no
Operator to filter with CustomerName property
CustomerId
string
no
Customer Id (for partners only)
CustomerIdOperator
string
no
Operator to filter with CustomerId property
TransactionMethodAvailable
Integer
no
Transaction method available for the user
Pagination
no
PageNumber
number
no
The respective page, starting at 1
Response
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
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”
PrepaidCardUser
Id
Guid
Id of prepaid card
UserId
Guid
UserId of prepaid card
FirstName
String
First name
LastName
String
Last name
CardApplicationStatus
String
Card application status
OnboardStatus
String
Card onboarding status
CardNumber
String
Card number
CardStatus
String
Card status
CardReferenceId
String
Card reference id
CardProgramId
String
Card program id
AvailableBalance
String
Current balance of the card
CustomerId
Guid
Customer Id
OnboardId
Guid
Onboarding Id
String
Email on card
HasPrepaidCardUser
String
Indicate if this user can do Zum Card transactions
TransactionMethod
#
Name
Currency
0
Eft
CAD
1
Interac
CAD
2
VisaDirect
CAD
3
CreditCard
CAD
4
Ach
USD
5
DebitCard
USD
6
CreditCardUs
USD
7
MoneyTransfer
USD
8
ZumTransfer
USD
9
ZumCard
CAD
10
SameDayAch
USD
11
RtpFedNow
USD
You can use this endpoint to check if a US bank account is eligible for payments using RTP or FedNow rails.
Method: POST
Endpoint: {{env}}/api/user/checkuseligibility
For credit card payment instruments, it is possible to use cards that were issued outside the US. To consult the list of acceptable countries, .
Billing address state/province. .
Shipping address state/province. .
State where ID was issued. .
Card address country. .
For credit card payment instruments, it is possible to use cards that were issued outside the US. To consult the list of acceptable countries, .
NOTE This endpoint returns limited user details. To retrieve full information for a specific user, use the endpoint.