Save Widget Payout Details
Records the country and the PayPal address of the participant that the Widget token names, with its acceptance of the current payout terms (acceptTerms). The token needs the widget:payout scope. Without paypalEmail the save keeps the current PayPal address, for example to accept new terms; the first save without it gets 400 VALIDATION_ERROR. Only an eligible participant gives payout details, and only when a Program of its cash Rewards offers PayPal; another participant gets 400 INVALID_REQUEST, and so does a participant whose payout details are blocked. In a Live Project, an address in a reserved test domain (.test, .example, .invalid, .localhost, example.com, example.net, or example.org) gets 400 INVALID_REQUEST. The same details again change nothing; a new address replaces the default method.
Authorization
WidgetJWT HS256 with typ refref-widget+jwt, aud refref-widget, programId the referral Program of the Widget, sub the external ID of the participant, participantKind its kind (individual or group), optional email the contact email of the participant, mandatory iat and exp, lifetime at most 900 seconds. scope lists one or more Widget scopes separated by one space; widget:read gives Widget init, the referral and Reward reads, and the payout details read, and widget:payout gives the payout details save, for example "widget:read widget:payout". A token without the scope of an operation gets 403. Signed by the backend of the Program's Project with the Project secret. A Widget request names no Project and no Program; the token's Program gives both.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v1/widget/payout-details" \ -H "Content-Type: application/json" \ -d '{ "country": "string", "method": "paypal", "acceptTerms": "2026-10" }'{ "eligible": true, "contactEmail": "string", "recipient": { "status": "active", "country": "string", "method": { "type": "paypal", "maskedDestination": "string" }, "termsVersion": "string", "termsAcceptedAt": "string", "taxStatus": "not_required" }, "offeredMethods": [ "paypal" ], "termsVersion": "string", "taxFormRequired": true, "canSave": true, "amounts": { "currency": "string", "heldMinor": "string", "payableMinor": "string", "inProgressMinor": "string", "paidMinor": "string", "correctionsMinor": "string" }}Voided Webhook
An operator voided a Reward. RefRef POSTs the event to each enabled endpoint of the Project that subscribes to reward.voided, and retries for about 72 hours until the endpoint answers 2xx.
Set Qualifying Event Types PUT
Set the Event types that create a referral in the Project (default signup and purchase). A write applies at once. Needs the programs:write key permission.