# 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.

### Connect SDK (Install & Init)

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

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2F7ksnHY6Zn3qxJ86DcNKv%2Fimage.png?alt=media&#x26;token=d2b76021-8580-445f-82d2-5c85c9f67878" alt=""><figcaption></figcaption></figure>

1. **Authorize** using the endpoint `{{env}}/api/authorize`.&#x20;
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.

{% tabs %}
{% tab title="Payload" %}

```json
{
  "ConnectTokenType": "AddPaymentProfile",
  "Configuration": {
    "allowEft": true,
    "allowInterac": true,
    "allowVisaDirect": true,
    "allowCreditCard": true
  }
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "statusCode": 200,
  "message": "POST Request successful.",
  "isError": false,
  "result": {
    "Token": "production|AddPaymentProfile|85dedfcd-f8de-45e4-851a-5a8b79b75e15|a4ae068aeeea49859c266605a5c3cddd",
    "ExpirationUTC": "2022-03-21T13:30:56.4052997Z",
    "CustomerId": "85dedfcd-f8de-45e4-851a-5a8b79b75e15",
    "CompanyName": "Company To Test",
    "Environment": "production",
    "ConnectTokenType": " "
  }
}
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="225.199951171875">ConnectTokenType</th><th>Description</th></tr></thead><tbody><tr><td>CheckoutProduct</td><td>Define a request to go to the Connect checkout product</td></tr><tr><td>CheckoutProductPrice</td><td>Define a request to go to the Connect checkout product price</td></tr><tr><td>AddPaymentProfile</td><td>Define a request to go to the Connect Add payment profile</td></tr><tr><td>AddFundingSource</td><td>Define a request to go to the Connect Add funding source</td></tr><tr><td>UpdateSubscription</td><td>Define a request to go to the Connect Update subscription</td></tr><tr><td>CancelSubscription</td><td>Define a request to go to the Connect Cancel subscription</td></tr><tr><td>SubscriptionDetails</td><td>Define a request to go to the Connect Subscription details</td></tr><tr><td>ManageUserPortal</td><td>Define a request to go to the Connect Manage user profile</td></tr><tr><td>ViewCardInformation</td><td>Define a request to go to the View Card Information</td></tr><tr><td>RequestFunds</td><td>Define a request to go to the Connect Request funds</td></tr><tr><td>InvoicePayment</td><td>Define a request to go to the Connect Invoice Payment</td></tr><tr><td>InvoiceDownload</td><td>Define a request to go to the Connect Invoice Download</td></tr><tr><td>SendFunds</td><td>Define a request to go to the Connect Send Funds</td></tr><tr><td><a href="../../payments/card-payments/visa-direct#id-3d-secure">ThreeDS</a></td><td>Define a request to go to the Connect ThreeDS</td></tr><tr><td>HostedCheckout</td><td>Define a request to go to the Hosted Checkout</td></tr><tr><td>CardOnboarding</td><td>Define a request to go to the Card Onboarding application</td></tr></tbody></table>

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.

{% hint style="info" %}
**NOTE**\
To get the URL/SDK navigate to the settings menu option > Integration codes
{% endhint %}

#### Install & Initialize the SDK

Use the JavaScript library below to integrate the SDK into your website. Make sure to use the appropriate URL—one for the sandbox environment and another for production.

Sandbox

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

Production

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

The library expects 1 mandatory parameter:

<table><thead><tr><th width="154.79998779296875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>token</td><td>The token received in the endpoint <code>{{env}}/api/connect/createtoken</code></td></tr></tbody></table>

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

```html
<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 <a href="#onload" id="onload"></a>

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

*Parameters*

* There are no parameters in this callback

#### onButtonClose <a href="#onbuttonclose" id="onbuttonclose"></a>

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 <a href="#onerror" id="onerror"></a>

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 <a href="#onsuccess" id="onsuccess"></a>

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:

