Client reference

Pass your own account reference at checkout and get it back in every webhook for that order.

If the buyer is already signed in to your service, pass your internal reference for their account at checkout — the client reference — and it comes back in every notification for that order as clientReference. Credit the payment to the right account without matching emails by hand: at checkout the buyer may enter any email.

In the widget, set the attribute on the same element that carries the widget attribute. The script reads it at the moment of the click, not at page load, so you can set it after the user signs in. It works in both widget modes: the button appends it to the payment link, the card passes it into the product panel and from there into the purchase. The attribute is data-client-reference:

html

<div data-lis-widget="wgt_1a2b3c" data-client-reference="acc_10294"></div>

In a direct payment link

In a direct payment link, pass it as a query parameter. Payment links are in the cabinet catalog. The parameter is client_reference:

text

https://pay.lis-system.eu/pay/prod_1a2b3c?client_reference=acc_10294

From your server

When the payment is created from your server, pass the reference in the clientReference field of the request body; there it is required.

Where it comes back

The value arrives in every event of the order: payment, partial and full refund, dispute opened and resolved. Subscription events — renewal, failed charge, cancellation, end — carry the value of the order the subscription started with. If the buyer cancels at the payment provider and retries on our payment page, the new order gets the same value.

The value is returned in the clientReference field of every webhook for the order, and you can look a buyer up by it in the Customer state and the Access check. The partner also sees it in the cabinet's order list and in the CSV export.

Format

Up to 128 characters: Latin letters, digits and . _ : - only, and the first character may not be "-" or "." (a spreadsheet opening the order export would read "-A1" as a formula). A malformed or missing value does not stop the purchase: the order is created, and clientReference in the notification is null.

The value is set by the buyer's browser: it is a crediting address, not proof of identity. The notification signature proves that the notification is from us and that the value is exactly what arrived at checkout. The value itself is set by the buyer's browser: anyone can change the attribute on your page or the link parameter. Use it as a crediting address — which account to credit — not as proof of identity or of the right to an account. Do not pass an email, a name, a phone number or other personal data, only your internal account reference. The buyer's email arrives in its own field anyway. If you need protection against tampering, sign the value on your side: for example reference.signature, where signature is an HMAC-SHA256 of the reference with your own key, in hex (64 characters; the base64 characters + / = do not pass the format), and verify that signature when the notification arrives.