Ways to Integrate

There are various ways to integrate with Zūm Rails:

Full API Integration: You can start using our API endpoints (see documentation here) to add users, create transactions, 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 to Zūm Rails. Read more about the authorize endpoint here.

Portal: You can use the portal to add users, create transactions, etc. You can view our knowledgebase and FAQs 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.

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 and do much more by leveraging the functionalities available in the Zūm portal.

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/createtoken to generate the token. The token is valid for 15 minutes, and it will be automatically expired after a user uses it.

    {
    "ConnectTokenType": "AddPaymentProfile",
    "Configuration": {
    "allowCreditCard": true
    }
    }
ConnectTokenTypeDescription
AddPaymentProfileDefine a request to go to the Connect Add payment profile
info

You can also define configurations that will change the behavior of the forms for the requested process. For that you can used the parameters defined here.

  1. 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/createtoken

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)
},
onButtonClose: function () {
console.log("onButtonClose")
},
})
})
})
</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

onButtonClose#

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 ConnectTokenType defined.

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

{
"userId": "2abc0bda-98bf-40e0-993b-4b76302c0843",
"origin": "ZUM_RAILS",
"clientUserId": null,
"extraField1" : null,
"extraField2" : null
}

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
firstNameUser first name, when the account type is Personal
lastNameUser last name, when the account type when is Personal
allowCreditCardTo display only CREDIT CARD payment method.
allowAchTo display only ACH (bank) payment method.
displayTermsAndConditionsTo display the terms and conditions checkbox or not.
displayZumRailsLogoTo display the powered by Zūm Rails logo
hideRailsNameTo hide the rails name when there is just one
hideCreditCardAddress*To hide all the credit card address fields
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...)
creditCardAddressLine1Define the field address line 1 in credit card tab
creditCardAddressLine2Define the field address line 2 in credit card tab
creditCardAddressCityDefine the field city in credit card tab
creditCardAddressProvinceDefine the field province/territory in credit card tab
creditCardAddressPostalCodeDefine the field postal code in credit card tab
creditCardAddressCountryDefine the field country in credit card tab.
accountType“Personal” or “Business”
companyNameCompany name, when the account type is Business
idTypeThe type of ID: “DL” or “SSN”, when the account type is Personal
idNumberID (DL or SSN) number, when the account type is Personal
idStateState where ID was issued, when the account type is Personal and id type is DL
businessTaxIdBusiness tax ID, when the account type is Business
billingAddressLine1Define the field address line 1 in bank tab
billingAddressLine2Define the field address line 2 in bank tab
billingAddressCityDefine the field city in bank tab
billingAddressProvinceDefine the field state in bank tab
billingAddressPostalCodeDefine the field postal code in bank tab
clientUserIdYour internal user id for user added
extraField1User extra field 1
extraField2User extra field 2
successURLThe URL to which Zum Rails will redirect end-users, after the payment is initiated by the end-user.
cancelURLThe URL to which Zum Rails will redirect end-users, when they decide to cancel the payment.
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.

info

The field creditCardAddressProvince and creditCardAddressCountry should follow the countries and administrative regions definitions.

Examples:

{{env}}/connect-adduser/{{customerId}}v2?creditCardAddressCountry=JP&creditCardAddressPostalCode=150-2345&creditCardAddressCity=Tokyo&creditCardAddressProvince=JP-13&creditCardAddressLine1=8-43-2%20Nishiogu&creditCardAddressLine2=Arakawa&hideCreditCardAddress=false&disablePreFilledFields=true

{{env}}/connect-adduser/{{customerId}}v2?firstName=John

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",
"clientUserId": null,
"extraField1" : null,
"extraField2" : null
}

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. For this specific type of request the parameters for the allowment of rails are mandatory.

{
"ConnectTokenType": "AddPaymentProfile",
"Configuration": {
"allowCreditCard": true
}
}

Callbacks#

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

Hosted Checkout#

The Hosted Checkout feature enables developers to quickly generate a secure, customizable payment page by providing product details like name, price, and description. Customers can complete transactions using their preferred payment method through a seamless, white-labeled interface. This solution simplifies payment integration, offering a PCI-compliant checkout experience that maintains brand consistency across different platforms.

Hosted Checkout using SDK#

Once authorized, the next step is to create a token. You will need to create a token with the payload as below. Follow the examples to see how to handle the product information, fees attached to product and specific configurations

{
"ConnectTokenType": "HostedCheckout",
"Amount": 10.0,
"Items": [
{
"Name": "Product Name",
"Price": 10.0
}
]
}
note

Some fields, if not informed, will have default values.

  • If ExpirationUTC isn't specified, the token will be valid during the next 24 hours;
  • If Quantity, property of the object inside of the Items list, isn't informed, it's value will be 1;
  • If none transaction method is specified (by the fields allowEft, allowInterac, allowVisaDirect, allowCreditCard and allowAch), then the payment methods on the Hosted Checkout will be the ones enabled for the customer that called the API.

Callbacks#

{
"origin": "ZUM_RAILS",
"invoiceId": "731eabd7-9b50-469f-ab8b-54f7ec89109f",
"userId": "80d53753-a9f7-4b81-93f0-44879ed778af",
"transactionId": "0795b370-b2c8-431d-899c-3b54d589e8b0",
"sessionId" : "89d53753b2c8431d899c54f7ec89109f"
}