```json
{
  "invoiceId": null,
  "userId": "2abc0bda-98bf-40e0-993b-4b76302c0843",
  "transactionId": null,
  "subscriptionId": null,
  "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

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2F9XOUjtvWHfJMAVrprqzC%2Fimage.png?alt=media&#x26;token=1e178833-2099-4b2b-a95c-e85563bc9b60" alt=""><figcaption></figcaption></figure>

#### 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:

{% tabs %}
{% tab title="Canada" %}

<table><thead><tr><th width="226.5999755859375">Name</th><th>Description</th></tr></thead><tbody><tr><td>accountType</td><td>Personal or Business</td></tr><tr><td>firstName</td><td>User first name, when the account type is Personal</td></tr><tr><td>lastName</td><td>User last name, when the account type when is Personal</td></tr><tr><td>dateOfBirth</td><td>User date of birth</td></tr><tr><td>email</td><td>User email</td></tr><tr><td>companyName</td><td>Company name, when the account type is Business</td></tr><tr><td>memo</td><td>Transaction memo that will be created with the <em>request funds</em>. The limit is 15 characters</td></tr><tr><td>comment</td><td>Transaction comment that will be created with the <em>request funds</em>. The limit is 400 characters</td></tr><tr><td>allowEft</td><td>To display only EFT payment method.</td></tr><tr><td>allowInterac</td><td>To display only INTERAC payment method.</td></tr><tr><td>allowVisaDirect</td><td>To display only VISA DIRECT payment method.</td></tr><tr><td>allowCreditCard</td><td>To display only CREDIT CARD payment method.</td></tr><tr><td>displayTermsAndCondition</td><td>To display the terms and conditions checkbox or not.</td></tr><tr><td>displayDetailsColumn</td><td>To display the left side column with transaction details, amount and recurrency</td></tr><tr><td>displayZumRailsLogo</td><td>To display the powered by Zūm Rails logo</td></tr><tr><td>displayPhoneNumber</td><td>To display the phone number field</td></tr><tr><td>displayAccountType</td><td>To display account type option</td></tr><tr><td>displayFullName</td><td>To 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)</td></tr><tr><td>hideBackButton</td><td>To hide all back buttons</td></tr><tr><td>hideShippingAddress</td><td>To hide the shipping address</td></tr><tr><td>hideRailsName</td><td>To hide the rails name when there is just one</td></tr><tr><td>hideFirstName*</td><td>To hide the first name field</td></tr><tr><td>hideLastName*</td><td>To hide the last name field</td></tr><tr><td>hideFullName*</td><td>To hide the full name field</td></tr><tr><td>hideEmail*</td><td>To hide the email field</td></tr><tr><td>hideCreditCardAddress*</td><td>To hide all the credit card address fields</td></tr><tr><td>language</td><td>Change 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</td></tr><tr><td>backgroundColor</td><td>Change the background color around the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)</td></tr><tr><td>foregroundColor</td><td>Change the foreground color in the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)</td></tr><tr><td>disablePreFilledFields</td><td>Disable all fields that received a value by query parameter (Example: firstName, lastName...)</td></tr><tr><td>creditCardAddresLine1</td><td>Define the field address line 1 in credit card tab</td></tr><tr><td>creditCardAddresLine2</td><td>Define the field address line 2 in credit card tab</td></tr><tr><td>creditCardCity</td><td>Define the field city in credit card tab</td></tr><tr><td>creditCardProvince</td><td>Define the field province/territory in credit card tab</td></tr><tr><td>creditCardPostalCode</td><td>Define the field postal code in credit card tab</td></tr><tr><td>creditCardCountry</td><td>Define 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.</td></tr><tr><td>clientUserId</td><td>Your internal user id for user added.</td></tr><tr><td>extraField1</td><td>User extra field 1</td></tr><tr><td>extraField2</td><td>User extra field 2</td></tr><tr><td>successURL</td><td>The URL to which Zum Rails will redirect end-users, after the payment is initiated by the end-user.</td></tr><tr><td>cancelURL</td><td>The URL to which Zum Rails will redirect end-users, when they decide to cancel the payment.</td></tr></tbody></table>

{% endtab %}

{% tab title="US" %}

<table><thead><tr><th width="241.7999267578125">Name</th><th>Description</th></tr></thead><tbody><tr><td>firstName</td><td>User first name, when the account type is Personal</td></tr><tr><td>lastName</td><td>User last name, when the account type when is Personal</td></tr><tr><td>email</td><td>User email</td></tr><tr><td>allowCreditCard</td><td>To display only CREDIT CARD payment method.</td></tr><tr><td>allowAch</td><td>To display only ACH (bank) payment method.</td></tr><tr><td>displayTermsAndConditions</td><td>To display the terms and conditions checkbox or not.</td></tr><tr><td>displayZumRailsLogo</td><td>To display the powered by Zūm Rails logo</td></tr><tr><td>hideRailsName</td><td>To hide the rails name when there is just one</td></tr><tr><td>hideCreditCardAddress*</td><td>To hide all the credit card address fields</td></tr><tr><td>backgroundColor</td><td>Change the background color around the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)</td></tr><tr><td>foregroundColor</td><td>Change the foreground color in the form with a hex code (Only numbers, you don't need to send the hash symbol prefix)</td></tr><tr><td>disablePreFilledFields</td><td>Disable all fields that received a value by query parameter (Example: firstName, lastName...)</td></tr><tr><td>creditCardAddressLine1</td><td>Define the field address line 1 in credit card tab</td></tr><tr><td>creditCardAddressLine2</td><td>Define the field address line 2 in credit card tab</td></tr><tr><td>creditCardAddressCity</td><td>Define the field city in credit card tab</td></tr><tr><td>creditCardAddressProvince</td><td>Define the field province/territory in credit card tab</td></tr><tr><td>creditCardAddressPostalCode</td><td>Define the field postal code in credit card tab</td></tr><tr><td>creditCardAddressCountry</td><td>Define the field country in credit card tab.</td></tr><tr><td>accountType</td><td>“Personal” or “Business”</td></tr><tr><td>companyName</td><td>Company name, when the account type is Business</td></tr><tr><td>idType</td><td>The type of ID: “DL” or “SSN”, when the account type is Personal</td></tr><tr><td>idNumber</td><td>ID (DL or SSN) number, when the account type is Personal</td></tr><tr><td>idState</td><td>State where ID was issued, when the account type is Personal and id type is DL</td></tr><tr><td>businessTaxId</td><td>Business tax ID, when the account type is Business</td></tr><tr><td>billingAddressLine1</td><td>Define the field address line 1 in bank tab</td></tr><tr><td>billingAddressLine2</td><td>Define the field address line 2 in bank tab</td></tr><tr><td>billingAddressCity</td><td>Define the field city in bank tab</td></tr><tr><td>billingAddressProvince</td><td>Define the field state in bank tab</td></tr><tr><td>billingAddressPostalCode</td><td>Define the field postal code in bank tab</td></tr><tr><td>billingAddressCountry</td><td>Define the field country in bank tab. See <a data-mention href="../api-reference/country-and-region-codes">country-and-region-codes</a> for more information.</td></tr><tr><td>clientUserId</td><td>Your internal user id for user added</td></tr><tr><td>extraField1</td><td>User extra field 1</td></tr><tr><td>extraField2</td><td>User extra field 2</td></tr><tr><td>successURL</td><td>The URL to which Zum Rails will redirect end-users, after the payment is initiated by the end-user.</td></tr><tr><td>cancelURL</td><td>The URL to which Zum Rails will redirect end-users, when they decide to cancel the payment.</td></tr><tr><td>singleAccountSelection</td><td>Enable the user to select a specific account Chequing or Savings and disable all others.</td></tr><tr><td>displayBankConnection</td><td><p>Controls whether users can manually enter and verify their bank account details in the Connect UI if aggregation fails or their institution isn't listed. </p><p>Supported values are:</p><ul><li><code>none</code>: Manual connection is disabled (default).</li><li><code>all</code>: Manual connection is shown on the search page, consent page, and if aggregation fails.</li><li><code>hideOnConsentPage</code>: Manual connection is shown only on the search page and if aggregation fails.</li></ul><p>To enable this feature, please contact us via the chat in the Zūm Rails portal or email us at <a href="mailto:support@zumrails.com">support@zumrails.com</a>.</p></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**NOTE**

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.
{% endhint %}

The field `creditCardProvince` can be defined with this state abbreviations:

| Abbreviation | Description               |
| ------------ | ------------------------- |
| AB           | Alberta                   |
| BC           | British Columbia          |
| MB           | Manitoba                  |
| NB           | New Brunswick             |
| NL           | Newfoundland and Labrador |
| NS           | Nova Scotia               |
| NT           | Northwest Territories     |
| NU           | Nunavut                   |
| ON           | Ontario                   |
| PE           | Prince Edward Island      |
| QC           | Quebec                    |
| SK           | Saskatchewan              |
| YT           | Yukon                     |

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`

