# Integration Guide

## 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.

| 
| Production | https://companion.workloads.production.dailypay.com/v1/widgets/debitcard/tokenizer |
| UAT | https://companion.workloads.uat.dailypay.com/v1/widgets/debitcard/tokenizer |


### Required Query Parameters

The following parameters are required whenever the Component is used:

| Parameter | Notes |
|  --- | --- |
| `client_id` | The client ID used in authorization, supplied by DailyPay |
| `implementation_id` | The ID of this particular application, supplied by DailyPay |


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


```json
{
  "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


```json
{
  "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](/#tag/Accounts/operation/createAccount) 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