Onboarding links
Download the complete public OpenAPI schema
Onboarding links
Issue short-lived hosted links that let an end customer complete their own profile onboarding — or update an existing profile — on an OpenMerchant-hosted page (contact details, addresses, payment method collection) without your app handling any of it.
The returned url carries the only copy of the secret token; store or forward it immediately. Links expire automatically and can be revoked early with the expire endpoint.
POST /v1/onboarding_links
Create an onboarding link
Issue a short-lived hosted onboarding link. The returned url is the only copy of the secret token — store or forward it immediately. Pass profile.id only for account_update links; omit it for account_onboarding and a profile id is reserved for you.
Parameters, request, responses, and security
{
"tags": [
"onboarding-links"
],
"summary": "Create an onboarding link",
"description": "Issue a short-lived hosted onboarding link. The returned `url` is the only copy of the secret token — store or forward it immediately. Pass `profile.id` only for `account_update` links; omit it for `account_onboarding` and a profile id is reserved for you.",
"operationId": "v1_create_onboarding_link",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnboardingLinkCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnboardingLinkRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_create_onboarding_link",
"x-mcp-exposed": true,
"x-public-path": "/v1/onboarding_links",
"x-docs-kind": "create",
"x-docs-order": 10,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/onboarding_links \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"use_case\": {\n \"type\": \"account_onboarding\"\n }\n}'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_create_onboarding_link\",\n \"arguments\": {\n \"use_case\": {\n \"type\": \"account_onboarding\"\n }\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_create_onboarding_link\",\n arguments: {\n \"use_case\": {\n \"type\": \"account_onboarding\"\n }\n},\n});"
}
]
}
GET /v1/onboarding_links/{onboarding_link_id}
Retrieve an onboarding link
Return a previously issued onboarding link by id. The user-facing URL is not included on read.
Parameters, request, responses, and security
{
"tags": [
"onboarding-links"
],
"summary": "Retrieve an onboarding link",
"description": "Return a previously issued onboarding link by id. The user-facing URL is not included on read.",
"operationId": "v1_get_onboarding_link",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Onboarding Link Id"
},
"name": "onboarding_link_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnboardingLinkRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_get_onboarding_link",
"x-mcp-exposed": true,
"x-public-path": "/v1/onboarding_links/{onboarding_link_id}",
"x-docs-kind": "retrieve",
"x-docs-order": 30,
"x-docs-depth": 0,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X GET https://api.openmerchant.dev/v1/onboarding_links/... \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_get_onboarding_link\",\n \"arguments\": {\n \"onboarding_link_id\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_get_onboarding_link\",\n arguments: {\n \"onboarding_link_id\": \"...\"\n},\n});"
}
]
}
POST /v1/onboarding_links/{onboarding_link_id}/expire
Expire an onboarding link
Mark the link as revoked so subsequent opens redirect to the configured refresh_url.
Parameters, request, responses, and security
{
"tags": [
"onboarding-links"
],
"summary": "Expire an onboarding link",
"description": "Mark the link as revoked so subsequent opens redirect to the configured `refresh_url`.",
"operationId": "v1_expire_onboarding_link",
"parameters": [
{
"required": true,
"schema": {
"type": "string",
"title": "Onboarding Link Id"
},
"name": "onboarding_link_id",
"in": "path"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnboardingLinkRead"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"ApiKeyBearer": []
}
],
"x-api-audience": "public_v1",
"x-api-authentication": "required",
"x-operation-id": "v1_expire_onboarding_link",
"x-mcp-exposed": true,
"x-public-path": "/v1/onboarding_links/{onboarding_link_id}/expire",
"x-docs-kind": "other",
"x-docs-order": 100,
"x-docs-depth": 2,
"x-docs-action-order": 1000,
"x-codeSamples": [
{
"lang": "shell",
"label": "curl",
"source": "curl -X POST https://api.openmerchant.dev/v1/onboarding_links/.../expire \\\n -H 'Authorization: Bearer pr_sk_test_...'"
},
{
"lang": "shell",
"label": "MCP (Streamable HTTP)",
"source": "curl -X POST https://api.openmerchant.dev/mcp/v1 \\\n -H 'Authorization: Bearer pr_sk_test_...' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"v1_expire_onboarding_link\",\n \"arguments\": {\n \"onboarding_link_id\": \"...\"\n }\n }\n}'"
},
{
"lang": "typescript",
"label": "MCP SDK (TS)",
"source": "// Reusing a Client connected to /mcp/v1 — see the \"MCP server\" tag for setup.\nconst result = await client.callTool({\n name: \"v1_expire_onboarding_link\",\n arguments: {\n \"onboarding_link_id\": \"...\"\n},\n});"
}
]
}