# 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](https://docs.zumrails.com/tokenization-1/zum-connect). {% embed url="" %} ## Create a new user ### API 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 to enable this feature. For Visa Direct Push transactions, it is possible to add a user through API providing only the card number, please contact Zūm support to enable this feature. [Request example](#request-visa-direct-push-canada). `Method: POST` `Endpoint: {{env}}/api/user` {% tabs fullWidth="false" %} {% tab title="Request (Canada)" %} ```json { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "ClientUserId": "*", "BankAccountInformation": { "InstitutionNumber": "111", "TransitNumber": "12345", "AccountNumber": "1234567" }, "CreditCardInformation": { "Number": "1234123412341234", "EncryptedNumber": "", "ExpireMonth": "01", "ExpireYear": "2027", "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" } ] } ``` {% endtab %} {% tab title="Request (Visa Direct Push - Canada) " %} ```json { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CreditCardInformation": { "Number": "1234123412341234", "EncryptedNumber": "" } } ``` {% endtab %} {% tab title="Response (Canada)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19", "FirstName": "John", "LastName": "Doe", "CompanyName": null } } ``` {% endtab %} {% tab title="Request (ACH -US)" %} ```json { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "ClientUserId": "*", "IdType": "DL", "IdNumber": "12-3456789", "IdState": "CA", "PaymentInstruments": [ { "RoutingNumber": "122000661", "AccountNumber": "1234567890", "AccountType": "Checking", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "BankAccount" } ] } ``` {% endtab %} {% tab title="Request (Debit Card -US)" %} ```json { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "PaymentInstruments": [ { "Number": "4000230000048889", "EncryptedNumber": "", "ExpireMonth": "08", "ExpireYear": "2027", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "DebitCard" } ] } ``` {% endtab %} {% tab title="Request (Credit Card -US)" %} ```json { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "PaymentInstruments": [ { "Number": "4000230000048889", "EncryptedNumber": "", "ExpireMonth": "08", "ExpireYear": "2027", "Cvv": "123", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "CreditCard" } ] } ``` {% endtab %} {% tab title=" Response (US)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19", "FirstName": "John", "LastName": "Doe", "CompanyName": null, "IsActive": true, "PaymentInstruments": [ { "Id": "92142401-d17e-4906-91e8-389ba0d87e75", "RoutingNumber": "021000021", "AccountNumber": "1001001235", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethodType": "BankAccount" } ] } } ``` {% endtab %} {% endtabs %} **Input parameters** {% tabs %} {% tab title="Canada" %}
ParameterTypeEFT (Mandatory)Interac (Mandatory)Credit Card (Mandatory)Visa Direct (Mandatory)Description
FirstNamestringyesyesyesyesUser's first name, in case User is an individual. Character limit is 120.
LastNamestringyesyesyesyesUser's last name, in case User is an individual. Character limit is 120.
CompanyNamestringyesyesyesyesCompany name, in case User is a company. Character limit is 120.
EmailstringyesyesyesyesUser e-mail
PhoneNumberstringnonononoPhone number (maximum 10 characters, no special characters accepted)
ClientUserIdstringnonononoExternal Client User Identifier
BankAccountInformationyes
InstitutionNumberstringyesnononoInstitution Number, 3 digits
TransitNumberstringyesnononoTransit Number, 5 digits
AccountNumberstringyesnononoAccount Number
CreditCardInformationyesyes
NumberstringnonoyesyesLeave empty if EncryptedNumber is included
EncryptedNumberstringnonononoEncrypted card number. Refer to Encryption section for more information
ExpireMonthnumbernonoyesyesCard expiry month, 2 digits.
ExpireYearnumbernonoyesyesCard expiry year, 4 digits
CVVstringnonoyesyesSecurity code, 3 or 4 digits
AddressLine1stringnonononoBilling address line 1 (maximum 60 characters)
AddressLine2stringnonononoBilling address line 2 (maximum 60 characters)
AddressPostalCodestringnonononoBilling address postal code
AddressCountrystringnonononoBilling address country
AddressCitystringnonononoBilling address city (maximum 32 characters)
AddressStatestringnonononoBilling address state/province
{% endtab %} {% tab title="US" %}
ParameterTypeACH (Mandatory)Debit Card (Mandatory)Credit Card (Mandatory)Description
FirstNamestringconditionalconditionalconditionalUser's first name, in case User is an individual. Character limit is 120.
LastNamestringconditionalconditionalconditionalUser's last name, in case User is an individual. Character limit is 120.
CompanyNamestringconditionalconditionalconditionalCompany name, in case User is a company. Character limit is 120.
EmailstringyesyesnoUser's e-mail
PhoneNumberstringyesnonoPhone number (maximum 10 characters, no special characters accepted)
ClientUserIdstringnononoExternal identifier for the user
BusinessTaxIdstringconditional--Business tax ID, required in case User is a company
IdTypestringconditional--ID type, can be DL or SSN
IdNumberstringconditional--ID number
IdStatestringconditional--State where ID was issued
PaymentInstrumentsyesyesyesList of payment instruments
PaymentMethodstringyesyesyesPayment method must be BankAccount, DebitCard or CreditCard
RoutingNumberstringyes--Routing number, 9 digits, required when payment method is BankAccount
AccountNumberstringyes--Account number, 5-17 digits, required when payment method is BankAccount
AccountTypestringyes--Account type, can be either Checking or Savings, required when payment method is BankAccount
ExternallyVerifiedbooleanno--Set to true to skip bank account verification
Numberstring-yesyesCard number, 16 digits. Leave empty if EncryptedNumber is included
EncryptedNumberstring-nonoEncrypted card number. Refer to Encryption section for more information
ExpireMonthstring-yesyesCard expiry month, 2 digits
ExpireYearstring-yesyesCard expiry year, 4 digits
Cvvstring--yesCard verification number, 3-4 digits, required fir CreditCard
AddressLine1string-yesyesCard address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2string-nonoCard address line 2 (maximum 30 characters)
AddressPostalCodestring-yesyesCard address postal code
AddressCountrystring-yesyesCard address country. See country-and-region-codes for more information.
AddressCitystring-yesyesCard address city (maximum 32 characters)
AddressStatestring-yesyesCard address state
{% endtab %} {% endtabs %} {% hint style="danger" %} **CAUTION** 1. When creating a user, provide `FirstName` and `LastName` if the user is an individual, or provide `CompanyName` if the user is a business. 2. CVV and Expire Month/Year are mandatory for all transaction types with the Visa Direct/Credit Card payment methods. 3. When an SSN is provided for a User, then `IdNumber` should be 9 digits. 4. To skip bank account verification, speak to your account executive or reach out to support. 5. The card number can be provided encrypted to improve the security. When EncryptedNumber is included, the Number field must be not informed. Refer to [Encryption](https://docs.zumrails.com/api-reference/encryption) section for more information. 6. When adding a User with only the card number, it will be enabled only for Visa Direct Push transactions. 7. The card expiration date (ExpireMonth / ExpireYear) must not exceed 5 years from the current date. {% endhint %} **Response (Canada)**
ParameterTypeDescription
IdguidUser id
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name, in case it's a company
Emailstringemail used to create user
IsActiveboolIndicates if user is active
{% hint style="info" %} **TIP (US)** In sandbox, to add a **credit card** for a User, use any of the following card numbers. **Mastercard** * 5102610000000077 * 5102630000000026 **Visa** * 4000130000000106 * 4000240000044432 * 4000230000044433 * 4000230000048889 * 4000240000044481 * 4000230000055587 * 4000240000044663 **Amex** * 379605170000771 **Discover** * 6011208701111117 **Diners** * 36797342194957 **JBC** * 3587306912123367 {% endhint %} {% hint style="info" %} **TIP (US)** In sandbox, to add a **debit card** for a User, use any of the following card numbers. **Mastercard** * 5204730820000029 {% endhint %} {% hint style="info" %} **INFO (US)** It is possible to add credit cards or bank accounts from a country other than the US. To consult the list of acceptable countries, [click here](https://docs.zumrails.com/api-reference/country-and-region-codes). {% endhint %} ### 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` {% tabs %} {% tab title="User (Canada)" %}
NameTypeDescription
FirstName*stringFirst name, if the User is an individual.
LastName*stringLast name, if User is an individual. Maximum 100 characters.
CompanyName*stringCompany name, if User is a company. Maximum 100 characters.
Email*stringEmail address
PhoneNumberstringPhone number. Maximum 10 characters (no special characters).
ClientUserIdstringExternal identifier for the User.
BankAccountInformation
InstitutionNumberstringInstitution Number, 3 digits
TransitNumberstringTransit Number, 5 digits
AccountNumberstringAccount Number
CreditCardInformation
NumberstringCard number
ExpireMonthstringCard expiry month, 2 digits.
ExpireYearstringCard expiry year, 4 digits.
CVVstringSecurity code, 3 or 4 digits.
AddressLine1stringBilling address line 1. Maximum 60 characters.
AddressLine2stringBilling address line 2. Maximum 60 characters.
AddressCitystringBilling address city. Maximum 32 characters.
AddressStatestringBilling address state/province. See region codes.
AddressPostalCodestringBilling address postal code
AddressCountrystringBilling address country
Addresses
AddressTypestring??
AddressLine1stringShipping address line 1. Maximum 60 characters.
AddressLine2stringShipping address line 2. Maximum 60 characters.
AddressCitystringShipping address city. Maximum 32 characters.
AddressStatestringShipping address state/province. See region codes.
AddressPostalCodestringShipping address postal code
AddressCountrystringShipping address country
{% endtab %} {% tab title="User (US)" %}
NameTypeDescription
FirstName*stringFirst name, if the User is an individual. Maximum 100 characters.
LastName*stringLast name, if User is an individual. Maximum 100 characters.
CompanyName*stringCompany name, if User is a company. Maximum 100 characters.
Email*stringEmail address
PhoneNumberstringPhone number. Maximum 10 characters (no special characters).
ClientUserIdstringExternal identifier for the User.
BusinessTaxIdstringBusiness tax ID, required in case User is a company.
IdTypestringID type, can be DL or SSN
IdNumberstringID number
IdStatestringState where ID was issued. See region codes.
PaymentInstruments
PaymentMethodstringPayment method must be BankAccount, DebitCard or CreditCard
RoutingNumberstringRouting number, 9 digits, required when payment method is BankAccount
AccountNumberstringAccount number, 5-17 digits, required when payment method is BankAccount
AccountTypestringAccount type, can be either Checking or Savings, required when payment method is BankAccount
NumberstringCard number, 16 digits
ExpireMonthstringCard expiry month, 2 digits
ExpireYearstringCard expiry year, 4 digits
CvvstringCard verification number, 3-4 digits, required for CreditCard
AddressLine1stringCard address line 1, 3-30 characters.
AddressLine2stringCard address line 2, maximum 30 characters.
AddressCitystringCard address city, maximum 32 characters.
AddressStatestringCard address state
AddressPostalCodestringCard address postal code
AddressCountrystringCard address country. See country & region codes.
{% endtab %} {% endtabs %} {% tabs %} {% tab title="Request (Canada)" %} ```json { "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" } ] } ``` {% endtab %} {% tab title="Response (Canada)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19", "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null } } ``` {% endtab %} {% tab title="Request (US)" %} ```json //Request - ACH { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "ClientUserId": "*", "IdType": "DL", "IdNumber": "12-3456789", "IdState": "CA", "PaymentInstruments": [ { "RoutingNumber": "122000661", "AccountNumber": "1234567890", "AccountType": "Checking", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "BankAccount" } ] } //Request - Debit Card { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "PaymentInstruments": [ { "Number": "4000230000048889", "ExpireMonth": "08", "ExpireYear": "2026", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "DebitCard" } ] } //Request - Credit Card { "FirstName": "John", "LastName": "Doe", "Email": "johndoe@zumrails.com", "CompanyName": null, "PhoneNumber": "5141231234", "PaymentInstruments": [ { "Number": "4000230000048889", "ExpireMonth": "08", "ExpireYear": "2026", "Cvv": "123", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "CreditCard" } ] } ``` {% endtab %} {% tab title="Response (US)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "Id": "0bc9894d-b37b-4ae0-af70-f691024aca19", "FirstName": "John", "LastName": "Doe", "CompanyName": null, "IsActive": true, "PaymentInstruments": [ { "Id": "92142401-d17e-4906-91e8-389ba0d87e75", "RoutingNumber": "021000021", "AccountNumber": "1001001235", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethodType": "BankAccount" } ] } } ``` {% endtab %} {% endtabs %} **Input parameters**
ParameterTypeMandatoryDescription
FirstNamestringyesUser first name
LastNamestringyesUser last name
EmailstringyesUser e-mail
AuthCodestringyesKey used to get an access_code
{% hint style="info" %} **INFO** It is possible to add credit cards or bank accounts from a country other than the US. To consult the list of acceptable countries, [click here](https://docs.zumrails.com/docs/us/api-specification/countries-and-administrative-units). {% endhint %} ## Update a 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}` {% tabs %} {% tab title="Payload (Canada)" %} ```json { "FirstName": "John", "LastName": "Doe", "CompanyName": null, "DateOfBirth": "2000-01-25", "Email": "johndoe@zumrails.com", "PhoneNumber": "5141231234", "ClientUserId": "*" } ``` {% endtab %} {% tab title="Response (Canada)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% tab title="Payload (US)" %} ```json { "FirstName": "John", "LastName": "Doe", "CompanyName": null, "Email": "johndoe@zumrails.com", "PhoneNumber": "5141231234", "ClientUserId": "*", "IdType": "DL", "IdNumber": "12-3456789", "IdState": "CA" } ``` {% endtab %} {% tab title="Response (US)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **Input parameters** {% tabs %} {% tab title="Canada" %}
ParameterTypeEFT (Mandatory)Interac (Mandatory)Credit Card (Mandatory)Prepaid Card Card (Mandatory)Visa Direct (Mandatory)Description
FirstNamestringyesyesyesyesyesUser first name. Character limit is 100.
LastNamestringyesyesyesyesyesUser last name. Character limit is 100.
CompanyNamestringnoyesyesnoyesCompany name, in case it's a company. Character limit is 100.
EmailstringyesyesyesyesyesUser e-mail
LanguagestringnononononoLanguage preference (en, fr)
PhoneNumberstringnononoonnoPhone number (maximum 10 characters, no special characters accepted)
ClientUserIdstringnononononoExternal Client User Identifier
DateOfBirthdatenononoyesnoDate of birth
{% endtab %} {% tab title="US" %} | Parameter | Type | ACH (Mandatory) | Debit Card (Mandatory) | Credit Card (Mandatory) | Description | | ------------- | ------ | --------------- | ---------------------- | ----------------------- | -------------------------------------------------------------------- | | FirstName | string | yes | yes | yes | User first name | | LastName | string | yes | yes | yes | User last name | | CompanyName | string | no | no | no | Company name, in case it's a company | | Email | string | yes | yes | no | User e-mail | | PhoneNumber | string | yes | no | no | Phone number (maximum 10 characters, no special characters accepted) | | ClientUserId | string | no | no | no | External Client User Identifier | | BusinessTaxId | string | yes | - | - | Business tax ID, required in case User is a company | | IdType | string | yes | - | - | ID type, can be `DL` or `SSN` | | IdNumber | string | yes | - | - | ID number | | IdState | string | yes | - | - | tate where ID was issued | | {% endtab %} | | | | | | | {% endtabs %} | | | | | | **Response** | Parameter | Type | Description | | --------- | ---- | ----------- | | id | guid | User id | ## Add payment instrument 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}` {% hint style="warning" %} This endpoint is only available to US customers. {% endhint %} {% tabs %} {% tab title="Request (ACH)" %} ```json { "AccountType": "Checking", "RoutingNumber": "123456789", "AccountNumber": "1234567890", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY" } ``` {% endtab %} {% tab title="Request (Debit Card)" %} ```json { "Number": "4000230000048889", "ExpireMonth": "08", "ExpireYear": "2026", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "DebitCard" } ``` {% endtab %} {% tab title="Request (Credit Card)" %} ```json { "Number": "4000230000048889", "ExpireMonth": "08", "ExpireYear": "2026", "Cvv": "1234", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "CreditCard" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **Request parameters**
ParameterTypeACH (Mandatory)Debit Card (Mandatory)Credit Card (Mandatory)Description
AccountTypestringyes--Account Type can be either Checking or Savings
RoutingNumberstringyes--Routing Number, 9 digits
AccountNumberstringyes--Account Number
ExternallyVerifiedbooleanno--Set to true to skip bank account verification
Numberstring-yesyesCard number, 16 digits
ExpireMonthstring-yesyesCard expiry month, 2 digits
ExpireYearstring-yesyesCard expiry year, 4 digits
Cvvstring--yesCredit Card verification number, 3-4 digits
AddressLine1stringyesyesyesCard address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2stringnononoCard address line 2 (maximum 30 characters)
AddressPostalCodestringyesyesyesCard address postal code
AddressCountrystringyesyesyesCard address country
AddressCitystringyesyesyesCard address city (maximum 32 characters)
AddressStatestringyesyesyesCard address state
**Response**
ParameterTypeDescription
payment_instrument_idguidPayment Instrument id
## Update payment instrument 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}` {% hint style="warning" %} This endpoint is only available to US customers. {% endhint %} {% tabs %} {% tab title="Request (ACH)" %} ```json { "AccountType": "Checking", "RoutingNumber": "123456789", "AccountNumber": "1234567890", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY" } ``` {% endtab %} {% tab title="Request (Debit Card)" %} ```json { "Number": "4000230000048889", "ExpireMonth": "08", "ExpireYear": "2026", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "DebitCard" } ``` {% endtab %} {% tab title="Request (Credit Card)" %} ```json { "Number": "4000230000048889", "ExpireMonth": "08", "ExpireYear": "2026", "Cvv": "1234", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "11215", "AddressCountry": "USA", "AddressCity": "Brooklyn", "AddressState": "NY", "PaymentMethod": "CreditCard" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **Request parameters**
ParameterTypeACH (Mandatory)Debit Card (Mandatory)Credit Card (Mandatory)Description
AccountTypestringyes--Account Type can be either Checking or Savings
RoutingNumberstringyes--Routing Number, 9 digits
AccountNumberstringyes--Account Number
ExternallyVerifiedbooleanno--Set to true to skip bank account verification
Numberstring-yesyesCard number, 16 digits
ExpireMonthstring-yesyesCard expiry month, 2 digits
ExpireYearstring-yesyesCard expiry year, 4 digits
Cvvstring--yesCredit Card verification number, 3-4 digits
AddressLine1stringyesyesyesCard address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2stringnononoCard address line 2 (maximum 30 characters)
AddressPostalCodestringyesyesyesCard address postal code
AddressCountrystringyesyesyesCard address country
AddressCitystringyesyesyesCard address city (maximum 32 characters)
AddressStatestringyesyesyesCard address state
**Response**
ParameterTypeDescription
user_idguidUser id
payment_instrument_idguidPayment Instrument 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}` {% tabs %} {% tab title="Payload" %} ```json { "InstitutionNumber": "111", "TransitNumber": "12345", "AccountNumber": "1234567" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **Input parameters**
ParameterTypeEFT (Mandatory)Description
InstitutionNumberstringyesInstitution Number, 3 digits
TransitNumberstringyesTransit Number, 5 digits
AccountNumberstringyesAccount Number
**Response** | Parameter | Type | Description | | --------- | ---- | ----------- | | 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}` {% hint style="warning" %} Note that this endpoint is restricted to Canadian customers. {% endhint %} {% tabs %} {% tab title="Request " %} ```json { "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "Canada", "AddressCity": "Toronto", "AddressState": "ON" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **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 | ### Credit / debit card details 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}` {% hint style="warning" %} Note that this endpoint is restricted to Canadian customers. {% endhint %} {% tabs %} {% tab title="Payload" %} ```json { "Number": "4242424242424242", "ExpireMonth": "01", "ExpireYear": "2025", "CVV": "111", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "Canada", "AddressCity": "Toronto", "AddressState": "ON" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **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 prepaid card information Use this endpoint to update the billing address information attached to a user. `Method: PUT` `Endpoint: {{env}}/api/User/UpdatePrepaidCardInformation/{{userId}}` {% tabs %} {% tab title="Payload" %} ```json { "AddressLine1": "123 Main St", "AddressLine2": "Apt 4B", "AddressPostalCode": "N1G 5H6", "AddressCountry": "CA", "AddressCity": "Anytown Hills", "AddressState": "ON" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "PUT Request successful.", "isError": false, "result": { "Id": "d1751e46-042c-492b-bc2a-cfa0aaea1016", "User": { "Id": "88a24aaa-214c-40f3-beeb-7666a91f9248", "UserId": "a1f26783-8e7b-4aeb-adc4-60f47c5a9f4c", "FirstName": "Sebastian", "LastName": "Gadzinski", "DateOfBirth": "2008-03-05", "Occupation": "ZUM_DEV", "ShippingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "BillingAddress": { "AddressLine1": "123 Main Stre", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" } }, "CardBrand": "Unknown", "CardApplicationStatus": "Approved", "OnboardStatus": "InProgress", "CardNumber": "************8704", "ExpireMonth": "03", "ExpireYear": "29", "CardStatus": "IssuedInactive", "CardReferenceId": "599000153544", "CardRegistrationStatus": "NotRegistered", "CardProgramId": "Zumrail_ProdT", "CardHolderId": "599000000000001535", "AvailableBalance": 10.0, "LedgerBalance": 10.0, "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f", "CreatedAt": "2026-03-17T00:20:15.979253Z", "CardActivatedAt": "2026-03-17T00:21:10.897278Z", "IsCardActive": true } } ``` {% endtab %} {% endtabs %} #### **Input parameters**
ParameterTypeRequiredDescription
UserIdGuidYesUser Id
AddressLine1StringYesAddress
AddressLine2StringNoSecond Address
AddressPostalCodeStringYesPostal code
AddressCountryStringNoCountry Code (CA is only available for Baas)
AddressCityStringYesCity
AddressStateStringYesProvince
#### Response | Category | Type | Description | | ---------------------- | ----------- | ------------------------------------------------ | | 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 | | Email | 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 | ## Approve card 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` #### **Request Parameters:** | Parameter | Type | Mandatory | Description | | ------------- | ------ | --------- | ------------------------ | | UserId | Guid | Yes | User Id | | CardProgramId | String | Yes | Customer Card Program Id | ## Update shipping address 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}` {% hint style="info" %} The `sameAsBilling` boolean, when set to true, populates the shipping address with the billing address details {% endhint %} {% tabs %} {% tab title="Payload" %} ```json { "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "Canada", "AddressCity": "Toronto", "AddressState": "ON" } ``` {% endtab %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": "0bc9894d-....-f691024aca19" } ``` {% endtab %} {% endtabs %} **Input parameters** | Parameter | Type | Credit Card (Mandatory) | Visa Direct (Mandatory) | Zum Card (Mandatory) | Description | | ----------------- | ------- | ----------------------- | ----------------------- | -------------------- | ----------------------------------------------- | | 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** | 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}` {% tabs %} {% tab title="Response (Canada)" %} ```json { "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", "Language": "en", "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", "VisaDirectCardType": "Debit", "CardMetadata": { "CvvResult": "MATCH", "AvsResult": "FULL_MATCH", "CardType": "Debit", "CardBrand": "VISA", "DebitCardPull": false, "DebitCardPush": false, "FinancialInstitution": "TD", "Country": "CA", "Currency": "CAD", "VisaDirectAniResult": "VERIFIED_MATCH" }, }, "TransactionsMethodsAvailable": { "Eft": true, "VisaDirectPull": false, "VisaDirectPush": false, "Interac": true, "CreditCard": true } } } ``` {% endtab %} {% tab title="Response (Canada - PrepaidCardUser)" %} ```json { "statusCode": 200, "message": "GET Request successful.", "isError": false, "result": { "Id": "1763f576-b6b7-463c-b0b3-d009c0038be8", "CreatedAt": "2025-05-25T19:54:29.500759Z", "AccountType": "Personal", "Name": "New User", "FirstName": "New", "LastName": "User", "PhoneNumber": "2222222222", "Currency": "CAD", "ShippingSameAsBilling": false, "Email": "user@example.com", "DateOfBirth": "01-01-1990", "Occupation": "Business and Financial Operations (Accounting, Budgeting, Banking, Fundraising, Insurance Claims, etc.)", "Language": "en", "Customer": { "Id": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f", "CompanyName": "Zum Card Customer" }, "Addresses": [ { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON", "AddressType": "Billing" } ], "TransactionMethodsAvailable": { "Interac": false, "Eft": false, "VisaDirectPull": false, "VisaDirectPush": false, "CreditCard": false, "PrepaidCard": true }, "CardUser": { "Id": "88a24aaa-214c-40f3-beeb-7666a91f9248", "UserId": "a1f26783-8e7b-4aeb-adc4-60f47c5a9f4c", "FirstName": "Sebastian", "LastName": "Gadzinski", "Gender": "Male", "Email": "sebastian.gadzinski+hpeofif@zumrails.com", "PhoneNumber": "2222222222", "Occupation": "Developer", "DateOfBirth": "2008-03-05", "Language": "En", "Comment": "APPROVED.", "UserPrepaidCard": { "Id": "d1751e46-042c-492b-bc2a-cfa0aaea1016", "CardBrand": "Unknown", "CardApplicationStatus": "Approved", "OnboardStatus": "Approved", "CardNumber": "************8704", "CardStatus": "IssuedInactive", "CardReferenceId": "599000153544", "CardRegistrationStatus": "NotRegistered", "CardProgramId": "Zumrail_ProdT", "CardholderId": "599000000000001535", "AvailableBalance": 10.0, "LedgerBalance": 10.0, "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f", "OnboardId": "bd98b10f-bd55-4f03-8f29-e8a42cb5c33d", "CreatedAt": "2026-03-17T00:20:15.979253Z", "CardActivatedAt": "2026-03-17T00:21:10.897278Z" }, "ShippingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "BillingAddress": { "AddressLine1": "123 Main Stre", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "Notifications": { "AllowTransactionEmailNotification": true, "AllowTransactionSmsNotification": true, "AllowProfileUpdateEmailNotification": true, "AllowProfileUpdateSmsNotification": true, "AllowLoginSessionEmailNotification": true, "AllowLoginSessionSmsNotification": true } }, "HasPrepaidCardUser": true } } ``` {% endtab %} {% tab title="Response (US)" %} ```json { "statusCode": 200, "message": "GET Request successful.", "isError": false, "result": { "Id": "0bc9894d-....-f691024aca19", "CreatedAt": "2022-01-20T17:16:05.166865Z", "AccountType": "Personal", "Name": "John Doe", "FirstName": "John", "LastName": "Doe", "PhoneNumber": "", "Currency": "USD", "AggregationRequestId": "15bb883e-e0bb-4a58-9a2c-f8ff234033b4", "Customer":{ "AchProvider": "Fiserv", "CompanyName": "Main Company Inc", "Id": "12345678-1234-1234-1234-123456789123" }, "Email": "john.doe@zumrails.com", "IdType": "SSN", "IdNumber": "*****1234", "PaymentInstruments": [ { "Id": "92142401-d17e-4906-91e8-389ba0d87e75", "RoutingNumber": "021000021", "AccountNumber": "1001001235", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressCity": "Brooklyn", "AddressState": "NY", "AddressPostalCode": "11215", "AddressCountry": "USA", "AggregationBalance": 500000, "AggregationRequestId": "011e4acb-0b9b-4d30-9dfc-f6793fa97eaf", "AggregationStatus": "Connected", "AllowRefreshBalance": false, "PaymentMethod": "BankAccount", "BankAccountInformation": { "Id": "caeb3477-03ba-4874-a22e-a8e3b9ffa472", "Institution": "Zūm Rails Testing Bank", "AccountNumber": "4921710685", "AccountType": "Personal", "BankAccountType": "Checking", "RoutingNumber": "021000021", "Name": "John Doe", "FirstName": "John", "LastName": "Doe", "CreatedAt": "2024-07-30T22:48:15.211332Z", "AggregationStatus": "Connected", "LastTimeRefreshed": "2024-07-30T23:11:49.323567Z", "AggregationBalance": 500000, "Country": "USA", "AggregationRequestId": "011e4acb-0b9b-4d30-9dfc-f6793fa97eaf" } }, { "Id": "0f429457-fec9-4c33-b945-3dae92bb10d3", "Number": "************8889", "ExpireYear": "26", "ExpireMonth": "08", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressCity": "Brooklyn", "AddressState": "NY", "AddressPostalCode": "11215", "AddressCountry": "USA", "PaymentMethod": "DebitCard" }, { "Id": "1a2b3c4d-fec9-4c33-b945-3dae92bb10d3", "Number": "************8596", "ExpireYear": "2026", "ExpireMonth": "08", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressCity": "Brooklyn", "AddressState": "NY", "AddressPostalCode": "11215", "AddressCountry": "USA", "PaymentMethod": "CreditCard" } ], "TransactionMethodsAvailable": { "Ach": true, "DebitCard": true, "CreditCard": true, "CreditCard": true, "MoneyTransfer": false }, "ClientUserId": "" } } ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="Canada" %} | 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 | Phone number | | Email | string | E,mail address | | Language | string | Language preference | | 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 | | **CardMetadata** | | | | CvvResult | string | Result of the CVV check | | AvsResult | string | Result of the AVS check | | VisaDirectAniResult | string | Result of the Visa Account Name Inquiry (ANI). Only applicable to Visa Direct. | | CardType | string | Card type | | CardBrand | string | Card brand | | DebitCardPull | boolean | Boolean flag if the Visa debit card is eligible for pull. Only applicable to Visa Direct. | | DebitCardPush | boolean | Boolean flag if the Visa debit card is eligible for push. Only applicable to Visa Direct. | | FinancialInstitution | string | The institution of the card, valid for Visa Direct when not using aggregation | | Country | string | ISO 3166-1 alpha-2 country code of the country where the card is issued. | | Currency | string | Currency code for the card. | | **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 | | Email | String | Email on card | | Language | String | Language reference 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 | | {% endtab %} | | | {% tab title="US" %}
ParameterTypeDescription
IdguidUser id
CreatedAtdatetimeWhen the user was created
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
PhoneNumberstringLast name
EmailstringLast name
ClientUserIdstringExternal Client User Identifier
BusinessTaxIdstringBusiness tax ID, required in case User is a company
IdTypestringID type, can be DL or SSN
IdNumberstringLst 4 digits of the ID number
IdStatestringState where ID was issued
PaymentInstrumentIdstringPayment instrument id
AggregationRequestIdguidUnique identifier of the aggregation request
Customer
IdstringCustomer id
CompanyNamestringCustomer's company name
PaymentInstruments
idstringPayment instrument id
RoutingNumberstringRouting Number
AccountNumberstringAccount Number
PaymentMethodstringPayment Method
NumberstringMasked card number with the last 4 digits
ExpireMonthstringCard expiry month, 2 digits
ExpireYearstringCard expiry year, 2 digits for DebitCard and 4 digits for CreditCard
AddressLine1stringCard address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2stringCard address line 2 (maximum 30 characters)
AddressPostalCodestringCard address postal code
AddressCountrystringCard address country
AddressCitystringCard address city (maximum 32 characters)
AddressStatestringCard address state
AggregationBalancedecimalACH account current balance
AggregationRequestIdguidUnique identifier of the aggregation request
AggregationStatusstringIndicate if the account is Connected
AllowRefreshBalanceBooleanIndicate if the balance can be refreshed via Aggregation
BankAccountInformation
IdguidBankAccountInformation id
AccountNumberstringAccount Number
AccountTypestringIndicate the type of the account (Personal/Business)
AggregationBalancedecimalACH account current balance
AggregationRequestIdguidUnique identifier of the aggregation request
AggregationStatusstringIndicate if the account is Connected
BankAccountTypestringIndicate the type of the bank account
CountrystringBank account country
CreatedAtdatetimeWhen the bank account information was created
NamestringFull name
FirstNamestringFirst name
LastNamestringLast name
InstitutionstringInstitution name
RoutingNumberstringRouting Number
LastTimeRefresheddatetimeWhen the last refresh happened
AggregationFailedReasonstringIf failed, informs the failure reason
TransactionsMethodsAvailable
AchBooleanIndicate if this user can do ACH transactions
DebitCardBooleanIndicate if this user can do Debit card transactions
CreditCardBooleanIndicate if this user can do Credit card transactions
MoneyTransferBooleanIndicate if this user can do money transfer transactions
{% endtab %} {% endtabs %} **AggregationStatus**
StatusDescription
NotConnectedThe 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
**CvvResult** | Result | Description | | --------- | -------------------------------------------------------------------------- | | MATCH | Security code was matched. | | NO\_MATCH | Security code does not match. | | UNKNOWN | Security code verification was not performed. Issuer does not participate. | **AvsResult** | Result | Description | | ------------------------- | ------------------------------------------------------------------------------------------ | | FULL\_MATCH | Address and postal code match. | | ADDRESS\_ONLY\_MATCH | Address matches, but postal code does not or is unknown. | | POSTAL\_CODE\_ONLY\_MATCH | Postal code matches, but address does not or is unknown. | | NOT\_VERIFIED | Address not verified. AVS not supported, or system not available, or incompatible formats. | | NO\_MATCH | No match. Neither postal code nor address match. | **VisaDirectAniResult** | Result | Description | | ------------------------ | ------------------------- | | VERIFIED\_MATCH | Name matched. | | VERIFIED\_NO\_MATCH | Name does not match. | | VERIFIED\_PARTIAL\_MATCH | Name matched partially. | | NOT\_VERIFIED\_NO\_MATCH | Name match not performed. | | NOT\_SUPPORTED | Name match not supported. | {% hint style="info" %} **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. {% endhint %} {% hint style="info" %} **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. {% endhint %} ## 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}` {% hint style="info" %} **INFO** When deleting a user, all transactions already created for the respective user will remain active, but the user's data will be completely erased. {% endhint %} {% tabs %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "DELETE Request successful.", "isError": false, "result": "" } ``` {% endtab %} {% endtabs %} ## Search for a user 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. {% hint style="info" %} **NOTE**\ This endpoint returns limited user details. To retrieve full information for a specific user, use the [Get a specific user](#get-a-specific-user) endpoint. {% endhint %} `Method: POST` `Endpoint: {{env}}/api/user/filter` {% tabs %} {% tab title="Payload" %} ```json { "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 }, "TransactionMethodAvailable": 9 } ``` {% endtab %} {% tab title="Payload (Canada - CardUser)" %} ```json { "CardStatus": "Activated", "CardOnboardStatus": "Approved", "GenericSearch": null, "Pagination": { "PageNumber": 1, "ItemsPerPage": 10 } } ``` {% endtab %} {% tab title="Response (Canada)" %} ```json { "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": "", "ClientUserId": "*", "BankAccountInformation": { "LastTimeRefreshed": "2020-05-12T15:23:24.496157", "AggregationStatus": "NotConected", "AggregationBalance": 123.45, "NameMatch": { "Score": 90, "Result": "Matched" } } } ] } } ``` {% endtab %} {% tab title="Response (Canada - CardUser)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "CurrentPage": 1, "PageSize": 10, "TotalCount": 3, "Items": [ { "Id": "d50b3eae-7712-40a6-b9ed-f9b3b4383f68", "CreatedAt": "2026-03-24T18:56:04.240576Z", "AccountType": "Personal", "Name": "MarTwoFourOne MarTwoFourOne", "FirstName": "MarTwoFourOne", "LastName": "MarTwoFourOne", "PhoneNumber": "1234567890", "Currency": "CAD", "ShippingSameAsBilling": false, "Email": "dickson.li+martwofourone@zumrails.com", "DateOfBirth": "01-12-1990", "Occupation": "ZUM_DEV", "Customer": { "Id": "887ead16-0a27-4f41-8557-da6423a37a6f", "CompanyName": "Aug130947" }, "Addresses": [], "TransactionMethodsAvailable": { "Interac": true, "Eft": false, "VisaDirectPull": false, "VisaDirectPush": false, "CreditCard": false, "CreditCardUs": false, "Ach": false, "SameDayAch": false, "RtpFedNow": false, "DebitCard": false, "MoneyTransfer": false, "PrepaidCard": true }, "TransactionMethodsAvailableDescription": "Interac, Prepaid Card", "CardUser": { "Id": "a4981e14-4636-4a1b-9c58-e0f117cfd50e", "UserId": "d50b3eae-7712-40a6-b9ed-f9b3b4383f68", "FirstName": "MarTwoFourOne", "LastName": "MarTwoFourOne", "Gender": "Male", "Email": "dickson.li+martwofourone@zumrails.com", "PhoneNumber": "1234567890", "Occupation": "ZUM_DEV", "DateOfBirth": "1990-01-12", "Language": "En", "Comment": "Ai Prise simulation for APPROVED.", "UserPrepaidCard": { "Id": "c7e39f56-8b71-434a-8137-29a6b089de13", "CardBrand": "Unknown", "CardApplicationStatus": "Approved", "OnboardStatus": "Approved", "CardNumber": "************2244", "CardStatus": "Activated", "CardReferenceId": "599000158153", "CardRegistrationStatus": "NotRegistered", "CardProgramId": "Zumrail_ProdT", "CardholderId": "599000000000001569", "AvailableBalance": 0.0, "LedgerBalance": 0.0, "CustomerId": "887ead16-0a27-4f41-8557-da6423a37a6f", "OnboardId": "7a9ed2e1-4b6d-4759-96ed-61229eb237a3", "CreatedAt": "2026-03-24T22:21:32.908101Z", "CardActivatedAt": "2026-03-24T22:37:12.402398Z" }, "ShippingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "BillingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "Notifications": { "AllowTransactionEmailNotification": true, "AllowTransactionSmsNotification": true, "AllowProfileUpdateEmailNotification": true, "AllowProfileUpdateSmsNotification": true, "AllowLoginSessionEmailNotification": true, "AllowLoginSessionSmsNotification": true } }, "HasPrepaidCardUser": true, "Language": "En" }, { "Id": "e2667bc3-933b-441d-9322-cade8b4713c9", "CreatedAt": "2026-03-19T19:04:29.054787Z", "AccountType": "Personal", "Name": "MarNinteenOne MarNinteenOne", "FirstName": "MarNinteenOne", "LastName": "MarNinteenOne", "PhoneNumber": "1234567890", "Currency": "CAD", "ShippingSameAsBilling": false, "Email": "dickson.li+marninteenone@zumrails.com", "DateOfBirth": "01-01-1990", "Occupation": "ZUM_DEV", "Customer": { "Id": "887ead16-0a27-4f41-8557-da6423a37a6f", "CompanyName": "Aug130947" }, "Addresses": [], "TransactionMethodsAvailable": { "Interac": true, "Eft": false, "VisaDirectPull": false, "VisaDirectPush": false, "CreditCard": false, "CreditCardUs": false, "Ach": false, "SameDayAch": false, "RtpFedNow": false, "DebitCard": false, "MoneyTransfer": false, "PrepaidCard": true }, "TransactionMethodsAvailableDescription": "Interac, Prepaid Card", "CardUser": { "Id": "52272c3b-19bc-4686-a855-87545c493ff4", "UserId": "e2667bc3-933b-441d-9322-cade8b4713c9", "FirstName": "MarNinteenOne", "LastName": "MarNinteenOne", "Gender": "Male", "Email": "dickson.li+marninteenone@zumrails.com", "PhoneNumber": "1234567890", "Occupation": "ZUM_DEV", "DateOfBirth": "1990-01-01", "Language": "En", "Comment": "Ai Prise simulation for APPROVED.", "UserPrepaidCard": { "Id": "ffb06b96-6656-4759-bb50-9989eefd35f3", "CardBrand": "Unknown", "CardApplicationStatus": "Approved", "OnboardStatus": "Approved", "CardNumber": "************8891", "CardStatus": "Activated", "CardReferenceId": "599000154238", "CardRegistrationStatus": "NotRegistered", "CardProgramId": "Zumrail_ProdT", "CardholderId": "599000000000001542", "AvailableBalance": 0.0, "LedgerBalance": 0, "CustomerId": "887ead16-0a27-4f41-8557-da6423a37a6f", "OnboardId": "56ee4d95-723c-47cc-bd0d-464a02483aad", "CreatedAt": "2026-03-19T19:04:23.583527Z", "CardActivatedAt": "2026-03-19T19:13:17.412489Z" }, "ShippingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "BillingAddress": { "AddressLine1": "123 Main Street", "AddressLine2": "Suite 123", "AddressPostalCode": "A1A 1A1", "AddressCountry": "CA", "AddressCity": "Anytown", "AddressState": "ON" }, "Notifications": { "AllowTransactionEmailNotification": true, "AllowTransactionSmsNotification": true, "AllowProfileUpdateEmailNotification": true, "AllowProfileUpdateSmsNotification": true, "AllowLoginSessionEmailNotification": true, "AllowLoginSessionSmsNotification": true } }, "HasPrepaidCardUser": true, "Language": "En" } ] } } ``` {% endtab %} {% tab title="Response (US)" %} ```json { "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", "AccountType": "Personal", "Name": "John Doe", "FirstName": "John", "LastName": "Doe", "PhoneNumber": "8888888888", "Currency": "USD", "Email": "johndoe@gmail.com", "Customer": { "Id": "911388da-5095-4cc9-bf51-cf636dd6c46b", "CompanyName": "US Company" }, "TransactionMethodsAvailable": { "Ach": true, "DebitCard": true, "CreditCard": true }, "TransactionMethodsAvailableDescription": "ACH, Debit Card, Credit Card", "ClientUserId": "1", "IdType": "DL", "IdNumber": "*****6789", "IdState": "CA", "PaymentInstruments": [ { "Id": "9dc4a630-883a-425c-b162-c8c8eb813775", "RoutingNumber": "122105155", "AccountNumber": "2020202020", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressCity": "Brooklyn", "AddressState": "NY", "AddressPostalCode": "11215", "AddressCountry": "USA", "PaymentMethod": "BankAccount" }, { "Id": "0f429457-fec9-4c33-b945-3dae92bb10d3", "Number": "************8889", "ExpireYear": "26", "ExpireMonth": "08", "AddressLine1": "123 street", "AddressLine2": "Apartment 123", "AddressCity": "Brooklyn", "AddressState": "NY", "AddressPostalCode": "11215", "AddressCountry": "USA", "PaymentMethod": "DebitCard" } ] } ] } } ``` {% endtab %} {% endtabs %} **Operators** Use these operators to filter by UserName, ClientUserId, CustomerName and CustomerId
TypeDescription
containsFilter records that contains the value
excludesFilter records that does not contains the value
exactly matchesFilter records that exactly matches the value
**Date operators** Use these operators to filter by CreatedAt
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
UserNamestringnoFirst and/or Last name
UserNameOperatorstringnoOperator to filter with UserName property
CreatedAtdatetimenoCreate date
CreatedAtFromdatetimenoStart date (This field is only used when the operator is IsBetween)
CreatedAtTodatetimenoEnd date (This field is only used when the operator is IsBetween)
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
EmailstringnoUser email
ClientUserIdstringnoExternal Client User Identifier
ClientUserIdOperatorstringnoOperator to filter with ClinetUserId property
CustomerNamestringnoCustomer name (for partners only)
CustomerNameOperatorstringnoOperator to filter with CustomerName property
CustomerIdstringnoCustomer Id (for partners only)
CustomerIdOperatorstringnoOperator to filter with CustomerId property
TransactionMethodAvailableIntegernoTransaction method available for the user
CardStatusstringnoOperator to filter with the CardStatus property when a card is issued
CardOnboardStatusstringnoOperator to filter with the CardOnboardStatus property when a card application is in progress
Paginationno
PageNumbernumbernoThe respective page, starting at 1
ItemsPerPagenumbernoThe amount of items per page between 0 and 100
**Response** {% tabs %} {% tab title="Canada" %}
ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of users
IdguidUser id
CreatedAtdatetimeWhen the user was created
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
EmailstringUser email
LanguagestringLanguage reference
ClientUserIdstringExternal Client User Identifier
BankAccountInformation* if available
LastTimeRefresheddatetimeLast time the account was refreshed
AggregationStatusstringIndicates if the account is linked with the aggregation service
AggregationBalancedecimalAccount balance
NameMatch.ScorenumberA 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.ResultstringA description of the name-match score. It can be “Matched” or “Not Matched”
PrepaidCardUser
IdGuidId of prepaid card
UserIdGuidUserId of prepaid card
FirstNameStringFirst name
LastNameStringLast name
CardApplicationStatusStringCard application status
OnboardStatusStringCard onboarding status
CardNumberStringCard number
CardStatusStringCard status
CardReferenceIdStringCard reference id
CardProgramIdStringCard program id
AvailableBalanceStringCurrent balance of the card
CustomerIdGuidCustomer Id
OnboardIdGuidOnboarding Id
EmailStringEmail on card
LanguageStringLanguage preference on card
HasPrepaidCardUserStringIndicate if this user can do Prepaid Card transactions
{% endtab %} {% tab title="US" %}
ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of users
IdguidUser id
CreatedAtdatetimeWhen the user was created
AccountTypedatetimeType of user account
FirstNamestringFirst name
LastNamestringLast name
CompanyNamestringCompany name
EmailstringEmail address
PhoneNumberstringPhone number
CurrencystringAccount currency
TransactionMethodsAvailableDescriptionstringDescription of available transaction methods
ClientUserIdstringExternal Client User Identifier
IdTypestringID type, can be DL or SSN
IdNumberstringID number
IdStatestringState where ID was issued
CustomerAssociated Customer
IdstringCustomer Id
CompanyNamestringCustomer's company name
TransactionMethodsAvailablestringAvailable transaction methods for user
AchboolIndicate ACH transaction activation state
DebitCardboolIndicate Debit card transaction activation state
CreditCardboolIndicate Credit card transaction activation state
PaymentInstrumentsList of payment instruments
IdstringPayment instrument id
RoutingNumberstringBank account Routing Number
AccountNumberstringBank account Account Number
PaymentMethodstringPayment Method
NumberstringMasked card number with the last 4 digits
ExpireMonthstringCard expiry month, 2 digits
ExpireYearstringCard expiry year, 2 digits
AddressLine1stringCard address line 1 (minimum 3 characters, maximum 30 characters)
AddressLine2stringCard address line 2 (maximum 30 characters)
AddressPostalCodestringCard address postal code
AddressCountrystringCard address country
AddressCitystringCard address city (maximum 32 characters)
AddressStatestringCard address state
{% endtab %} {% endtabs %} TransactionMethod
NumberNameCurrnecy
#NameCurrency
0EftCAD
1InteracCAD
2VisaDirectCAD
3CreditCardCAD
4AchUSD
5DebitCardUSD
6CreditCardUsUSD
7MoneyTransferUSD
8ZumTransferUSD
9ZumCardCAD
10SameDayAchUSD
11RtpFedNowUSD
{% hint style="warning" %} **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. {% endhint %} ## Check RTP or FedNow eligibility 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` {% tabs %} {% tab title="Payload (US)" %} ```json { "RoutingNumbers": [ "011000138" ] } ``` {% endtab %} {% tab title="Response (US)" %} ```json { "statusCode": 200, "message": "POST Request successful.", "isError": false, "result": { "Routing_numbers": [ { "Eligible": true, "Fednow": false, "Routing_number": "011000138", "Rtp": true } ] } } ``` {% endtab %} {% endtabs %} ## Interac - Send Funds options {% hint style="warning" %} **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. {% endhint %} 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 and channel are informed in the URL. The default channel is email\_address when channel parameter is not informed in the URL. `Method: GET` `Endpoint: {{env}}/api/user/GetInteracSendFundsOptions/{user_id}?channel={channel}` Define the channel parameter to verify if the user's e-mail\_address or mobile\_number is registered for autodeposit. Channel options are: (`channel=email_address` or `channel=mobile_number`) {% tabs %} {% tab title="Response" %} ```json { "statusCode": 200, "message": "GET Request successful.", "isError": false, "result": { "RequireSecurityQuestionAndAnswer": true, "AutomaticDepositAvailable": false, "AccountNumberRoutingAvailable": false } } ``` {% endtab %} {% endtabs %} **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 or mobile number 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.
[^1]: To create a new user with card information via API, please contact support. [^2]: When `IDType` is `SSN`, then `IDNumber` should be 9 digits long.