Ways to integrate

There are various ways to integrate with Zūm Rails. Check the options below to decide what fits your workflow:

Full api integration: You can start using our API endpoints (check API documentation here) to create transactions, add users, create invoices, etc. With the API integration you have full control over the UI that your end user will see and you can develop it based on your business use cases. This is one of the most secure ways of integrating since all API requests are using the Bearer Token Authorization. A Bearer Token will last up to an hour from the time it is generated, allowing multiple API calls to be made securely without authorizing each time. Understand more about the Authorize endpoint here.

Portal: You can use the portal to create transactions, add users, create invoices, etc. You can view our FAQs and also check out our video tutorials to learn more about how to start moving money using the portal. If you prefer to use the portal, you will not have to do any API integration and you can start right away through the portal.

Hybrid (recommended): We recommend using a mix of both APIs and the portal as it is more robust and secure to use the APIs and you can view the details of your transactions, keep track of the money being moved, download reports, etc. by leveraging the functionalities available in the Zūm portal. You can use the API/SDK or host our URL within your application to add users, create transactions, send payment links to your users, etc and receive real time updates on the status of users and transactions so you can automate your next call to action depending on the status of the payments.

Zūm Connect#

URL V/S SDK#

Our URLs allow you to host our UI within your application and it's the easiest to use for our clients.
It's a unique URL which you can host as an iframe, send by e-mail or sms. Since, this is a public URL which is not tokenized, it’s not the most recommended option.

The javascript sdk library allows you to build a more robust integration with Zūm Rails. Instead of hosting a public URL, the library offers the possibility for you to first create a temporary token, then initiate and receive real-time updates and listen to events. Hence, it is the best option for our clients.

To start using the library you will need to do the following:

URL add user flow

  1. Authorize using the endpoint {{env}}/api/authorize. More information on how to authorize can be found here.

  2. Create a token which has to be informed in the SDK. Use the endpoint {{env}}/api/connect/createtokensdk to generate the token. The token is valid for 15 minutes, and it will be automatically expired after a user uses it.

    {
    "RequestType": "AddPaymentProfile"
    }
    RequestTypeDescription
    CheckoutProductDefine a request to go to the Connect checkout product
    CheckoutProductPriceDefine a request to go to the Connect checkout product price
    AddPaymentProfileDefine a request to go to the Connect Add payment profile
    AddFundingSourceDefine a request to go to the Connect Add funding source
    UpdateSubscriptionDefine a request to go to the Connect Update subscription
    CancelSubscriptionDefine a request to go to the Connect Cancel subscription
    SubscriptionDetailsDefine a request to go to the Connect Subscription details
    ManageUserPortalDefine a request to go to the Connect Manage user profile
    RequestFundsDefine a request to go to the Connect Request funds
  3. Refer the javascript sdk library into your website, build your configuration options and init the sdk. Inform the token (result.Token) in any request you want to execute.

note

To get the URL/SDK navigate to the settings menu option > Integration codes

Install JS SDK#

Refer the js library bellow into your website.

<script id="zumrailssdk" src="https://cdn.zumrails.com/production/zumsdk.js" type="text/javascript" async=""></script>

Init the JS SDK#

The library expects 1 mandatory parameters:

ParameterDescription
tokenThe token received in the endpoint {{env}}/api/connect/createtokensdk

Bellow you can find an example of the code needed to init the JS SDK.

<script>
$(function() {
$('#btnGoConnect').click(function() {
const token = '<THE TOKEN RECEIVED IN THE CREATE TOKEN ENDPOINT>';
ZumRailsSDK.init({
token: token,
onLoad: function () {
console.log('onLoad');
},
onError: function (error) {
console.log('onError', error);
},
onSuccess: function (data) {
console.log('onSuccess', data);
},
onClosed: function () {
console.log('onClosed');
},
});
});
});
</script>

SDK callbacks#

When something happens, the sdk library will fire a few callbacks, this allows you to easily get the data and take an immediate action. For example, call the endpoint to get the full card information onSuccess by passing the requestId or cardId

onLoad#

This callback is triggered when the UI is loaded and presented on the screen.

Parameters

  • There are no parameters in this callback

onClosed#

This callback is triggered when the end user clicks in the X button to close the Connect

Parameters

  • There are no parameters in this callback

onError#

This callback is triggered when the connection failed by any error not expected in the happy flow

Parameters

  • error: An error message explaining the reason why the failure happened

onSuccess#

This callback is triggered when the connection is completed

Parameters

  • data: The information returned will depend on the RequestType defined.

For example, when you use AddPaymentProfile will return something like this below:

{
invoiceId: null,
userId: '2abc0bda-98bf-40e0-993b-4b76302c0843',
transactionId: null,
subscriptionId: null,
origin: 'ZUM_RAILS'
}

User tokenization / Add payment profile#

The best way to add a user to the Zūm Rails platform is through Zūm Connect. It consists of an iFrame website, hosted by Zūm Rails and referenced in your website.

