Code Samples

Frontend

First, install components dependency with the package manager of your choice:

pnpm install @maxio-com/self-service

npm install @maxio-com/self-service

yarn add @maxio-com/self-service

Then, initialize componentsFactory in your application code:

let componentsFactory = new Components({
  i18nSettings: {
    loadPath: 'https://staging-static.keen.io/ruc/en/{{ns}}.json',
    language: 'en',
  },
  accessTokenUrl:
      'https://merchant.site/components/auth'
  theme:{
    colors: {colorpalette},
    components: {
      Button: {...ButtonSettings, boxShadow: 'none'}
    },
  }
});

Properties of the Components object include the following.

Property	Description
i18nSettings	The localization settings. The loadPath property specifies the URL where the label translations can be found. Merchants can use localization provided by Maxio, or create their own. The language property simply specifies the language.
accessTokenUrl	The URL of the authentication endpoint. This must be provided by the Merchant for the authenticated users with tokens used to authenticate Maxio customers against the components' backend.
apiUrl	The URL of the Embeddable Components backend, which by default is https://selfservice.maxio.com/api/.
onAuthenticationRequest	This is used for customizing authentication request to the Merchant's backend by, for example, providing a custom authentication header.
theme	This property can be used for styling and overriding components appearance.

Theming Example

To customize theming, simply include the theme property in the componentsFactory constructor.

theme:{
	colors: {colorpalette},
	fontWeights: "1",
	components: {
	  Button: {...ButtonSettings, boxShadow: 'none'},
	},
}

The Merchant can customize the entire color palette, many standard text formatting options and the granular settings of each individual Component, like button, credit card, or Input. The full customization reference is available here.

Backend Authentication Endpoint

The endpoint should return a JSON object with the 'token' field containing the signed token value.

For example:

{”token”: “eyJg…”}

The token subject should be set as the Maxio customer reference of a customer referring to an authenticated user in the Merchant’s application. Token should be signed using the JWT key provided while launching the integration in Maxio. Signing should be done using HS256 algorithm. Also, the iat (issued at) claim must be provided.

# Install the PyJWT package using pip, or include it in your requirements.txt.
import base64
from datetime import datetime
import json
from jwt.api_jwt import PyJWT

payload = {
	"sub": customer_reference, # where customer_reference is a Maxio customer's 
	# reference field resolved from merchant's authenticated customer
	"iat": datetime.utcnow().timestamp()
}

decoded_key = base64.b64decode(key) # where key is secret provided within Maxio UI
jwt_token = PyJWT().encode(payload=payload, key=decoded_key)
response_body = json.dumps({"token": jwt_token})

// Add the jsonwebtoken dependency to the project, then:
module.post('/auth', (req: Request, res: Response) = {
	const token = jwt.sign(
		{},
		Buffer.from(MERCHANT_PRIVATE_KEY, 'base64'), // where MERCHANT_PRIVATE_KEY is secret provided within Maxio UI
		{
			subject: customerReference, // where customer_reference is a Maxio customer's reference field resolved from merchant's authenticated customer
			algorithm: 'HS256'
		}
	);
	res.status(StatusCodes.OK);
	res.json({
		token,
	});
});

// Add the github.com/golang-jwt/jwt/v5 package to the project, then:
import (
	"time"
	"encoding/base64"
	"github.com/golang-jwt/jwt/v5"
)

func main() {
	// Create a new token object
	token := jwt.New(jwt.SigningMethodHS256)

	// Set the claims for the token
	claims := token.Claims.(jwt.MapClaims)
	claims["sub"] = customer_reference // where customer_reference is a Maxio 
		// customer's reference field resolved from merchant's authenticated customer.
	claims["iat"] = time.Now().Unix()

	// Sign the token with the secret key
	decoded_key, _ := base64.StdEncoding.DecodeString(secretKey) // where secretKey 
		// is secret provided within Maxio UI
	signedToken, _ := token.SignedString(decoded_key)
}

// Add the github.com/golang-jwt/jwt/v5 package to the project, then:
io.jsonwebtoken.jjwt-api,
io.jsonwebtoken.jjwt-impl,
io.jsonwebtoken.jjwt-jackson

Key key = Keys.hmacShaKeyFor(Base64.getDecoder().decode(base64Key)); // where base64Key is secret provided within Maxio UI
String jw = Jwts.builder()
	.setIssuedAt(new Date())
	.setSubject(customer_reference) // where customer_reference is a Maxio customer's reference field resolved from merchant's authenticated customer
	.signWith(key)
	.compact();

// Add the JWT dependency to the project: dotnet add package System.IdentityModel.Tokens.Jwt
var signingKey = new SymmetricSecurityKey(Convert.FromBase64String(secretKey)); 
// where secretKey is secret provided within Maxio UI
var signingCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256);

// Create the JWT token
var claims = new[]
{
	new Claim("sub", customer_reference), // where customer_reference is a Maxio 
// customer's reference field resolved from merchant's authenticated customer
	new Claim("iat", DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString())
};

var token = new JwtSecurityToken(
	claims: claims,
	signingCredentials: signingCredentials
	);
// Encode the JWT token as a string
var encodedToken = new JwtSecurityTokenHandler().WriteToken(token);