#### &#x20;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.

```javascript
<script>
  window.addEventListener("message", function (e) {
    var data = e.data
    if (data && data.origin && data.origin === "ZUM_RAILS") {
      console.log(data)
    }
  })
</script>
```

\
Add User Event&#x20;

```json
{
  "origin": "ZUM_RAILS",
  "userId": "c18dd952-...-9bd6a46eb1c4",
  "clientUserId": null,
  "extraField1" : null,
  "extraField2" : null
}
```

**Add Payment Profile using SDK**&#x20;

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FvnnKP5QvdvPWK7kGr2Py%2Fimage.png?alt=media&#x26;token=4e7354cc-1e35-49d2-aca6-478409427963" alt=""><figcaption></figcaption></figure>

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.

{% tabs %}
{% tab title="Add a payment profile without name matching" %}

```json
{
  "ConnectTokenType": "AddPaymentProfile",
  "Configuration": {
    "allowEft": true,
    "allowInterac": true,
    "allowVisaDirect": true,
    "allowCreditCard": true
  }
}
```

{% endtab %}

{% tab title="Add a payment profile with name matching" %}

```json
{
  "ConnectTokenType": "AddPaymentProfile",
  "User": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "test@zumrails.com",
    "addressCity": "Montréal",
    "addressLine1": "4975 Rue de Sorel",
    "addressProvince": "QC",
    "addressPostalCode": "H4P1G3"
  },
  "Configuration": {
    "allowEft": true,
    "allowInterac": true,
    "allowVisaDirect": true,
    "allowCreditCard": true
  }
}
```

