Skip to main content

Change request applications

Overview​

A change request application is a hosted experience that lets an existing seller update specific information on their Getpaid account without going through the full onboarding flow again.

Like the onboarding application, the change request runs on a Getpaid-hosted page that you can brand to match your platform. You decide which fields the seller is allowed to review and update, and Getpaid takes care of rendering the form, validating the input, and notifying you of the result.

Use change requests when you need the seller to maintain or refresh part of their account, for example updating the branding settings used for their hosted experiences.

Steps​

1. Create a change request application​

Create the change request application via API by calling the POST api.getpaid.io/v2/applications endpoint with type set to change_request.

You must specify the seller account.id whose information is being updated and the list of fields the seller is allowed to access while the application is open. Each entry in fields is scoped to a single piece of account information — any field not listed remains unchanged.

If you want the seller to update their branding configuration, include themes in fields.

POST api.getpaid.io/v2/applications
{
  "type": "change_request",
  "account": {
    "id": "acc_4fekhxdpss1et7rjp8t7rdpnw4"
  },
  "reference": "53426",
  "fields": [
    {
      "name": "themes",
      "access": "read_write"
    }
  ],
  "redirect": {
    "default": "https://titanauto.com/change-request/complete?customer=53426"
  },
  "webhooks": {
    "url": "https://webhooks.titanauto.com/getpaid"
  }
}

You can optionally set theme_id to brand the hosted change request page with one of your platform themes. This only affects the appearance of the hosted page itself and does not update the seller account's theme configuration. If omitted, the account's default theme is used.

note

Only one change request can be open at a time for a given seller account. Attempting to create another change request while one is still in progress returns a validation error referencing the open application.

2. Handle the application response​

A successful change request creation returns an application id and a flow.next_step.url to present the change request form to the seller. The account.id echoes the seller account being updated.

201 Created - POST api.getpaid.io/v2/applications
{
  "id": "app_5mzpjyeqtt2fu8skq9u8seqow5",
  "status": "initiated",
  "reference": "53426",
  "created_at": "2026-05-12T10:15:00.000Z",
  "updated_at": "2026-05-12T10:15:00.000Z",
  "expires_at": "2026-05-26T10:15:00.000Z",
  "account": {
    "id": "acc_4fekhxdpss1et7rjp8t7rdpnw4"
  },
  "flow": {
    "next_step": {
      "type": "redirect",
      "url": "https://onboarding.getpaid.io/v2/app_5mzpjyeqtt2fu8skq9u8seqow5?token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
  }
}

3. Redirect to hosted change request​

You can either redirect the seller to the hosted change request URL immediately or share the link so they complete it later.

4. Change request form rendered​

When the seller opens the link, the hosted change request page is displayed in their browser, scoped to the fields you listed when creating the application.

5. Review and update the requested fields​

The seller reviews the current values and updates the ones you allowed access to. Progress is saved automatically so they can resume later without losing changes.

6. Refresh the change request application​

The change request URL is valid for 14 days. If the seller hasn't submitted the form within that period, you can extend its validity for another 14 days by calling the POST api.getpaid.io/v2/applications/{application_id}/refresh endpoint.

Use the URL returned in the response at flow.next_step.url to redirect your seller to continue completing the change request form.

7. Submit change request application​

The seller sees a summary of the changes and can adjust any value before confirming and submitting the application.

8. Redirect to platform website​

Once submitted, the seller is redirected to your website using the URL configured in the redirect block during application creation.

9. Application submitted notification​

After the application is submitted, your platform server — set in the webhooks block during application creation — receives an application_submitted webhook.

application_submitted webhook
{
  "id": "evt_49c6zjncp5fk4572vj1y1f9gw8",
  "type": "application_submitted",
  "version": "v2",
  "occurred_at": "2026-05-12T11:02:18.420Z",
  "data": {
    "id": "app_5mzpjyeqtt2fu8skq9u8seqow5",
    "reference": "53426"
  }
}

10. Application completed notification​

Once the change request is processed, the seller account is updated with the new values and your platform server receives an application_completed webhook. From that point on, the new account information is in effect across the Getpaid solution.

application_completed webhook
{
  "id": "evt_49c6zjncp5fk4572vj1y1f9gw8",
  "type": "application_completed",
  "version": "v2",
  "occurred_at": "2026-05-12T11:08:44.117Z",
  "data": {
    "id": "app_5mzpjyeqtt2fu8skq9u8seqow5",
    "reference": "53426"
  }
}