# YOU Account Linking Link a creator’s Yoursafe account to your platform so you can pay them with a public token. The creator proves their identity and consents to the link. After a successful link you receive their email address, IBAN, and public token, and you can pay that token with Mass Payments. - https://you.yoursafe.com ## [Creator journey](#journey) Send creators who already have a Yoursafe account to the linkage page, or send new creators through registration and linkage in one flow. In Yoursafe Business, under YOU Account Linking, set the success redirect URL, success postback URL, and platform return URL, and copy your linkage ID and secret key. - The creator begins on your payout settings page and chooses to link an existing Yoursafe account or register a new one. - An existing account holder signs in on the linkage page and authorizes payouts to that account. A new account holder completes registration, confirms their email, and installs the Yoursafe App. The new account is linked when registration finishes. - On success the browser returns to your success redirect URL with the account details, and the same details are posted to your success postback URL. If the creator cancels, they return to your platform return URL with no parameters. ## [Link an existing account](#existing-account) Use this when the creator already has a Yoursafe account. Redirect their browser to the linkage endpoint with your linkage ID, a reference you will recognize later, and a signature. The creator signs in with their Yoursafe credentials. Signing in authorizes your platform to send payouts to that account. After a successful sign-in they are redirected to your success URL, and a postback is sent at the same time. If they leave without finishing, they are sent to your platform return URL. ``` GET https://you.yoursafe.com/pairaccount?pairingReference=&platformConnectId=&signature= https://you.yoursafe.com/pairaccount?pairingReference=zzzzxxxx&platformConnectId=118187&signature=9f370ce3a617d8e3a2fec1d2a566f5aab3ad28c5 ``` GET /pairaccount ### Query parameters pairingReference string Your reference for this creator. Returned on the redirect and postback. 1–100 characters: letters, digits, underscore, or hyphen. platformConnectId number Numeric YOU Account Linking ID from Yoursafe Business. signature string SHA-1 signature, 40–80 characters. See signature calculation. ## [Register and link a new account](#new-account) Use this when the creator does not have a Yoursafe account yet. Tell them a Yoursafe account is required for payouts, then redirect them to the registration linkage endpoint. They register, confirm their email, and register in the Yoursafe App. The account is linked as soon as registration is complete, and they are told they are registering for your platform. You can also send creators who still need an account to `https://you.yoursafe.com/register`. Once they have an account, continue with the existing-account linkage endpoint. ``` GET https://you.yoursafe.com/pairaccount/register?pairingReference=&platformConnectId=&signature= https://you.yoursafe.com/pairaccount/register?pairingReference=1137520835&platformConnectId=118187&signature=a7ddf8f3f99f3d60d9122b563b6be58ce156cee7 ``` GET /pairaccount/register ### Query parameters pairingReference string Your reference for this creator. Returned on the redirect and postback. 1–100 characters: letters, digits, underscore, or hyphen. platformConnectId number Numeric YOU Account Linking ID from Yoursafe Business. signature string SHA-1 signature, 40–80 characters. See signature calculation. ## [Signature calculation](#signature) Sign every linkage request, and verify the signature on every success redirect and postback before you trust the data. The signature is the hexadecimal SHA-1 of a UTF-8 string. Start with your YOU Account Linking secret key, then append the parameters in alphabetical order by name. - Optional parameters that have a value are included. Optional parameters that are empty are left out. - Convert parameter values to UTF-8 before hashing. - On responses, every returned parameter except `signature` is part of the signed string, in alphabetical order. ``` SHA-1(:pairingReference=:platformConnectId=) ``` ## [Success redirect](#success-redirect) After the creator’s credentials are verified, the browser is sent to the success redirect URL you configured. The account details travel as query parameters. Check the signature before storing them. ``` https://myplatform.com/payment/bitsafe-success?platformConnectId=&pairingReference=&publicToken=&email=&iban=&signature= ``` ### Parameters Parameter Format Length pairingReference a-z A-Z 0-9 _- 1–100 characters platformConnectId Numeric YOU Account Linking ID numeric publicToken A-Z 0-9 8 characters email Email address (RFC 822) 3–100 characters iban Yoursafe IBAN (a-z A-Z 0-9) 10–50 characters signature SHA-1 signature 40–80 characters ## [Success postback](#success-postback) The same account details are sent to your success postback URL after the creator is verified. Treat the postback as the source to record the link. The redirect can be lost if the creator closes the browser. - The postback is an HTTP GET request. - Respond with HTTP status `200` and a plain-text body of `OK`. - A failed postback is retried twice. Parameters match the success redirect: `pairingReference`, `platformConnectId`, `publicToken`, `email`, `iban`, and `signature`. ``` https://myplatform.com/payment/bitsafe-postback?platformConnectId=&pairingReference=&publicToken=&email=&iban=&signature= ``` ## [Cancel return](#return) If the creator chooses “Back to platform” and leaves before linking, the browser is sent to your platform return URL. That redirect has no query parameters. ## [URLs and credentials](#urls) Set these in Yoursafe Business under YOU Account Linking, where you also find the linkage ID (`platformConnectId`) and the secret key used to sign and verify messages. - Success postback URL - Success redirect URL - Platform return URL Pay linked creators with the [Mass Payments API](/en/mass-payments-api).