Get a card widget

▶ Run in Postman

Overview

This API lets you use NIUM’s card widget to tokenize the beneficiary card details. Customers who don't follow the Payment Card Industry Data Security Standard (PCI DSS) need to integrate with this API to get the recipient’s encrypted card token number.

Card payouts

The card widget is a functionality of the NIUM Payout service, which lets you make payments in many currencies to multiple parties using the VISA card. This functionality also helps you to make payouts in Chinese Yuan (CNY) using the UnionPay cards.

📘

IMPORTANT

This API supports Visa Direct payouts. Visa Direct is available for Asia-Pacific and European Economic Area(EEA) clients only. UnionPay payouts are only available for the destination country China. In case the transaction currency doesn't match the destination card issuer's currency, the payout amount is converted and credited to the currency of the card issuer.

You can use the card widget to make peer-to-peer, business-to-peer, and business-to-business payments.

You need to pass the token number in the field encryptedBeneficiaryCardToken when you add a beneficiary to make a payout to a card. In case you're PCI-DSS compliant, you can directly pass the card number when you add a beneficiary.

Follow these steps to integrate a card widget:

Step 1: Get a card widget URL.

The Get card widget API lets you get a card widget URL. You need to pass the style values to make basic style changes to the widget depending on your page color scheme.

Step 2: Add your widget URL to the client’s page.

Use the retrieved card widget URL from Step 1 and use it as input for src=widgetUrl. You can use an HTML iFrame tag on your page to add your image details.

📘

NOTE:

You can set the height and width of the iFrame tag depending on your page view.

{
  <iframe   
  	src="<Use the response data from Step 1.>"  
  	style="width:100%;height:50vh">
  </iframe>
}

If you don't have Cascade Style Sheets set up in Step 1, then your default widget looks like this image.

Step 3: Add a listener for your message event to get iFrame-validated data.

Once you fill in the card details on the widget, the iFrame triggers a message event to the parent client page. You have to implement a listener to receive that message which contains the encrypted beneficiary card token and other details.

Sample event data on success:

{
  "cardDetailsValid": true, 
  "encryptedBeneficiaryCardToken": "eyJhbGciOiJIUzI1NiJ9.eyJlbmNJIjoiZGhoVlFMWW53MjFPY\u2026DQ3fQ.ektooTLFNeCnZSEF5o9iLFHo-JE62qecryM_Hy5cJcM", 
  "maskedCardNumber": "XXXX XXXX XXXX 4242", 
  "billingCurrencyCode": "PHP"
}

Sample event data on failure:

{
  "cardDetailsValid":false
}

📘

NOTE:

Non-PCI DSS-compliant clients have to use the encrypted beneficiary card token when they add or update a beneficiary for a card payout. The token expires in 30 minutes.