Partner program

Partner integration guide

From first conversation to a working integration: get set up, get your keys, send events, receive webhooks, sign people in with Bynefit and put Bynefit on your own pages. Each step says who does it, and what is not built yet.

The path at a glance

1. Get enrolled

Tell support you want to be a partner and which Space is yours. Bynefit records your agreement and links your partner record to your Space. That part is ours to do, because it is a signed agreement and it decides which people see your data. Admins and managers of your Space then open the console at /dash/partner and set up the rest themselves: websites, events and the details each event carries. A partner goes live once these are in place:

• the Partner Agreement is recorded, with your contracting entity;
• a decision on the credit rate is recorded (zero is a decision);
• your Space is linked;
• at least one website and at least one event are registered, which you can do from the console.

Until then the program is in draft: test events work, and nothing live is counted. The console has Home, Catalog (what exists, with its state), Requests, Keys, Events, Brand kit, Credits and the sign-in recipe. Bynefit sees every change you make there and can step in if something looks wrong, but nothing waits for us.

2. Find your keys

The Keys page shows your partner key and tells you what is ready. There are two different kinds of secret to keep apart.

Lost the signing secret? A manager of your Space makes a new one on the Keys page and sees it once. Making a new one stops the old one working at once.

3. Add your websites and events

To send events from a browser, the address your pages are served from has to be on your list, written as https://example.com (no path). Add it under Your websites on the Keys page and it works straight away, up to 20. Plain http is only accepted for localhost. Sending from your own servers needs no website.

Under Manage events you add an event, switch one off, and choose the details each event carries: a name and whether it is text, a number or yes/no, up to 10 per event. A new detail is accepted from the next event you send. Removing one stops it being accepted; events you already sent keep it. Details that would hold personal data, like a name, email, phone number, address, location, ID number or IP address, are refused.

4. Send events

Pick the browser way for pages and the signed way for servers and app backends. The full request, the worked signature example, errors and limits are on Partner events. A first check that costs nothing:

URL="https://bynefit.com/dash/api/v1/beacons/collect"
KEY="pbk_YOUR_PARTNER_KEY"
SECRET="YOUR_SIGNING_SECRET"

TS=$(date +%s)
AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
BODY="{\"test\":true,\"events\":[{\"id\":\"test-$TS\",\"name\":\"listing_viewed\",\"at\":\"$AT\"}]}"
SIGNATURE=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -i -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: $KEY" \
  -H "X-Beacon-Timestamp: $TS" \
  -H "X-Beacon-Signature: $SIGNATURE" \
  -d "$BODY"

You should see 202 and "test": true. Take "test": true out when you are ready to count real events.

5. Receive webhooks

A webhook tells your server when something happens in your Space: a form is submitted, a person joins, a donation arrives. A Space admin adds your address at /dash/integrations/webhooks and copies the signing secret once. Your server checks the signature on every delivery and answers 2xx. The envelope, headers, events, retries and ready-to-run verification code are on Webhooks.

Webhooks are about your own Space. They do not carry your partner events, and there is not a webhook for engagement or Business Setup changes.

6. Sign people in with Bynefit

People can sign in to your site or app with their Bynefit account. A manager of your Space opens /dash/partner/sign-in, names the client, and lists your return addresses: web pages, and for a native app an https link on your own domain. You get a client_id; there is no client secret, so the flow uses PKCE. The recipe shows your live endpoints. The protocol, with code, is on OAuth 2.0 / OpenID Connect.

• Name, picture and email are available straight away.
• Creator status and earnings are available By approval Bynefit approves each use first.
• A sign-in sheet that opens on your own page, without leaving it, works for the websites you list as in-page sign-in sites in the recipe.
• Return to a native app through its own link scheme, your domain written backwards (vip.example.app://callback) By approval Bynefit approves each scheme for you first. A verified https link on your domain needs no approval.

7. Put Bynefit on your pages

A Space admin copies the widget snippet from Embeds in the dashboard and lists the websites that may load it. See Embed widget. If your own website is a Bynefit-hosted site, the hosted sites guide covers forms, events, resources and sign-in on it.

8. Ask for what is missing

The Catalog lists what exists today and what does not. Most of it you switch on yourself. Use Requests to ask for something that is not built, or for the few things Bynefit reviews first: member emails, managing the shared directory, creator status and earnings at sign-in, and anything about your credit terms. A request gets a reply on the page and in your support list, and it never holds up anything else you are doing.

Bring businesses to Bynefit

These are built and listed as Available in the Catalog. Bynefit switches the business features on for your program, so they appear once it has. The Brand kit page has ready-to-send copy under Words you can use: an announcement, an email, a social post, and plain explanations of how the loyalty program and free promotion posts work, so you can tell a business what to expect before you invite them.

Credits

Credit is set per partner by Bynefit. It accrues on Business Setup orders paid by a Space that carries your partner code, after the date the rate took effect and inside the tail period if there is one. It never raises what the customer pays. The Credits page of the console shows your terms and totals, and the totals are also in the summary response.