Hyperwallet Integration Documentation

Home

Welcome to the Hyperwallet integration documentation website. Navigate using the top menu.

Production public key is hosted to help you get started with payload encryption.You may view JWKS endpoint at URL provided here. Hyperwallet caches your public keys when possible. However, you need to ensure that your public keys are always accessible to avoid service interruption. Hyperwallet supports public/private keys and compact JWT serialization. Hyperwallet doesn't support shared secrets or password-based encryption.

GitHub Pages Hosting

Create repository on GitHub.
Add index.html, jwks.json, and assets.
Enable GitHub Pages in Settings → Pages.
Publish at https://<username>.github.io/<repo>/.

JWKS Public Key Hosting

Place your JWKS in jwks.json and ensure HTTPS access.

{
  "keys": [
    {"kty":"RSA","kid":"prod-key-1","use":"enc","alg":"RSA-OAEP-256","n":"...","e":"AQAB"}
  ]
}

Payload Encryption

RSA-OAEP-256 for CEK encryption
AES-256-GCM for payload
JWE Compact Serialization

Encryption Flow

from jwcrypto import jwk, jwe
from jwcrypto.common import json_encode

with open('jwks.json') as f:
    jwks = json.load(f)
recipient_key = jwk.JWK.from_json(json.dumps(jwks['keys'][0]))

payload = b'{"email":"amohammed@paylution.com"}'
protected = {'alg':'RSA-OAEP-256','enc':'A256GCM','kid':recipient_key.get('kid')}
jwetoken = jwe.JWE(payload, json_encode(protected))
jwetoken.add_recipient(recipient_key)
compact = jwetoken.serialize(compact=True)

Production Access

Share JWKS endpoint with Hyperwallet.
Ensure kid matches encrypted payload header.
Encrypt requests as JWE.
Sign requests with your private key if needed.
Send payloads to https://api.paylution.com/rest/v4

How Decryption & Signature Verification Works (HS512)

Header

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

Payload (Data)

{
  "token": "usr-78c03528-9916-4856-a92d-bdf79a04d430",
  "status": "PRE_ACTIVATED",
  "verificationStatus": "NOT_REQUIRED",
  "taxVerificationStatus": "NOT_REQUIRED",
  "createdOn": "2025-11-13T16:52:56",
  "clientUserId": "AB67399IP",
  "profileType": "INDIVIDUAL",
  "firstName": "Abdulrahman",
  "lastName": "Mohammed",
  "email": "amohammed@paylution.com",
  "addressLine1": "186 Buza Road",
  "city": "Daressalaam",
  "stateProvince": "DAR",
  "country": "TZ",
  "postalCode": "15115",
  "language": "en",
  "timeZone": "GMT",
  "programToken": "prg-da2bf439-bf8e-4420-89rd-1b53350a2377",
  "links": [
    {
      "params": { "rel": "self" },
      "href": "https://uat-api.paylution.com/rest/v4/users/usr-78c03528-9916-4856-a92d-bdf79a04d430"
    }
  ]
}

Verify Signature

HMACSHA512(
    base64UrlEncode(header) +
    "." +
    base64UrlEncode(payload),
    base64Decode(your-secret-base64)
)

see the structure available

Hyperwallet Integration & Encryption Docs