Interactive payin requests

Authentication

In an interactive payin, the Merchant system must have OAuth 2.0 credentials, which include Client ID, Client Secret, and App ID. Passing these credentials to the Mazooma authentication server allows you to create and obtain an access token. For more information, see Merchant credentials.

The Merchant system must call the Mazooma authentication API and obtain an access token before redirecting the Consumer to Mazooma. Access tokens are retrieved via the OAuth Client Credentials flow, which is used for server-to-server authentication. For more information, see Getting an access token.

Redirect options

Interactive payins can be implemented in the same window or embedded in an iFrame on the Merchant’s site. We recommend that you implement the payment system in an iFrame. This provides a seamless experience for Consumers, giving the impression that they’re remaining on the Merchant’s site throughout the transaction.

All Instant Bank Transfer screens use responsive design and automatically adjust to the optimal size for the Consumer’s device.

When the Consumer is redirected to Mazooma, Instant Bank Transfer guides the Consumer through the payment flow. At the end of the payment, Instant Bank Transfer redirects the Consumer to the Merchant’s specified, URL-encoded return URL, which is specified in the request (returnUrl).

Registering a new bank account

The payin transaction for a first-time Consumer, or a returning Consumer registering a new bank account, is a non-tokenized payin. That is, the Merchant system does not yet have a token that uniquely identifies this Consumer’s bank account in the Instant Bank Transfer system.

In this case, the Merchant system sends a payin request that doesn’t include the Bank object in the interactive payin request. See interactive payin request examples.

At the end of the payin process, the Merchant receives four data parameters in the payment notification. The Merchant stores these parameters for subsequent payins and payouts made by the same Consumer using the same bank account.

  • accountToken – A token that uniquely identifies the Consumer’s bank account in the Mazooma system.
  • accountLabel – The masked account number that will be displayed by the Merchant to the Consumer in subsequent transactions. This is in the format ***1234.
  • bankAccountType– The Consumer’s bank account type, either PC or PS (personal checking or personal savings).
  • fiName – The name of the Consumer’s bank.

Using a previously registered bank account

A payin transaction for a returning Consumer using a previously registered bank account is a tokenized payin. On the cashier page, the Merchant displays the stored account labels (accountLabel), account type (bankAccountType), and bank name (fiName) associated with the account token (accountToken) from the Consumer’s most recent payin transaction notifications.

To improve the Consumer’s user experience, the Merchant can allow them to select the previously used account, or to add a new account, before being redirected to Mazooma for payment. We recommend displaying the last three (3) unique tokens per Consumer on the cashier and allowing the Consumer to remove the tokens from being displayed on the cashier. If the Consumer uses more than 3 unique tokens, the older tokens should not be automatically displayed.

The Merchant cashier also displays an option for the Consumer to make a payin using a new bank account that hasn’t been previously used for Instant Bank Transfer payins.

  • If the Consumer chooses a bank account that they previously used to make a payin, the Merchant sends a payin request with the associated accountToken in the redirect.
  • If the Consumer wants to use a different bank account, the Merchant sends a payin redirect without a token, following the same process as a first-time Consumer payin.

The accountToken, bankAccountType, fiName, and acccountLabel are passed back for each transaction, regardless of whether the payin request contained a token.