Acquiring SDK

This SDK is designed to securely collect sensitive information such as card numbers and CVV on the frontend. It generates a Transient Token and supports the 3D Secure (3DS) authentication process.

1. Overview

1.1 Core Capabilities

• Secure Payment Form: Card numbers and CVV are embedded via iframes, ensuring sensitive data never passes through the merchant's page.

• Transient Token: Converts card information into a one-time use token for backend payment initiation.

• 3DS Authentication: Supports the 3DS 2.0 flow, handling both frictionless and challenge scenarios.

• DDC Optimization: Supports early Device Data Collection (DDC) to reduce payment wait times.

2. Integration Flow

The integration follows a four-phase process:

1. SDK Initialization Phase: Import the script, instantiate the PaymentForm, call .init(), and render the Microform iframes.

2. Info Collection & Tokenization: The customer enters card info; the frontend calls .submit() to receive a Transient Token.

3. 3DS Authentication Flow: Call .authenticate().

   • Frictionless Flow: Direct success status is returned.

   • Challenge Flow: A popup window appears for OTP/Verification; the result is returned after the issuing bank verifies the info.

4. Final Settlement: Retrieve the authentication result and send data to the merchant backend for final capture.

3. Quick Start

3.1 Import the SDK

Currently, only the Sandbox environment is available for integration testing. Use a <script> tag as no NPM package is provided.

<script src="https://asset.sandbox.build.app/payment-form/payment-form.js"></script>

Upon loading, the PaymentForm class is attached to the global window object.

3.2 Prepare HTML Containers

Create containers for the card number, CVV, and expiration date.

<form id="paymentForm">
  <div class="form-group">
    <label>Card Number</label>
    <div id="cardNumber" class="field-container"></div>
  </div>
  
  <div class="form-group">
    <label>CVV</label>
    <div id="cvv" class="field-container"></div>
  </div>

  <div class="form-group">
    <label>Expiration Date</label>
    <div style="display: flex; gap: 10px;">
      <select id="expMonth">
        <option value="01">01</option>
        </select>
      <select id="expYear">
        </select>
    </div>
  </div>
  <button type="submit" id="submitBtn">Pay</button>
</form>

3.3 Initialize the SDK

Instantiate the form and call init().

const paymentForm = new PaymentForm({
  env: 'sandbox',
  captureContextParams: {
    merchant_id: "YOUR_MERCHANT_ID",
    hosted_origin: [window.location.origin],
    card_networks: ['VISA', 'MASTERCARD', 'AMEX'],
    reference_id: crypto.randomUUID(),
    billing_info: {
      address: {
        country_code: 'AU',
        state: 'NSW',
        city: 'Sydney',
        address_line1: 'Level 29',
        postal_code: '2000'
      },
      first_name: 'John',
      last_name: 'Doe',
      email: 'test@example.com'
    }
  },
  selectors: {
    cardNumber: '#cardNumber',
    securityCode: '#cvv'
  },
  onError: (err) => console.error('Error:', err),
  onSuccess: (token) => console.log('Token generated:', token)
});

await paymentForm.init();

4. API Reference

4.1 PaymentFormConfig

*Either context or captureContextParams must be provided.

4.2 Methods

• init(): Promise<void>: Initializes the SDK and loads security iframes.

• submit(expMonth, expYear): Promise<string>: Submits encrypted info to get a Transient Token.

• authenticate(token, urls): Promise<AuthResult>: Performs 3DS authentication.

• prepare(token): Promise<void>: Advanced. Triggers DDC early to optimize performance.

5. Sandbox Test Data

Use these credentials for testing in the sandbox environment:

• CVV: Any 3 digits.
• Expiry: Any future date.

6. FAQ

• Q: Why do I see "No capture context provided" during init?

• A: Check if context or captureContextParams is in your config. Ensure merchant_id is correct.

• Q: Why is there no response after a 3DS challenge?

• A: Ensure billing_info is complete and returnUrlOrigin matches window.location.origin.

• Q: How do I style the input fields?

• A: Use the fieldConfig parameter or apply CSS directly to the .field-container.