{% endtab %}
{% endtabs %}

**Callbacks**

{% tabs %}
{% tab title="onSuccess" %}

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

{% endtab %}
{% endtabs %}

### **Update Payment Profile**

The Update Payment Profile Token Type allows customers to let end users add or update a credit card on their existing profile through the SDK. This provides a seamless and secure experience for managing payment methods, while preventing the creation of duplicate user profiles.

If a payment method (e.g., a credit card) already exists for the user, the new details will overwrite the existing method.

```json
{
  "ConnectTokenType": "UpdatePaymentProfile",
  "UserId": "772645eb-0ed9-4ff4-b8ac-47b1d115736d",
  "Configuration": {
    "allowEft": false,
    "allowVisaDirect": false,
    "allowCreditCard": true
  }
}
```

{% hint style="info" %}
**NOTE**

* User personal details such as first name, last name, email, and phone number are pre-filled and not editable during this flow.
* The token can be configured to allow Credit Card only.
* Supports pre-filled form parameters and standard SDK callbacks.
* UserId is required to associate the updated payment method with an existing user.
* This token type is currently available only to Canadian customers.
  {% endhint %}

### **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

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FSqQDnVdXyyYPYQe5c487%2Fimage.png?alt=media&#x26;token=d71b29c6-047c-4a98-b011-d1c62df5054f" alt=""><figcaption></figcaption></figure>

#### 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.

{% tabs %}
{% tab title="Other Rails" %}

```json
{
  "origin": "ZUM_RAILS",
  "invoiceId": "c18dd952-...-9bd6a46eb1c4",
  "userId": "c18dd952-...-9bd6a46eb1c4",
  "transactionId": "c18dd952-...-9bd6a46eb1c4",
  "clientUserId": null,
  "extraField1" : null,
  "extraField2" : null
}
```

{% endtab %}

{% tab title="EFT" %}

```json
{
  "origin": "ZUM_RAILS",
  "userId": "c18dd952-...-9bd6a46eb1c4",
  "clientUserId": null,
  "extraField1" : null,
  "extraField2" : null
}
```

{% endtab %}
{% endtabs %}

**Invoice Checkout using SDK**&#x20;

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2Fp9Bgwcifj2rI8j69VlJJ%2Fimage.png?alt=media&#x26;token=2959df9f-29c8-4b57-a912-0930cd6a50dd" alt=""><figcaption></figcaption></figure>

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.

{% tabs %}
{% tab title="Checkout for a product" %}

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

{% endtab %}

{% tab title="Checkout for a specific product price " %}

```json
{
  "ConnectTokenType": "CheckoutProductPrice",
  "ProductId": "01cd838e-9f07-47e9-8581-ecc324b0529b"
}
```

{% endtab %}
{% endtabs %}

**Callbacks**

{% tabs %}
{% tab title="onSuccess" %}

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

{% endtab %}
{% endtabs %}

### 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.

{% hint style="info" %}
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.
{% endhint %}

#### Subscription checkout using URL

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2F8CrfAIml2c1tMZ0AkQNh%2Fimage.png?alt=media&#x26;token=4a51d46e-c020-483b-af7c-182ca1e1a8cb" alt=""><figcaption></figcaption></figure>

#### 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.

{% tabs %}
{% tab title="Other Rails" %}

