Visa Direct + 3D Secure

This is a step by step tutorial on how you can use Zūm Rails to implement 3D Secure into payment collections made with the Visa Direct payment rail.

Prerequisites

The 3D Secure protocol enables a liability shift to the card-issuing bank of the end user. To implement 3D Secure for Visa Direct collections, the following items must first be in place:

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

• Ensure your account has the Visa Direct payment rail enabled. Details of this payment method along with the 3D Secure protocol may be found 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

Create a Visa Cardholding User

To utilize the Visa Direct payment rails, accompanied by 3D Secure, you will first need to add users and their Visa Card data to the Zum Rails system. As this requires the transmitting and storage of sensitive card data, a PCI compliant collection mechanism is required. For this purpose, Zum Rails offers our Connect UI feature to tokenize user card data safely and securely. For details on how to integrate the Connect UI via our SDK please refer to our documentation seen here.

Once the Connect SDK is implemented, to render the AddPaymentProfile modal for creating a Visa card-holding user you may call the Create Token endpoint as described here to generate a token to supply in the call to the Connect SDK.

Endpoint: /api/connect/createtoken
Method: POST

{
     "ConnectTokenType": "AddPaymentProfile",
     "Configuration": {
          "allowEft": false,
          "allowInterac": false,
          "allowVisaDirect": true,
          "allowDebitCard": false,
          "allowCreditCard": false,
          "forceConnectV2": true
     }
}

This will result in the following iframe, within which a user will be guided to add their Visa Direct card details to create their payment profile. Once submitted, the resulting userId will be returned in the onSuccess callback.

4

Call the Zum Rails 3D Secure SDK

For successful 3D Secure transaction creation the Zum Rails 3DSecure SDK must be called to generate the 3D Secure transaction parameters. The steps for this process are outlined here.

Endpoint: /api/connect/createtoken
Method: POST

{
  "ConnectTokenType": "ThreeDS",
  "UserId": "1111c68f-e927-4e93-b55a-bbec31aaa111",
  "Amount": 10.0,
  "Configuration": {
    "TransactionMethod": "VisaDirect"
  }
}

The token generated above is used to call the 3D Secure SDK. If a challenge is required, the SDK will display a popup for the customer to complete the authentication. When the flow is completed, the SDK returns a callback with the following parameters needed to be supplied in the transaction creation request.

{
  "userId": "57c7c68f-e927-4e93-b55a-bbec31aaa632",
  "cardEci": "05",
  "cardDsTransId": "d65e93c3-35ab-41ba-b307-767bfc19eae3",
  "cardAuthenticationValue": "9ec1JHwF5eWa8/j/hlS5DjHZBsY=",
  "origin": "ZUM_RAILS"
}

5

Create a Visa Direct Accounts Receivable Transaction

Call the Create Transaction API as described here, specifying Visa Direct as the Transaction Method and AccountsReceivable as the ZumRailsType. Ensure the same amount and userId specified in the 3D Secure SDK call are used in this request. Append the 3D Secure parameters generated in the previous step to the request payload and send:

• cardEci

• cardDsTransId

• cardAuthenticationValue

Endpoint: /api/transaction
Method: POST

{
  "ZumRailsType": "AccountsReceivable",
  "TransactionMethod": "VisaDirect",
  "Amount": 10.0,
  "Memo": "Memo description",
  "Comment": "This transaction is just a test from a user to wallet",
  "UserId": "1111c68f-e927-4e93-b55a-bbec31aaa111",
  "WalletId": "8ebd932b-...b92633e14297",
  "cardEci": "05",
  "cardDsTransId": "d65e93c3-35ab-41ba-b307-767bfc19eae3",
  "cardAuthenticationValue": "9ec1JHwF5eWa8/j/hlS5DjHZBsY="
}

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