Your own segments
Declaring the payer's memberships in segments you maintain yourself
Your system already knows things about a payer that ours cannot: that they are a returning customer of five years, that your risk team flagged them last week. A payment request can carry those memberships, and your routing can act on them.
Register the segment first
A key only means something once a segment on our side is bound to it. In the admin, open the segment and fill Foreign segment with the name or id your system uses for it. The binding is 1:1 — one key, one segment.
Filling this field takes effect immediately, not on some later step. The moment it is saved, that segment stops being judged by its expression alone: until you also switch on the setting below, every payment is treated as if you had declared no memberships at all — the segment matches nobody. If it currently matches people, binding it is what stops that, before any toggle is touched.
A key bound to nothing is ignored. That is deliberate — you can send your whole list and we take the part we recognise — but it does mean a typo is silent, so check the binding rather than the request when a segment does not match.
If the segment also carries an expression of its own, both have to hold: your key must be in the list you send and the expression must evaluate true. A bound segment with no expression matches on the key alone.
Turn it on when you're ready
The feature is off by default. In the admin, open Settings on the project — or on the merchant, to set what every project under it does unless a project overrides it — and switch on Accept foreign segments on payment requests. A project's own setting wins over the merchant's, and the merchant's wins over the default, which is off.
Until it's on, whatever you send in segments is still accepted and signed
like any other field, but every payment is judged as if you had sent [] —
in none of your segments — regardless of what the list actually held; that
judging is already in effect the moment a segment is bound, as the previous
section says. What switching this setting on changes is the refusal: only
once it is on, and only for a project with a bound segment, does sending no
list at all (as opposed to []) get refused rather than silently treated as
[]. A project that never opted in has not failed to declare anything.
Send the memberships
{
"project": "…",
"amount": "70.00",
"currency": "EUR",
"segments": ["crm_vip", "returning"],
"signature": "…"
}Abridged to the field this page is about: success_url, failure_url,
cancel_url and callback_url are also required on every payment request
and are left out here. See the payment
endpoint for the full body.
Two absences that are not the same
Sending [] says the payer is in none of your segments. Omitting segments
says nothing at all, and the two are treated differently on purpose:
- Not in the list means not in the segment. There is no third answer, so a segment you do not mention is simply false.
- No list at all, while any of your segments is bound, is refused. Your routing would otherwise decide on a membership nobody stated.
If you have no bound segments, the field changes nothing and you can leave it out.
Matching is on the exact key: trimmed of surrounding whitespace, but not
case-folded. crm_vip and CRM_VIP are two different bindings, and a key
that matches the binding except for case is treated as not sent at all.
Signing
segments joins the canonical string in its alphabetical place, like any
other field — including when it's []. See
the canonical string rule for how
an array signs; nothing about segments is special there, it's just the one
array field you're likely to use.