---
title: Integrating with PerksWallet
slug: integrating-with-perkswallet
icon: 🔧
docTags: 
createdAt: 2025-04-03T12:05:23.940Z
---

:::hint{type="info"}
**Who is this for:** Developers who want to embed PerksWallet directly within their own app or website with full control over the user experience.

**Outcome:** Integrate Embedded PerksWallet via API or JavaScript SDK, enabling users to save and access offers within the publisher's own interface using a `pub_user_id`.
:::

# Overview

This guide covers the **Embedded PerksWallet** integration, for partners who want full control over the wallet experience within their own app or website.

This document provides a detailed walkthrough for integrating PerksWallet into your product using our APIs or JavaScript SDKs.

:::hint{type="info"}
**Looking for a simpler option?** If you prefer a zero-code solution, see [Integrating with Hosted PerksWallet](docId:0zfIUnAhNWI7qljCQQ052) instead. With Hosted PerksWallet, MomentScience manages everything, no integration required.
:::

## Prerequisites

Before you begin, ensure the following:

1. PerksWallet must be enabled for your account. Contact your MomentScience account manager to activate it.
2. You need an API Key with access to "PerksWallet." Refer to [API Key Documentation](https://docs.momentscience.com/getting-your-api-key#St6qx) to learn how to obtain one.

## Understanding pub\_user\_id

The `pub_user_id` is a unique, non-PII identifier for each user. It plays a critical role in linking offers to individual users.

- Ensure the `pub_user_id`remains consistent across sessions and devices.
- Do not use personally identifiable information (PII) such as email addresses or phone numbers.
- You can generate this identifier using any logic, as long as it’s unique for each user.

:::hint{type="success"}
The `pub_user_id`is a **required field** in all requests and is essential for saving and retrieving offers.
:::

***

# Embedded Integrating  Methods

You can integrate PerksWallet into your product using one of the following methods: 

- Perkswall API
- Moments API
- Moments JS SDK
- Perkswall SDK

The core requirement for all integrations is providing a `pub_user_id`, a stable user identifier that allows offers to be saved and retrieved across sessions and devices.

## Integration via API

When integrating with **Perkswall API** or **Moments API**, the process is the same. The key step is ensuring the `pub_user_id`is included in the request body for both saving and retrieving offers.

### Try It Out 

**Moments API**

:::Iframe{iframeHeight="0" code="<iframe src=&#x22;https://hopp.sh/e/G3RrLqRXm6Qz&#x22; title=&#x22;Hoppscotch Embed&#x22; style=&#x22;width: 100%; height: 480px; border-radius: 4px; border: 1px solid rgba(0, 0, 0, 0.1);&#x22;></iframe>"}

:::

**Perkswall API**

:::Iframe{iframeHeight="0" code="<iframe src=&#x22;https://hopp.sh/e/VnNgPL864j75&#x22; title=&#x22;Hoppscotch Embed&#x22; style=&#x22;width: 100%; height: 480px; border-radius: 4px; border: 1px solid rgba(0, 0, 0, 0.1);&#x22;></iframe>"}

:::

## Integration via JavaScript SDK

### Moments&#x20;

1. Add the following script before the closing `</head>` tag

:::CodeblockTabs{indent="3"}
```javascript
<script type="module">
    (function (window) {
        // Configure Moments with your account settings
        window.AdpxConfig = {
            accountId: 'fbe6000000f803ef4', // Replace with your unique account ID
            autoShow: true // Automatically show the Moments widget when loaded
        };

        // Define the user object using a stable pub_user_id
        window.AdpxUser = {
            pub_user_id: 'user-123' // Replace with your unique user ID
        };

    })(window.self !== window.top ? window.top : window);

    (async function (window) {
        const target = window.document.head || window.document.body;
        const script = window.document.createElement('script');
        script.type = 'text/javascript';
        script.src = 'https://cdn.pubtailer.com/launcher.min.js';
        script.importance = 'high';
        script.crossOrigin = 'anonymous';
        script.async = true;
        script.id = 'adpx-launcher';
        target.appendChild(script);
        await new Promise(function (resolve) {
            window.Adpx
                ? resolve()
                : window.document
                    .getElementById('adpx-launcher')
                    .addEventListener('load', function () { resolve(); });
        });
        window.Adpx.init(AdpxConfig);
    })(window.self !== window.top ? window.top : window);
</script>
```
:::

### Perkswall

1. Add the container where the widget will be rendered:

:::CodeblockTabs{indent="3"}
```javascript
<div id="adpx_container"></div>
```
:::

2. Add the following script before the closing `</body>` tag

:::CodeblockTabs{indent="3"}
```javascript
<script>
  window.AdpxConfig = {
    accountId: "fbe6000000f803ef4", // Replace with your account ID
    themeId: "Standard-Theme",     // Replace with your theme ID
    containerId: "adpx_container"
  };

  window.AdpxUser = {
    // Include user info here
    pub_user_id: "user-123",     // Replace with your unique user ID
  };

  const adpx = document.createElement('script');
  adpx.type = 'text/javascript';
  adpx.async = true;
  adpx.src = 'https://cdn.adspostx.com/launcher.perkswall.js';
  document.getElementsByTagName('head')[0].appendChild(adpx);
</script>

```
:::

***

## Saving an Offer

When a user wants to save an offer for later, they can click the "Save for Later" CTA within the PerksWallet experience.

### Saving via API

To save offers via the Moments API or Perkswall API, follow these steps:

1. Include the `pub_user_id`in the API request body.
2. Extract `save_for_later_url`from the API response (`offers[].save_for_later_url`).
3. On CTA click, make a POST request to `save_for_later_url`.

Once the POST request is made, the offer is saved to the user’s wallet and can be retrieved later using the same `pub_user_id`.

:::hint{type="danger"}
If `pub_user_id`is missing in the request body, `save_for_later_url `will be null.
:::

### Saving via JavaScript SDK

If you are using the SDK, the saving process is **automatically handled**.

- The SDK automatically saves the offer when a user clicks the "Save for Later" button within a PerksWallet experience.
- The saved offer is linked to the `pub_user_id`you provided during integration.

***

## Retrieving User's Wallet

To fetch offers saved by a user, use the following API endpoint. This applies whether you're integrating via the Moments API or Perkswall API.

### &#x20;Using the API

- **HTTP Method:** GET
- **Endpoint:&#x20;**[`https://api.perkswallet.com/api/publisher/user/{{pub_user_id}}/saved/campaigns.json`](https://api.perkswallet.com/api/publisher/user/%7B%7Bpub_user_id%7D%7D/saved/campaigns.json)

**Path Parameters:**

| **Parameter** | **Type** | **Description**                                                       |
| ------------- | -------- | --------------------------------------------------------------------- |
| `pub_user_id` | String   | The unique identifier of the user whose wallet you want to retrieve.  |

**Header Parameter**

| **Parameter**   | **Type&#x20;** | **Description**                                                                                    |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `pwaas-api-key` | String         | API key with access permission to PerksWallet. Required to authenticate and authorize the request. |

**Response Parameters**

| **Parameter**                       | **Type**    | **Description**                                                                            |
| ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `data`                              | array       | List of saved offers for the user. If no offers are saved, this will be an empty array.    |
| `data[].id`                         | integer     | Unique ID of the saved offer.                                                              |
| `data[].user_id`                    | string      | Unique identifier for the user who saved the offer.                                        |
| `data[].campaign_id`                | string      | ID of the campaign associated with the offer.                                              |
| `data[].publisher_id`               | string      | The partner'sID from which the user saved the offer                                        |
| `data[].session_id`                 | string      | Unique session identifier when the offer was saved.                                        |
| `data[].converted_at`               | string/null | Timestamp of when the offer was claimed (if applicable). Returns `null`if not yet claimed. |
| `data[].created_at`                 | string      | Timestamp of when the offer was saved, in ISO 8601 format (YYYY-MM-DDTHH\:MM\:SSZ).        |
| `data[].updated_at`                 | string      | Timestamp of the last update to the saved offer record.                                    |
| `data[].campaign`                   | object      | Details of the campaign associated with the saved offer.                                   |
| `data[].campaign.id`                | integer     | Unique campaign ID.                                                                        |
| `data[].campaign.advertiser_name`   | string      | Name of the advertiser providing the offer.                                                |
| `data[].campaign.description`       | string      | Full description of the offer.                                                             |
| `data[].campaign.short_description` | string      | Shorter version of the offer description.                                                  |
| `data[].campaign.headline`          | string      | Primary offer headline.                                                                    |
| `data[].campaign.short_headline`    | string      | A more concise version of the headline.                                                    |
| `data[].campaign.positive_cta`      | string      | Call-to-action text for the offer (e.g., "Start My Free Trial").                           |
| `data[].campaign.primary_creative`  | string      | URL to the primary creative (image) of the offer.                                          |
| `data[].campaign.is_active`         | boolean     | Indicates whether the offer is still active (true or false).                               |
| `data[].click_url`                  | string      | URL to claim the offer.                                                                    |

:::CodeblockTabs
Example Response

```json
{
  "data": [
    {
      "id": 1000,
      "user_id": "200",
      "campaign_id": "100",
      "publisher_id": "2222",
      "session_id": "a21cec...",
      "converted_at": null,
      "created_at": "2025-04-03T10:47:27.404+00:00",
      "updated_at": "2025-04-03T10:47:27.404+00:00",
      "campaign": {
        "id": 100,
        "advertiser_name": "Ancestry",
        "description": "...",
        "short_description": "...",
        "headline": "Discover Your Roots - Free Ancestry Trial!",
        "short_headline": "Discover Your Roots - Free Trial!",
        "positive_cta": "Start My Free Trial",
        "mini_text": "<p><br></p>",
        "primary_creative": "https://...",
        "is_active": true,
        "last_sync_at": "2025-02-07T05:03:17.049Z",
        "created_at": "2025-02-07T05:03:17.049+00:00",
        "updated_at": "2025-02-07T05:03:17.049+00:00"
      },
      "click_url": "https://trk.pubtailer.com/sdk/offer-click?o_id=4460&c_id=1753&sess_id=a21cec89008306ec70d4315f6d55a045ae8761fc&p_id=3065"
    }
  ]
}
```
:::

### Showing User's Wallet with SDK

Add this container element where you want the Saved Offers widget to appear&#x20;

1. Add this container element where you want the Saved Offers widget to appear

:::CodeblockTabs{indent="3"}
```javascript
<div id="adpx_container"></div>
```
:::

2. Add the following script before the closing `</body>`tag&#x20;

:::CodeblockTabs{indent="3"}
```javascript
<script>
  window.PwaasConfig = {
    accountId: "fbe6000000f803ef4", // Replace with your account ID
    pub_user_id: "user-123", // Replace with your user's unique ID
    themeId: "Standard-Theme", // Optional: use your own theme if available
    containerId: "adpx_container"
  };

  const adpx = document.createElement('script');
  adpx.type = 'text/javascript';
  adpx.async = true;
  adpx.src = 'https://cdn.adspostx.com/launcher.pwaas.js';
  document.getElementsByTagName('head')[0].appendChild(adpx);
</script>

```
:::

***

## Deleting Saved Offers

### Using the API

To delete a saved offer, use the following API request:

- **HTTP Method:&#x20;**&#x44;ELETE
- **Endpoint: &#x20;**[`https://api.perkswallet.com/api/publisher/user/{{pub_user_id}}/saved/campaign/{{campaign_id}}.json`](https://api.perkswallet.com/api/publisher/user/\{\{pub_user_id}}/saved/campaign/\{\{campaign_id}}.json)

**Path Parameters:**

| **Parameter** | **Type** | **Description**                                        |
| ------------- | -------- | ------------------------------------------------------ |
| `pub_user_id` | String   | The unique identifier of the user requesting deletion. |
| `campaign_id` | String   | The ID of the offer the user wants to remove.          |

**Header Parameter**

| **Parameter**   | **Type&#x20;** | **Description**                                                                                    |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `pwaas-api-key` | String         | API key with access permission to PerksWallet. Required to authenticate and authorize the request. |

If the request is successful, the API will return a confirmation message indicating the offer has been deleted.

### Using SDK

If you are implementing using the SDK, deletion is handled automatically.

- The user will see a delete icon next to each saved offer.
- Upon clicking the icon, a confirmation message will appear.
- If the user confirms, the offer will be deleted from their saved list.

***

📢 If you're running into any issues while going through the integration process, feel free to contact us at [help@momentscience.com](mailto\:help@momentscience.com)