Loan disbursement

This is a step by step tutorial on how you can use Zūm Rails to disburse a new loan payment

Prerequisites

To disburse funds for a new loan, you need to decide which payment method you will use. Each payment method requires different information and has its own particularities in speed, pricing, and KYC requirements.

1

Prerequisite

• Make sure you have a sandbox account for testing and read the developer quickstart as described here

• Get the api username and password in the sandbox portal as described here

• Get your funding source id. You can find this information in your portal under settings/funding source page or via API, as described here

• Get your wallet id. You can find this information in your portal under the wallet page or via API, as described here

• Decide which payment method you would want to use to disburse the loan. Each payment method has its own pros and cons, as described here

2

Authenticate with Zūm APIs

Authenticate with the Zūm Rails API as indicated below, or view more details here

Endpoint: /api/authenticate
Method: POST

{
  "Username": "abc...123",
  "Password": "xyz...321"
}

3

Fund Zūm Wallet

To disburse loans, funds must first be deposited into the Zūm Rails platform. A good idea is to fund the Zūm Wallet at the beginning of the week and then use these funds to issue new loans throughout the week.

Create a transaction to fund the wallet from your funding source. A funding source is your operating bank account from your business with your bank. Make sure you inform the FundingSourceId and the WalletId in the payload, as well as the amount that will be enought to the loans you plan to issue.

If needed, you can check the Zūm Wallet balance before as described here

Endpoint: /api/transaction
Method: POST

{
  "ZumRailsType": "FundWallet",
  "TransactionMethod": "Eft",
  "Amount": 123.45,
  "Memo": "Fund 01",
  "Comment": "Funding Zum Wallet for weekly loan disbursements",
  "FundingSourceId": "<your-funding-source-id>",
  "WalletId": "<your-wallet-id>"
}

4

Create a user - The loan recipient

Create a user, the recipient of the loan. There are different ways to add a new user. API, Zūm Connect (widget), or manually through the portal. More details can be found here.

Depending on the information stored on Zūm Rails, different payment methods will be enabled. For example, if an email is provided, Interac can be enabled; if bank account information is provided, then EFT or ACH can be enabled; if a credit card is provided, then credit card payments can be enabled.

Endpoint: /api/user
Method: POST

Example of creating a user that will enable Interac e-transfer:

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "[email protected]"
}

Example of creating a user that will enable EFT payments:

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "[email protected]",
  "BankAccountInformation": {
    "InstitutionNumber": "123",
    "TransitNumber": "12345",
    "AccountNumber": "1234567"
  }
}

Example of creating a user that will enable Interac and EFT payments via data aggregation:

To add a user via data aggregation, you can use Zūm Rails data aggregation, either standalone as described here or with PAD consent page as described here.

After creating the user, you have to store the Zūm Rails user id, received in the response of the api call.

5

Create transaction - Disburse the loan

Now, to disburse the loan, you can create a transaction like the example below.

Endpoint: /api/transaction
Method: POST

Loan disbursement via Interac e-transfer

{
  "ZumRailsType": "AccountsPayable",
  "TransactionMethod": "Interac",
  "Amount": 123.45,
  "Memo": "Laon 01",
  "Comment": "Issuing a loan via Interac e-transfer to John Smith",
  "UserId": "<the-user-id-from step 4",
  "WalletId": "<your-wallet-id>",
  "InteracHasSecurityQuestionAndAnswer": true,
  "InteracSecurityQuestion": "Your question",
  "InteracSecurityAnswer": "Your answer"
}

Loan disbursement via EFT

{
  "ZumRailsType": "AccountsPayable",
  "TransactionMethod": "Eft",
  "Amount": 123.45,
  "Memo": "Laon 01",
  "Comment": "Issuing a loan via EFT to John Smith",
  "UserId": "<the-user-id-from step 4",
  "WalletId": "<your-wallet-id>"
}

After creating the transaction, you have to store the Zūm Rails transaction id, received in the response of the api call.

6

Receive payment updates

The recommended way to receive payment updates is through webhooks.

You can configure your webhook URL and which events you might want to receive in the Zūm Rails portal, under settings/webhook and api settings.

We recommend setting up the transaction status events, selecting all statuses.

When the transaction status changes, we will post to your webhook URL with the transaction GET payload, as described here