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, iss and projectId equal to Project ID, aud refref-widget, sub the external ID of the participant, participantKind its kind (individual or group), 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 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 Project backend with its secret.
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 '{ "projectId": "string", "country": "string", "method": "paypal", "acceptTerms": "2026-10" }'{ "eligible": true, "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" }}