About Consumer Verification

Mazooma’s verification service uses online bank verification (OBV) tokens to identify and link Consumers with their bank accounts. After initially verifying a Consumer and retrieving an associated OBV token, the token can be used in subsequent transactions to link the Consumer with their bank account.

Authentication


The verification service requires a bearer token from the authentication server. This bearer token is then included in the header of the verification request.

POST https://sandbox-api.mazooma.com/exp/auth/mint/v1/oauth2/token?grant_type={grant_type}&scope={scope}

Parameter Description
grant_type The grant type is client_credentials.
scope The scope is obv/token-request.

Authentication request

curl --location --request POST 'https://sandbox-api.mazooma.com/exp/auth/mint/v1/oauth2/token?grant_type=client_credentials&scope=obv/token-request' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic NzQ5NG02YWpzZGttcHFrcWExMzNoMXA3NWU6cnFzMTljMWZmcWJ0aDI4ODczMmFiYTg3bnZvNGx1YnNxM202MmU1NmVubHE5ZjRlNzY5' \
--header 'Cookie: XSRF-TOKEN=da21a7f2-059b-447d-82ad-facaedf83cb7'

Authentication response

Parameter Description
access_token The bearer token retrieved from the authorization server.
expires_in The time until the token expires, in seconds.
token_type This is always Bearer.
{
  "access_token": "plJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0GRP3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleTRiOjE5OTU0OTQ2ODYsInNjb3BlIjoib2J2L3Rva2VuLXJlcXVlc3Qgb2J2L2JhbmstYWNjb3VudC1kZXRhaWxzIn0lY1WSIvzyL0D5qDFZ6MsjFl5MPPlSZG9sBiTcmteDUtY",
  "expires_in": 1800,
  "token_type": "Bearer"
}

Verifying and linking Consumer bank accounts


To link and verify a Consumer bank account for the first time, the Merchant system sends a verification request with the required Consumer data to the verification service endpoint. Instant Bank Transfer then sends a response that includes a consumerURL to the Merchant system. The consumerURL is rendered in the Consumer’s browser in a new window or tab.

Instant Bank Transfer performs the bank verification and redirects the Consumer to the returnURL provided by the Merchant. The Merchant receives the result of the verification request at their specified verification notification URL. If the Consumer verification is successful, the notification includes an OBV account token (accountToken) and bank account information - accountLabel, fiName, and fiAccountType - that you can use to display the account on your cashier. If the verification is unsuccessful, the notification includes the relevant error code and error message.

Although the verification request includes transaction details, no transaction is initiated as part of the verification. The only action taken as a result of the verification request is to verify and link the account with the Consumer.

After receiving a successful response, the Merchant system includes the token in the transaction request and completes the transaction.

For more information about transaction requests, see About interactive payins and About Direct Payouts.

Consumer verfication requests

Headers

Calls to the Consumer verification endpoint require the following headers:

  • Authorization: Bearer token
  • Content-Type: application/json

The bearer token is obtained via the authentication endpoint. See Authentication.

Request

To initiate verification, send an HTTP POST request to:

https://sandbox-api.mazooma.com/exp/ext/mint/ooes/v1/obv

object
accountToken
string

Account token for reauthorization.

1 validation
consumer
object
required
countryCode
string

The 2-digit country code. This must be US

1 validation + required
merchant
object
required
transaction
object
required

Consumer verification response

The response to a successful request is the consumerURL, which opens in a new window or tab in the Consumer’s browser.

{
  "consumerUrl": "https://pay-pd-mint.enfin.ca/bank-select?code=dfb5b727-03d6-43c7-8faf-48d31974e264&merchant-return-url=http%3A%2F%2Fsmplmerchant.com%dFreturn-url"
}

Notification

After verifying and linking a Consumer account, a notification is sent to the Merchant’s verification notification URL. If the verification is successful, the notification includes a token that links the Consumer and bank account. The token is then passed to Mazooma in the accountToken field in subsequent transaction requests.

For more information about transactions, see Instant Bank Transfer transaction API.

object
verificationStatus
string

The verification status.

2 validations
merchant
object
transaction
object
account
object