> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt > Use this file to discover all available pages before exploring further. # Resume workspace setup after payment verification > Consumes the short-lived return token issued with a setup intent and rotates the session resume credential atomically. It is bound to the public session, current setup intent and current resume credential, so it cannot be replayed after rotation. Token lifetime is at most15 minutes and never exceeds session expiry. ## OpenAPI ````yaml post /workspace-onboarding/payment-return/exchange openapi: 3.0.0 info: title: Gratona API description: >- REST API for the Gratona fundraising platform, including donor, donation, sponsorship, program, event, and integration workflows. Endpoints are organized by tag. Most endpoints require either a Passport bearer token or an issued API key — see the Security Schemes section. contact: name: Gratona Engineering url: https://gratona.com email: devs@gratona.com version: 1.0.0 servers: - url: https://api.gratona.com/v1 description: Server Version 1.0.0 security: [] tags: - name: Auth description: >- Login, signup, logout, password reset, and email verification for admin users and donors. - name: Donors description: >- Donor records: CRUD, profile fields, household linkage, search, filters, merge, and duplicate detection. - name: Donations description: >- Individual donation records, recurring commitments, soft credits, refunds, designations, and exports. - name: Sponsorships description: >- Donor-to-entity commitment relationships, lifecycle transitions, and commitment-specific filters. - name: Entities description: >- Recipient records (children, families, projects, animals, etc.), their status, and entity-level fields. - name: Programs description: >- Program / campaign configuration: hierarchy, settings, and program-level metadata. - name: Forms description: >- Custom form builder (HysForm), form fields, standardized donor fields, and field migrations. - name: Trips description: >- Mission-trip management: trips, participants, budgets, tasks, e-signatures, fundraising milestones, and background checks. - name: Communications description: >- Email templates, SMS, newsletters, donor email manager, and per-donor notes. - name: Payments description: >- Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks). Excludes inbound webhooks — see the Webhooks tag. - name: Reports description: Dashboards, analytics, scheduled reports, and exports. - name: Admin description: >- Client-account administration: users, groups/permissions, settings, integrations, and account lifecycle. - name: Donor Portal description: >- Endpoints consumed by the donor-facing portal (donor login, dashboard, donation history, messages). - name: Recipient Portal description: Endpoints consumed by the recipient-facing portal. - name: Public description: >- Unauthenticated public endpoints: donor signup, public trip pages, peer-to-peer campaigns, public checkout. - name: Webhooks description: >- Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr, DropboxSign). Annotated minimally for reference; payload shapes are owned by the upstream provider. - name: Events description: >- Event setup, invitations, registration, ticketing, attendance and event reporting. - name: Journeys description: >- Journey graphs, activation, enrollment, message templates and event follow-up automations. - name: Tasks description: Workspace tasks, assignments, saved task views and record collaboration. - name: Fundraising description: >- Fundraising portfolios, stewardship plans, giving anniversaries and personal donor follow-up. - name: Impact Stories description: Story intake, review, assets, consent and publication workflows. - name: Integrations description: Workspace integration connections, mappings, synchronization and recovery. - name: Email Calendar description: Connected email/calendar accounts and donor interactions. - name: Spaces description: Workspace Spaces and collaborative Pages. - name: Library description: Workspace documents, source connections, files and analysis. - name: Intelligence description: Donor intelligence and Tali workspace workflows. - name: Automation description: >- V3 automation primitive discovery, input validation, invocation and Zapier contracts. - name: Schema description: V3 model, enum, capability and scope discovery. - name: Zapier description: Zapier automation connections, polling feeds and actions. - name: Files description: Files - name: Client description: Client - name: Payment Gateways description: Payment Gateways - name: Email Settings description: Email Settings - name: Admin Dashboard description: Admin Dashboard - name: Recipients description: Recipients - name: Historical Archived Updates description: Historical Archived Updates - name: Team & access description: Team & access - name: Settings description: Settings - name: Notifications description: Notifications - name: Participation description: Participation - name: Users description: Users - name: Wrapped description: Wrapped - name: Donor SignUp description: Donor SignUp - name: Frontend description: Frontend - name: User description: User - name: Workspace description: Workspace paths: /workspace-onboarding/payment-return/exchange: post: tags: - Workspace summary: Resume workspace setup after payment verification description: >- Consumes the short-lived return token issued with a setup intent and rotates the session resume credential atomically. It is bound to the public session, current setup intent and current resume credential, so it cannot be replayed after rotation. Token lifetime is at most15 minutes and never exceeds session expiry. operationId: reference_Frontend_WorkspaceOnboardingController_exchangePaymentReturn requestBody: description: Validated request fields for this operation. required: true content: application/json: schema: required: - public_id - return_token properties: public_id: description: Public setup-session UUID. type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 return_token: description: Signed return token from payment_return.token. type: string maxLength: 96 pattern: ^\d{10}\.[a-f0-9]{64}$ example: >- 1760961600.0000000000000000000000000000000000000000000000000000000000000000 type: object responses: '200': description: Operation result. content: application/json: schema: required: - status - data - session_token properties: status: type: string enum: - success example: success data: $ref: '#/components/schemas/WorkspaceOnboardingSession' session_token: description: New opaque resume credential. type: string maxLength: 64 minLength: 64 example: >- example-session-token-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx type: object '401': description: The return token or its bound session is invalid or expired. content: application/json: schema: $ref: '#/components/schemas/WorkspaceOnboardingError' '422': description: Request validation failed. content: application/json: schema: oneOf: - $ref: '#/components/schemas/WorkspaceOnboardingError' - $ref: '#/components/schemas/ValidationErrorResponse' '429': description: The setup request rate limit was reached. '503': description: Workspace setup or a required service is unavailable. content: application/json: schema: $ref: '#/components/schemas/WorkspaceOnboardingError' security: [] servers: - url: https://api.gratona.com/v1 description: Gratona API components: schemas: WorkspaceOnboardingSession: required: - public_id - state - brand_id - email - answers - automatic_billing - qualification - expires_at properties: public_id: description: Public setup-session UUID. type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 state: type: string enum: - pending_auth - existing_account - authenticated - organization_confirmed - intent_resolved - qualification_satisfied - provisioning - workspace_ready - handed_off example: authenticated brand_id: type: string enum: - gratona - gratona-sponsorships example: gratona email: description: Mailbox that will own the new workspace. type: string format: email maxLength: 255 example: jane@example.org first_name: type: string example: Jane nullable: true last_name: type: string example: Donor nullable: true organization_name: type: string example: Example Nonprofit nullable: true website: type: string example: https://example.org/ nullable: true ein: type: string example: '123456789' nullable: true country_code: type: string example: US nullable: true phone: type: string example: '+12025550123' nullable: true answers: description: >- Confirmed answer object, or an empty JSON array before intent confirmation. oneOf: - required: - primary_goal - starting_point properties: primary_goal: type: string example: fundraising_campaigns starting_point: type: string example: launching_new type: object additionalProperties: false - type: array items: type: string maxItems: 0 automatic_billing: description: Admission does not enable automatic billing. type: boolean enum: - false example: false qualification: type: string enum: - verify_payment_method example: verify_payment_method expires_at: type: string format: date-time example: '2026-10-21T12:00:00Z' nullable: true questions: description: >- Displayed until intent is confirmed. Pass primary_goal to show its starting-point branch. type: array items: required: - key - prompt - type - required - options properties: key: type: string example: primary_goal prompt: type: string example: What would you like Gratona to help you set up first? type: type: string enum: - single_choice example: single_choice required: type: boolean example: true options: type: array items: required: - value - label properties: value: type: string example: fundraising_campaigns label: type: string example: Fundraising campaigns and donations type: object type: object type: object WorkspaceOnboardingError: required: - status - code - message properties: status: type: string enum: - error example: error code: type: string example: workspace_onboarding_session_unavailable message: type: string example: This setup session is no longer available. Start again. type: object ValidationErrorResponse: title: ValidationErrorResponse description: >- Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The `errors` map is keyed by the failing field name; each value is an array of human-readable error messages for that field. Most controllers also include a top-level `status: error`. required: - errors properties: errors: description: >- Map of field name to array of validator error messages. Example: `{email: [The email field is required.], amount: [The amount must be a number.]}`. type: object additionalProperties: type: array items: type: string status: description: Always the literal string `error`. type: string example: error message: description: >- Optional summary message — present on some endpoints, absent on others. type: string example: The given data was invalid. nullable: true type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.