Wallit Partner Integration Guide

Overview

The Wallit Partner Integration Guide outlines the integration options for accessing partner portals following a product purchase through Wallit. Upon purchase, users can manage their products via a partner portal.

This portal may be hosted by the partner and can be accessed through an embedded IFRAME within the Wallit application or through a separate browser window. Although using an IFRAME generally enhances user experience, certain partner IT policies may restrict this option, necessitating the use of a new window.

Wallit supports two primary authentication methods: SAML2 federated authorization and custom authorization using a JWT token appended to the launch URL.

API Integration

For reporting status back to Wallit, please refer to the Webhook API documentation
https://qa.api.wallit.app/api-docs

Integration Options

1. Partner Product Rendering Options
   • Iframe within Wallit App
   • New browser window
   • Embedded WebView for mobile devices
2. SSO Authorization Options
   • SAML2 identity federation
   • Encrypted JWT in launch URL
   • Custom tokens
3. APIs / SDKs
   • Webhooks for real-time updates
   • Mobile SDKs for seamless integration in mobile applications
   • Custom Solutions for unique partner requirements

SAML2 Integration

To configure the partner's federated identity service provider (SP), Wallit will use the following IdP endpoints:

Partners must provide Wallit with specific information to initiate the SAML2 authorization and subsequent login and product launch. Wallit employs IdP-initiated SAML2, meaning the first interaction with the partner’s SP is a SAML2 Response.

Required Parameters

JWT Integration

Another method to launch a partner portal for a specific user is for Wallit to use a base URL provided by the partner to Wallit and then when the user wishes to go to the portal, they tap on a button that takes them there. Wallit appends a query parameter that specifies a JWT that passes information of your choice to identify the user. Typically, partners provide that information as part of what is returned with the enrollment API call. We adhere to the IETF RFC-7519 JWT standard:
https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6

We recommend partners add data to the return data from the call to the partner’s enrollment API, and Wallit will retain that info and use it when launching the portal with a URL similar to:
https://myvendor.portal.com?token=a5d4c65adc4ad56c6ca465d45a6dc56a4c

Our JWT has a creation and expiration date in the payload using the iat and exp fields specified in the IETF RFC-7519 standard for JWTs. We provide the partner with UAT and Production keys so that they can verify the signature on the JWT.

Example JWT

Header:

{
  "typ": "JWT",
  "alg": "HS256"
}
}

Payload:

{
  "iat": 2352543543523,
  "exp": 32452353455,
  "wallit": {
    "user": {
      "id": "12342-12412342-435334656-4566"
    }
  },
  "vendor": {
    "vendor_field_1": "xxx"
  }
}

Signature and Encryption

We use the standard JOSE encryption and signature methods as defined in RFC 7516: JSON Web Encryption (JWE): RFC 7516.
https://datatracker.ietf.org/doc/html/rfc7516

This requires the public key to be used on the encryption (Wallit) side and the private key on the decryption (partner) side.

Node.js Implementation Example:

Here is node.js code that implements the encrypt and decrypt:

         const jose = require('jose'); 
         const crypto = require('crypto'); 
         exports.encryptJWT = (payload) => { 
             const publicKey = crypto.createPublicKey({ 
                 key: fs.readFileSync(__dirname + '/federallife.public.key'), 
                 format: 'pem', 
                 type: 'pkcs1' 
             }); 
             return new jose.CompactEncrypt(new TextEncoder().encode(JSON.stringify(payload))) 
                 .setProtectedHeader({ 
                     alg: 'RSA-OAEP', 
                     enc: 'A256GCM' 
                 }) 
             .encrypt(publicKey); 
         } 
         exports.decryptJWT = (payload) => { 
             const privateKey = crypto.createPrivateKey({ 
                 key: fs.readFileSync(__dirname + '/federallife.private.key'), 
                 format: 'pem', 
                 type: 'pkcs1' 
             }); 
             return jose.compactDecrypt(payload, privateKey); 
         } 
    

Example Keys and JWT

Test keys are provided below for demonstration purposes.

Public Key:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxCcA4ik9TnhXGzIAMlb7
Xze4w2FC1/2d+hm4umKZQXrZzWFm6BuDsPklmJEf9+GYSdF6pGUldc1WYF0x0LxA
ryVWJJ0c1N1xnxOeydaVNLEzLIEJaCw4oa8tdhS4l744I0NDM5XWPX5OFa7wbN6v
QI9I/W2vIJGtTOSshC9X6XbwRv24lfumuiB6PSalTUnOgCW7XleluLtG+WAfv/83
ssJdsKhVXv3Z6DK3aCzq8M6qKqpyMkPi9zCPy2+NlQkiH7RfwHdzumF2JJM/b5Vq
sJMhadwh9lXhkaNtPEEQNU8FDtifsnNgzybAOJ6AYL89hPKtYXrXdHhnxuonLB7k
UwIDAQAB
-----END PUBLIC KEY-----

RSA Private Key:

[Demonstration private key omitted. Generate your own disposable test key; never use published example keys for authentication.]

Example Cleartext and Encrypted JWT:

Cleartext:

{"preferred_username":"wallit_01239128731023123","exp":"2024-09-24T13:47:18.772Z"}

Encrypted JWT:

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.ncsOuxZ5GVP3wpZvHd0vuAm857XYzYq341HCLzQnCo5zjNfydT0M_xfS21-9Rq_ak5CkqtsrdoueSE0y59wC8bX3PatPNdPH6zmjsXRdly4AP9Q6QBCcvZtPID_Ou20CTqw23mevA_YbINEJSub821v1xevJGw11HGJuPJogRZOXPEq5oMS9C5R5RnJXd23nS7A-E7rGoyoTW17Q9F0X4Wej8zZHUGQjrAB6PgEezXcsiZu61QhpSDKlbuJfjWCRWFTrFqjpSncZ9OMavn0lUdTotD5zNrW1dRdacuHL8kF3s5zhogTUdiaxEKiXuHZLV0U_J5SnNd5XLPtm22IKTw.ysgiOnHObLGZ3gFN.aZ5twgcRmfFK5OP08mJuC6k5hyCfBpkJhfnBB50WRPQvSkmpR8l_RE6wQmxg8M9_7ySxNS7WNWLqJEBCoxQfiJTNB1OilXIHSXoxbRDvVA7_yg.76Clqd14oDHXisqwUAc4-A

Contact Information

If you have any questions, please reach out to our support team.

Wallit Inc.

7643 Haddington Cove

Lakewood Ranch FL 34202

Email: info@wallit.app

Web: www.wallit.app

Help: help.wallit.app