```json
{
  "origin": "ZUM_RAILS",
  "subscriptionId": "c18dd952-...-9bd6a46eb1c4",
  "userId": "c18dd952-...-9bd6a46eb1c4",
  "transactionId": "c18dd952-...-9bd6a46eb1c4",
  "clientUserId": null,
  "extraField1" : null,
  "extraField2" : null
}
```

{% endtab %}

{% tab title="EFT" %}

```json
{
  "origin": "ZUM_RAILS",
  "userId": "c18dd952-...-9bd6a46eb1c4",
  "clientUserId": null,
  "extraField1" : null,
  "extraField2" : null
}
```

{% endtab %}
{% endtabs %}

#### Subscription checkout using SDK

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2F34mQNkIlP4TYXNNoUuds%2Fimage.png?alt=media&#x26;token=346c2bf1-a9c9-452a-9b2b-365fd94d9db5" alt=""><figcaption></figcaption></figure>

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.

{% tabs %}
{% tab title="Checkout for a product" %}

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

{% endtab %}

{% tab title="Checkout a specific product price" %}

```json
{
  "ConnectTokenType": "CheckoutProductPrice",
  "ProductId": "01cd838e-9f07-47e9-8581-ecc324b0529b"
}
```

{% endtab %}
{% endtabs %}

#### Callbacks

{% tabs %}
{% tab title="onSuccess" %}

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

{% endtab %}
{% endtabs %}

### 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 <a href="#view-or-update-a-subscription-using-the-sdk" id="view-or-update-a-subscription-using-the-sdk"></a>

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FGyodakELXC4uMQfJYjZe%2Fimage.png?alt=media&#x26;token=539d722c-6d40-4df9-8249-bb9ccbc03f2d" alt=""><figcaption></figcaption></figure>

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

**Cancel a Subscription**

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

#### Callbacks

{% tabs %}
{% tab title="onSuccess" %}

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

{% endtab %}
{% endtabs %}

### 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 <a href="#manage-user-account-using-sdk" id="manage-user-account-using-sdk"></a>

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FtaOZsdTZZ8bSzaTFOKET%2Fimage.png?alt=media&#x26;token=16a9d1aa-a642-4039-a3ec-3a9083917b02" alt=""><figcaption></figcaption></figure>

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

**Manage user portal**

```json
{
  "ConnectTokenType": "ManageUserPortal",
  "Email": "customer@zumrails.com"
}
```

{% hint style="info" %}
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 > Zūm 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.
{% endhint %}

### View Card Information

This workflow allows the cardholder to view the card details through a security process using the SDK token “ViewCardInformation”.

{% tabs %}
{% tab title="Payload" %}

```json
{
     "ConnectTokenType": "ViewCardInformation",
     "UserId": "f414fd80-ef5d-42d7-91b2-9546d2501b5d"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Token": "master|ViewCardInformation|f414fd80-ef5d-42d7-91b2-9546d2501b5d|bbb63ba328074eb8a03af9672b9e8de3",
        "ExpirationUTC": "2025-05-30T18:59:10.3233582Z"
    }
}
```

{% endtab %}
{% endtabs %}

Refer the javascript sdk library into your website, build your configuration options and init the SDK. Inform the token (result.Token) in the request you want to execute.

The card details iframe will be loaded with the card details information as image below.

\
![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcljrjBBelBgEmRh_cn2XVoOUzbA_H4KlFhOJR0M4Of5U-UjO4MR18wwIRLDWytFWP6i7oZwlLTTQSVL1Kg9iz32vCbiFiswodlEDfVC2KgthMMjilfc_NnZrvNPhpWVg2AcY3KfA?key=Szd33rytV1GAOW8yMVSo6v-F)<br>

{% hint style="info" %}
**NOTE**

SDK Callbacks for this Token Type are onButtonClose and onError
{% endhint %}

### Card Onboarding

This workflow allows the cardholder to apply for the card using the SDK token "CardOnboarding".

Alternatively, 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 public URL which you can host as an iframe, send by e-mail or sms. Your unique public URL can be found in the Settings --> Integration Codes page on the Zūm Rails portal.

{% tabs %}
{% tab title="Payload" %}

```json
{
     "ConnectTokenType": "CardOnboarding"
     "Language": "fr"
}
```

{% endtab %}

{% tab title="Complimentary  information" %}

```json
{
     "ConnectTokenType": "CardOnboarding",
     "Configuration": {
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@zumrails.com"
     }
}
```

