Overview

To enable an intstant payment (PULL/PUSH) with an external card-on-file, the following steps are required:

1. Tokenize card
2. Add card-on-file using card token
3. For PULL payments, enable 3-D Secure (3DS) authentication
4. Initiate external card-on-file payment

Tokenize card

To enable customers to add card-on-file, you first need to tokenize the card through integration with the TabaPay Cards Tokenization widget. The widget allows for direct communication between the client, TabaPay, and Synctera, eliminating the need for the integrator to have PCI certification. This integration is described step-by-step below.

Getting started

Before integrating with TabaPay Card PCI-Compliant iFrame, ensure that you have all the necessary components in place:

1. Ensure Synctera API keys are provisioned and working for your business;
2. Ensure external cards have been enabled for your program with your Synctera implementation and onboarding contact;
3. If integrating in a mobile application, you may need to use a web view such as a WKWebView in a iOS application, WebView in an android application, or a WebView in React Native;
4. Content security policies should be set in the application using the following directives:

{
  "connect-src": [
    'https://sso.tabapay.com',
    'https://sso.sandbox.tabapay.com:8443'
  ],
  "frame-src": [
    'https://sso.tabapay.com',
    'https://sso.sandbox.tabapay.com:8443'
  ]
}

Display iFrame and tokenize an External Card

The steps below describe how to display TabaPay PCI-Compliant iFrame:

1. Add an iFrame tag to the desired webpage:

<div><iframe id="sso"></iframe></div>

2. Set the iFrame source for the appropriate environment:

• prod: "https://sso.tabapay.com/SSOSynctera.html"
• sandbox: "https://sso.sandbox.tabapay.com:8443/SSOSynctera.html"

<script>
  document.getElementById( "sso" ).src = "https://sso.sandbox.tabapay.com:8443/SSOSynctera.html";
</script>

3. Add an event listener and handler for TabaPay events:

<script>
  function pfReceivedMessage( event )
  {
    if ( event.data != "Close" )
    {
      if ( event.data.slice( 0, 7 ) == "Error: " )
      {
        // Error
      }
      else
      {
        var asData = event.data.split( "|" );
        if ( asData.length == 4 )
        {
          // asData[ 0 ] contains the Cardholder Name
          // asData[ 1 ] contains the Last 4
          // asData[ 2 ] contains the Expiration Date in YYYYMM Format
          // asData[ 3 ] contains the Card Token
        }
        else
        {
          // Data Error
        }
      }
    }
    else
    {
      // Close or Cancel
    }
  }
  window.addEventListener( "message", pfReceivedMessage, false);
</script>

Upon completing the preceding steps, the widget should be ready to display and capable of tokenizing External Cards.

💡

For more information on card tokenization using TabaPay PCI-Compliant iFrame, refer to the TabaPay documentation.

Customization Options

The TabaPay Browser SDK provides a number of customization options for controlling the layout and appearance of the TabaPay Card PCI-Compliant iFrame. See TabaPay Browser SDK for additional details and specific customization options.

Add card-on-file using card token

Once the card has been tokenized, use the token and cardholder name to create an External Card by calling POST /v1/external_cards/tokens - customer_id must also be provided and business_id may optionally be provided if applicable.

📘

The token will expire after 5 minutes, so ensure External Card creation is performed shortly after card tokenization.

Verifications:

When an External Card is created, the following verifications are performed:

• CVV2 verification:
  • CVV2 provided in the iFrame is validated against the CVV2 on file with the issuer
• Address verification:
  • Address stored on the customer's record on Synctera is validated against the address on file with the issuer
  • Note that if business_id is provided, address verification is performed on the Business's legal address, otherwise, it is performed on the Person's legal address. However, cardholder name matching is performed on the Person's name regardless.
• Name verification:
  • Name provided in the iFrame is validated against the name on file with the issuer

Example request:

curl \
  $baseurl/v0/external_cards/tokens \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  -d '
  {
    "token": "{TOKEN}"
    "name": "Jane Taylor",
    "customer_id": "{CUSTOMER_ID}"
  }'

Example response:

{
  "created_time": "2023-01-18T12:03:46.892809-05:00",
  "currency": "USD",
  "customer_id": "{CUSTOMER_ID}",
  "expiration_month": "4",
  "expiration_year": "2026",
  "id": "{EXTERNAL_CARD_ID}",
  "last_four": "0004",
  "last_modified_time": "2023-01-18T12:03:46.892809-05:00",
  "name": "Jane Taylor",
  "verifications": {
    "address_verification_result": "VERIFIED",
    "cvv2_result": "VERIFIED",
    "pull_enabled": true,
    "push_enabled": true,
    "state": "SUCCEEDED"
  }
}

In addition to CVV2, address and name verification results, the verifications object contains information about the card, as well as the type of transactions the card supports. If either pull_enabled or push_enabled are false, that type of transaction may not be performed using the card.

Enable 3DS and create payment

Once a card has been added on file, a PULL or a PUSH payment can be initiated with the card. For PULL payments, 3-D Secure (3DS) authentication is required. For details on how to enable 3DS, and how to iniate a payment with a card-on-file, see the Instant Payments - Card-On-File section.