The Zūm Connect iframe will display a form to capture the user's basic information (Full Name and Email) so that we can create an identity.

Independent of the method, the user will always be asked to agree and consent the information shared (PAD). The message can be customized for your needs as well. Your specific settings will be available under your profile in Zūm Rails portal. Depending on your need, you can capture the new user using our webhook mechanism, or if you need it right at the moment we redirect back to your flow, you can capture the Zūm user id (token) by listening to an event message as described in your portal settings.

After a user creates and links his account, you will be able to view it in the Zūm Rails portal or use the API to filter and get a specific user.

Add payment profile using URL#

URL add user flow

Pre-filling the form#

To help streamline the Zūm Connect experience, it is possible to pass information that you already have through optional parameters in the url:

NameDescription
accountTypePersonal or Business
firstNameUser first name, when the account type is Personal
lastNameUser last name, when the account type when is Personal
emailUser email
companyNameCompany name, when the account type is Business
memoTransaction memo that will be created with the request funds.
commentTransaction comment that will be created with the request funds.
allowEftTo display only EFT payment method.
allowInteracTo display only INTERAC payment method.
allowVisaDirectTo display only VISA DIRECT payment method.
allowCreditCardTo display only CREDIT CARD payment method.
displayTermsAndConditionTo display the terms and conditions checkbox or not.
displayDetailsColumnTo display the left side column with transaction details, amount and recurrency
displayZumRailsLogoTo display the powered by Zūm Rails logo
displayPhoneNumberTo display the phone number field
displayAccountTypeTo display account type option
displayFullNameTo display a full name field instead of first and last name fields when the user chooses Personal as account type. (It can be pre-filled with firstName query param)
hideBackButtonTo hide all back buttons
hideShippingAddressTo hide the shipping address
hideRailsNameTo hide the rails name when there is just one
hideFirstName*To hide the first name field
hideLastName*To hide the last name field
hideFullName*To hide the full name field
hideEmail*To hide the email field
hideCreditCardAddress*To hide all the credit card address fields
languageChange the connect language. There are two available options: en (english) and fr (french). If not set, the language will be chosen according to the browser language. English is applied if the given language is not available
backgroundColorChange the background color around the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)
foregroundColorChange the foreground color in the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)
disablePreFilledFieldsDisable all fields that received a value by query parameter (Example: firstName, lastName...)
creditCardAddresLine1Define the field address line 1 in credit card tab
creditCardAddresLine2Define the field address line 2 in credit card tab
creditCardCityDefine the field city in credit card tab
creditCardProvinceDefine the field province/territory in credit card tab
creditCardPostalCodeDefine the field postal code in credit card tab
creditCardCountryDefine the field country in credit card tab. NOTE: Currently we only accept "Canada" as the value for this parameter. Any other values, if specified, will be ignored.
info

Hiding a field doesn't mean that it is no longer mandatory, please use the other query params to pre-fill: firstName, lastName, email, etc.

The field creditCardProvince can be defined with this state abbreviations:

AbbreviationDescription
ABAlberta
BCBritish Columbia
MBManitoba
NBNew Brunswick
NLNewfoundland and Labrador
NSNova Scotia
NTNorthwest Territories
NUNunavut
ONOntario
PEPrince Edward Island
QCQuebec
SKSaskatchewan
YTYukon

Examples:

{{env}}/connect-adduser/{{customerId}}?accountType=personal&firstname=Name&lastname=Last&email=user@zumrails.com

{{env}}/connect-adduser/{{customerId}}/{{requestFundsId}}?accountType=personal&memo=memo&comment=here%20is%20an%20example%20comment

{{env}}/connect-adduser/{{customerId}}?allowEft=true&language=fr

{{env}}/connect-adduser/{{customerId}}?allowEft=true&allowInterac=true

Event Listeners#

When a new user is added or a request funds is fulfilled, Zūm Connect will trigger an event to provide to your application the UserId, TransactionId or RecurrentTransactionId.

To listen to the event in js, your website must refer to Zūm Connect using an iFrame, and then your website should have the script/example.

<script>
window.addEventListener('message', function(e) {
var data = e.data;
if (data && data.origin && data.origin === 'ZUM_RAILS') {
console.log(data);
}
});
</script>
{
"origin": "ZUM_RAILS",
"userId": "c18dd952-...-9bd6a46eb1c4"
}

Add payment profile using SDK#

URL add user flow

Once authorized, the next step is to create a token. You will need to create a token with the payload as below.

{
"RequestType": "AddPaymentProfile"
}

Callbacks#

{
"invoiceId": "null",
"userId": "80d53753-a9f7-4b81-93f0-44879ed778af",
"transactionId": "null",
"subscriptionId": null,
"origin": "ZUM_RAILS"
}

Invoice checkout#

The best way to let the user choose and pay for an item is using the checkout. It consists of an iFrame website, hosted by Zūm Rails and referenced in your website. The Iframe will display the products/prices to the user and they can choose what they would like to pay for. It will display the form to collect the user’s payment information, then create a transaction and send the invoice to the user over their email once the transaction is successful.

