#315 — Facade API to allow Twill UI hosted (only) PayEngine embedded UI to authorize with PayEngine

Repo: Twill-AI/facade State: closed | Status: done Assignee: Unassigned

Created: 2025-03-20 · Updated: 2025-09-15

Description

See https://docs.payengine.co/developer-docs/merchant-onboarding/embedded-onboarding-ui#id-2.-authenticating-secure-setup-required-for-production-optional-in-sandbox and https://docs.payengine.co/merchant-session for details.

We should provide session for our authenticated users (i.e. for Twill UI). Note that providing this “session” API for 3d party sites is out of scope for now.

AC:

• Facade provides API to Create/Refresh a merchant session and to Delete a merchant session (deleting is not needed for now, see implementation details).
• https://twillpayments.atlassian.net/wiki/spaces/TD/pages/7929859/Facade+API is updated.

Implementation details

API is per merchant so creating GET /integrations/{integration_id}/payenginehash. And about persisting - generating HMAC takes ~8 microseconds (on my i5-10300H). So it is safe to generate it each call, moreover UI app may cache it to avoid extra HTTP call (cc @raymondehizoba). Response example:

{
  "merchant_id": "64cba9eb-c516-4819-86f4-d405c0b953ee",
  "hash": "8da6a9d2685323cd6a91a289fd70f5df4efbaf37f9e0085a71acbd33c38eb694"
}

Notes

Add implementation notes, blockers, and context here

Related

Add wikilinks to related people, meetings, or other tickets