{% endtab %}
{% endtabs %}

The card onboarding iFrame will be loaded.

For complimentary information, refer to [Pre-filling the form](#pre-filling-the-form).

#### **Event Listener**

When a new card onboard application is created through [Card Onboarding](#card-onboarding), 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.

```json
{
     "origin": "ZUM_RAILS",
     "customerId": "731ec4d9-4f14-43cb-9c38-ebd5c80665fa",
     "userId": "1905845e-1309-4529-a66e-61933b31e561",
     "sessionId": "09da52dd94f144ed8dc631e3a655ee74"
} 
```

### 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 <a href="#hosted-checkout-using-sdk" id="hosted-checkout-using-sdk"></a>

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

{% tabs %}
{% tab title="Mandatory fields" %}

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

{% endtab %}

{% tab title="Complementary information" %}

```json
{
  "ConnectTokenType": "HostedCheckout",
  "Amount": 10.0,
  "ReturnTokenWithoutUrl": true,
  "ExpirationUTC": "2024-09-15T17:53:17.8033045Z",
  "Items": [
    {
      "Name": "Item to sell",
      "Description": "Description of the item to sell",
      "Price": 10.0,
      "Quantity": 1,
      "ImageUrl": "https://image-url-example"
    }
  ],
  "Configuration": {
    "allowEft": true,
    "allowInterac": true,
    "allowVisaDirect": true,
    "successURL": "https://success-url-example",
    "cancelURL": "https://cancel-url-example"
  }
}
```

{% endtab %}

{% tab title="With additional amounts" %}

```json
{
  "ConnectTokenType": "HostedCheckout",
  "Amount": 11.1,
  "ReturnTokenWithoutUrl": true,
  "Items": [
    {
      "Name": "Item to sell",
      "Description": "Description of the item to sell",
      "Price": 10.0
    }
  ],
  "AdditionalAmounts": [
    {
     "Type": "CommonFee",
     "Name": "Fee 1",
     "Description": "Common Fee",
     "Amount": 0.1
    },
    {
      "Type": "TaxRate",
      "Name": "TaxRate 1",
      "Description": "Tax Rate",
      "Amount": 0.1,
      "RateType": "Inclusive"
    }
  ],
  "Configuration": {
    "allowCreditCard": true
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
  {% endhint %}

{% hint style="info" %}
**NOTE**

* By default, the HostedCheckout response includes the URL to the HostedCheckout endpoint. If you only need the token in the response, you can use the `ReturnTokenWithoutUrl` field. This field is applicable only to HostedCheckout.
* The `RateType` field, which is a property of the objects in the `AdditionalAmounts` list, must be provided **only** when the `Type` is set to `"TaxRate"`.
  {% endhint %}

#### Callbacks

{% tabs %}
{% tab title="onSuccess" %}

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

{% endtab %}
{% endtabs %}

### Card Funding Checkout

The Card Funding Checkout feature enables developers to quickly generate a secure, customizable payment page by providing product details like name, amount, and description. Cardholders can complete load 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.

#### Card Funding Checkout using SDK <a href="#hosted-checkout-using-sdk" id="hosted-checkout-using-sdk"></a>

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

{% tabs %}
{% tab title="Mandatory fields" %}

```json
{
  "ConnectTokenType": "CardFundingCheckout",
  "UserId": "772645eb-0ed9-4ff4-b8ac-47b1d115736d"
}
```

{% endtab %}

{% tab title="With additional amounts" %}

```json
{
     "ConnectTokenType": "CardFundingCheckout",
     "UserId": "772645eb-0ed9-4ff4-b8ac-47b1d115736d",
     "AdditionalAmounts": [
          {
               "Type": "PrepaidCardFee",
               "Name": "Card Activation Fee",
               "Description": "To apply the card activation fee",
               "Amount": 10
          }
     ]
     "Configuration": {
          "amount": 20
     }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**NOTE**

* Only `allowEft` is enabled and only `Amount` can be pre-filled.   &#x20;
  {% endhint %}

#### Callbacks

{% tabs %}
{% tab title="onSuccess" %}

```json
{
  "origin": "ZUM_RAILS",
  "userId": "80d53753-a9f7-4b81-93f0-44879ed778af",
  "transactionId": "0795b370-b2c8-431d-899c-3b54d589e8b0",
  "sessionId" : "89d53753b2c8431d899c54f7ec89109f"
}
```

{% endtab %}
{% endtabs %}