Invoice checkout using URL#

flow18

Event Listener#

When a new invoice is created through checkout, Zūm Connect will trigger an event to provide to your application the UserId, TransactionId or InvoiceId.

To listen to the js event, your website must refer to Zūm Connect using an iFrame, and then your website should have the script/example as described.

{
"origin": "ZUM_RAILS",
"invoiceId": "c18dd952-...-9bd6a46eb1c4",
"userId": "c18dd952-...-9bd6a46eb1c4",
"transactionId": "c18dd952-...-9bd6a46eb1c4"
}

Invoice checkout using SDK#

flow13

Once authorized, the next step is to create a token. You will need to create a token with the payload as below based on if it's a checkout for an entire product or a specific product price.

{
"RequestType": "CheckoutProduct",
"ProductId": "01cd838e-9f07-47e9-8581-ecc324b0529b"
}

Callbacks#

{
"invoiceId": "60ca0702-40ef-4d8a-ab5d-0788382c7934",
"userId": "80d53753-a9f7-4b81-93f0-44879ed778af",
"transactionId": "15de3094-84d8-4c6b-b001-02384be50ba1",
"subscriptionId": null,
"origin": "ZUM_RAILS"
}

Subscription checkout#

The best way to let the user choose and subscribe to an item is using the checkout. It consists of an iFrame website, hosted by Zūm Rails and referenced in your website. The Iframe will display the products/prices to the user and they can choose what they would like to subscribe to. It will display the form to collect the user’s payment information, create the subscription and email the subscription details to the user.

note

In case of subscription, a new invoice will be generated based on the billing cycle. Whenever a new invoice is generated we will automatically charge the payment method that was used when creating the subscription using the checkout link.

Subscription checkout using URL#

URL subscriptionw

Event Listener#

When a new subscription is created through checkout, Zūm Connect will trigger an event to provide to your application the UserId, TransactionId or subscriptionId.

To listen to the js event, your website must refer to Zūm Connect using an iFrame, and then your website should have the script/example as described.

{
"origin": "ZUM_RAILS",
"subscriptionId": "c18dd952-...-9bd6a46eb1c4",
"userId": "c18dd952-...-9bd6a46eb1c4",
"transactionId": "c18dd952-...-9bd6a46eb1c4"
}

Subscription checkout using SDK#

flow13

Once authorized, the next step is to create a token. You will need to create a token with the payload as below based on if it's a checkout for an entire product or a specific product price.

{
"RequestType": "CheckoutProduct",
"ProductId": "01cd838e-9f07-47e9-8581-ecc324b0529b"
}

Callbacks#

{
"invoiceId": null,
"userId": "80d53753-a9f7-4b81-93f0-44879ed778af",
"transactionId": null,
"subscriptionId": "578c3ddf-64ec-4479-ad7a-a3154bbe64c4",
"origin": "ZUM_RAILS"
}

Manage Subscriptions#

This library will allow the users to manage their subscriptions (view, cancel or update them). It consists of an iFrame website, hosted by Zūm Rails and referenced in your website.

View or Update a subscription using the SDK#

flow2

Once authorized, the next step is to create a token. You will need to create a token with the payload as below.

{
"RequestType": "UpdateSubscription",
"SubscriptionId": "01cd838e-9f07-47e9-8581-ecc324b0529b"
}

Cancel subscription using SDK#

flow3

Once authorized, the next step is to create a token. You will need to create a token with the payload as below.

{
"RequestType": "CancelSubscription",
"SubscriptionId": "01cd838e-9f07-47e9-8581-ecc324b0529b"
}

Callbacks#

{
"invoiceId": "null",
"userId": "null",
"transactionId": "null",
"subscriptionId": 80d53753-a9f7-4b81-93f0-44879ed778af,
"origin": "ZUM_RAILS"
}

Manage user account#

This library will allow the users to manage their account (view, cancel or update, pay for subscriptions/invoices). It consists of an iFrame website, hosted by Zūm Rails and referenced in your website.

Manage user account using SDK#

flow17

Once authorized, the next step is to create a token. You will need to create a token with the payload as below.

{
"RequestType": "ManageUserPortal",
"Email": "customer@zumrails.com"
}
note

Each user will receive a link along with the emails for invoices/subscription which they can use to manage their account. If they initiate this flow on their own they will be asked to enter their email address > Zum will check if that email address has any subscriptions/invoices under your customer account > if yes, we will send a one-time passcode to the users’ email which if matches with what the user enters in the UI, we will show them their Invoices/subscriptions/payment details.

Request funds#

Once authorized, the next step is to create a token. You will need to create a token with the payload as below.

{
"RequestType": "RequestFunds",
"RequestFundsId": "e212a298-4f39-4ac0-b9d6-60fc1c215176"
}

Callbacks#

{
"origin": "ZUM_RAILS",
"userId": "2b500e4e-a5fe-4697-a88b-07eb8162cc22",
"transactionId": "f884b81d-9335-4560-b764-aee1e369791d"
}