Integration Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Architecture Overview

The DailyPay Debit Card Tokenization Component is a secure, embeddable web form designed for seamless integration into mobile and web applications. It is intended to be loaded in a WebView (React Native, iOS, Android) or iframe, and communicates with the host application using the postMessage API. The component handles all user input, validation, and securely transmits card data to a DailyPay backend service, which performs the actual tokenization with the payment gateway. Only the resulting token and non-sensitive metadata are returned to the host. No sensitive card data is ever exposed to or stored by the host application.

Component Flow

1. Embedding: The host app loads the component in a WebView or iframe, passing the DailyPay backend tokenization API URL as a parameter.
2. User Input: The user enters their debit card and address details into the form. All validation and formatting is handled client-side.
3. Tokenization: On submit, the component sends the card data via a secure API call to a DailyPay backend service. The backend service performs the actual tokenization with the payment gateway and returns a token to the component.
4. Result Messaging: On success or failure, the component sends a DAILYPAY_CARD_TOKENIZE_RESPONSE message to the host via postMessage, containing either the token and metadata or error details.
5. Host Handling: The host listens for this message and processes the token as needed (e.g., for account linking or payment setup).

Component Boundaries

• Frontend (this component): Handles all UI, validation, formatting, and secure transmission of card data to the DailyPay backend. Communicates only via postMessage with the host, and via HTTPS with the backend.
• DailyPay Backend Service: Receives card data from the component, performs tokenization with the payment gateway, and returns only the token and non-sensitive metadata to the component.
• Host App: Responsible for embedding the component, listening for messages, and handling the tokenized result. Never processes or stores raw card data.

Basic Integration Steps

1. Import required dependencies
2. Set up the WebView with the tokenization component URL
3. Implement the message handler
4. Process the tokenized card data

URL

The Tokenization Component is hosted at the following URLs. Use the appropriate URL for your environment.

Required Query Parameters

The following parameters are required whenever the Component is used:

For example: https://companion.workloads.production.dailypay.com/v1/widgets/debitcard/tokenizer?client_id=123&implementation_id=3213

Response Messages

The widget communicates with your app using the postMessage API:

Successful Tokenization

{
  "type": "DAILYPAY_CARD_TOKENIZE_RESPONSE",
  "response": {
    "first_name": "...",
    // User's first name
    "last_name": "...",
    // User's last name
    "address_line_one": "...",
    // First line of address
    "address_line_two": "...",
    // Second line of address (optional)
    "address_city": "...",
    // City
    "address_state": "...",
    // State (2-letter abbreviation)
    "address_zip_code": "...",
    // ZIP code
    "address_country": "USA",
    // Country (always set to "USA")
    "expiration_month": "...",
    // Card expiration month (MM format)
    "expiration_year": "...",
    // Card expiration year (YY or YYYY format)
    "issuer": "...",
    // First 6 digits of the card number (BIN)
    "token": "..."
    // Tokenized card data from payment gateway
  },
  "success": true
}

Failed Tokenization

{
  "type": "DAILYPAY_CARD_TOKENIZE_RESPONSE",
  "success": false
  // Error details
}

Handling Responses

1. Always check the type property to identify the message
2. Verify the success flag to determine if tokenization succeeded
3. Access tokenized data via the response property
4. For errors, check the error details in the response

Utilizing a Successful Response with the Accounts API

The response object returned with DAILYPAY_CARD_TOKENIZE_RESPONSE may be used directly in the POST request to the accounts endpoint as the value for the details field when the fields "account_type": "CARD", "subtype": "DEBIT" are used. This action will create a transfer account for the user based on the card details submitted to the webview.

Security Best Practices

• Always use HTTPS URLs in production
• Don't store sensitive card information locally
• Implement proper error handling

Troubleshooting

• Enable WebView debugging to see console messages
• Check network connectivity if widget fails to load
• Verify that JavaScript is enabled in the WebView