API
LinkRequest
An embedded-flow link request, for KYC, payment instruments, recipients or disputes.
Operations
Every route this entity exposes. Each route links to its own reference on this page.
| Method | Route | SDK operation | Returns |
|---|---|---|---|
POST |
/profiles/{profileId}/embedded-flows/link-requests/kyc-reviews |
create |
Embedded link request created |
POST |
/profiles/{profileId}/embedded-flows/link-requests/payment-instrument |
create |
Embedded link request created |
POST |
/profiles/{profileId}/embedded-flows/link-requests/recipients |
create |
Embedded link request created |
POST |
/profiles/{profileId}/embedded-flows/link-requests/spend/disputes |
create |
Embedded link request created |
GET |
/embedded-flows/link-requests/{embeddedLinkRequestId} |
load |
Embedded link request found |
Examples
One example per SDK, generated from the API model. The argument names are the parameters and fields of this entity, and the values are placeholders. The examples are not compiled or executed.
Golang
Construct client as shown in the Golang setup, then call the operations:
link_request, err := client.LinkRequest(nil).Load(map[string]any{"id": "example_id"}, nil)
if err != nil {
panic(err)
}
fmt.Println(link_request)
created, err := client.LinkRequest(nil).Create(map[string]any{"profile_id": 1, "email": "example", "redirectUrl": "example", "transactionId": 1}, nil)
if err != nil {
panic(err)
}
fmt.Println(created)
Lua
Construct client as shown in the Lua setup, then call the operations:
local link_request, err = client:LinkRequest():load({ id = "example_id" })
local created, err = client:LinkRequest():create({ profile_id = 1, email = "example", redirectUrl = "example", transactionId = 1 })
PHP
Construct client as shown in the PHP setup, then call the operations:
$link_request = $client->LinkRequest()->load(["id" => "example_id"]);
$created = $client->LinkRequest()->create(["profile_id" => 1, "email" => "example", "redirectUrl" => "example", "transactionId" => 1]);
Python
Construct client as shown in the Python setup, then call the operations:
link_request = client.LinkRequest().load({"id": "example_id"})
created = client.LinkRequest().create({ "profile_id": 1, "email": "example", "redirectUrl": "example", "transactionId": 1 })
Ruby
Construct client as shown in the Ruby setup, then call the operations:
link_request = client.LinkRequest.load({ "id" => "example_id" })
created = client.LinkRequest.create({ "profile_id" => 1, "email" => "example", "redirectUrl" => "example", "transactionId" => 1 })
TypeScript
Construct client as shown in the TypeScript setup, then call the operations:
const link_request = await client.LinkRequest().load({ id: "example_id" })
const created = await client.LinkRequest().create({ profile_id: 1, email: "example", redirectUrl: "example", transactionId: 1 })
Fields
| Field | Type | Required | Description |
|---|---|---|---|
clientKey |
string |
Yes | Client key that created the embedded link request. |
email |
string |
Yes | The end user's email address, to receive dispute updates. |
id |
string |
Yes | Embedded link request ID. |
metadata |
object |
Yes | Flow-specific metadata. |
profileId |
integer |
Yes | Profile that owns the embedded flow. |
redirectUrl |
string |
Yes | URL where Wise redirects the user after the flow resolves. |
transactionId |
integer |
Yes | The ID of the card transaction to dispute. |
type |
string |
Yes | Embedded Flow type. |
create
POST /profiles/{profileId}/embedded-flows/link-requests/kyc-reviews
Operation ID: kycReviewsEmbeddedLinkRequestCreate.
Authentication: bearer token (UserToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
kycReviewId |
string (uuid) |
Yes | The UUID for the KYC review to be completed. |
redirectUrl |
string (uri) |
Yes | URL where the user is redirected when the flow resolves. This also includes query parameters based on flow completion state and completed KYC review ID. For more information, see our Embedded Flows - KYC Review guide. |
Example request body:
{
"kycReviewId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"redirectUrl": "https://example.com/return"
}
Responses
201: Embedded link request created
application/json
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt |
string (date-time) |
Yes | Timestamp when the returned flow URL expires. |
url |
string (uri) |
Yes | Unique URL to open or embed for the user. |
Example response:
{
"expiresAt": "2026-06-15T13:23:20.265Z",
"url": "https://wise-sandbox.com/embedded-flows?embeddedLinkRequestId=9f5f5812-2609-4e48-8418-b64437c0c7cd#token=0d0bdc88-bcf4-43dd-85be-7ca65441db20"
}
400: Invalid request, such as an invalid redirect URL
401: User is not authorised to access the resource
404: Profile not found
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
POST /profiles/{profileId}/embedded-flows/link-requests/payment-instrument
Operation ID: paymentInstrumentEmbeddedLinkRequestCreate.
Authentication: bearer token (UserToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
method |
enum: BACS, SEPA, ACH, EFT |
Yes | The method the payment instrument is created for. |
redirectUrl |
string (uri) |
Yes | URL where the user is redirected when the flow resolves. This also includes query parameters based on flow completion state and created payment instrument ID. For more information, see our Embedded Flows - Payment Instruments guide. |
Example request body:
{
"method": "BACS",
"redirectUrl": "https://example.com/return"
}
Responses
201: Embedded link request created
application/json
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt |
string (date-time) |
Yes | Timestamp when the returned flow URL expires. |
url |
string (uri) |
Yes | Unique URL to open or embed for the user. |
Example response:
{
"expiresAt": "2026-06-15T13:23:20.265Z",
"url": "https://wise-sandbox.com/embedded-flows?embeddedLinkRequestId=9f5f5812-2609-4e48-8418-b64437c0c7cd#token=0d0bdc88-bcf4-43dd-85be-7ca65441db20"
}
400: Invalid request, such as an invalid redirect URL
401: User is not authorised to access the resource
404: Profile not found
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
POST /profiles/{profileId}/embedded-flows/link-requests/recipients
Operation ID: recipientEmbeddedLinkRequestCreate.
Authentication: bearer token (UserToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
redirectUrl |
string (uri) |
Yes | URL where the user is redirected when the flow resolves. This also includes query parameters based on flow completion state and created recipient ID. For more information, see our Embedded Flows - Recipient Creation guide. |
targetCurrency |
string |
No | Optional target currency used to start recipient requirements for a specific currency. |
Example request body:
{
"redirectUrl": "https://example.com/return",
"targetCurrency": "USD"
}
Responses
201: Embedded link request created
application/json
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt |
string (date-time) |
Yes | Timestamp when the returned flow URL expires. |
url |
string (uri) |
Yes | Unique URL to open or embed for the user. |
Example response:
{
"expiresAt": "2026-06-15T13:23:20.265Z",
"url": "https://wise-sandbox.com/embedded-flows?embeddedLinkRequestId=9f5f5812-2609-4e48-8418-b64437c0c7cd#token=0d0bdc88-bcf4-43dd-85be-7ca65441db20"
}
400: Invalid request, such as an invalid redirect URL
401: User is not authorised to access the resource
404: Profile not found
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
POST /profiles/{profileId}/embedded-flows/link-requests/spend/disputes
Operation ID: disputeEmbeddedLinkRequestCreate.
Authentication: bearer token (UserToken) or bearer token (ClientCredentialsToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
profileId |
path |
integer (int64) |
Yes | The profile ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Request body
application/json
| Property | Type | Required | Description |
|---|---|---|---|
email |
string (email) |
Yes | The end user's email address, to receive dispute updates. |
redirectUrl |
string (uri) |
Yes | URL where the user is redirected when the flow resolves. This also includes query parameters based on flow completion state and disputed transaction IDs. For more information, see our Embedded Flows - Dispute Creation guide. |
transactionId |
integer (int64) |
Yes | The ID of the card transaction to dispute. It must belong to the given profile. |
Example request body:
{
"email": "user@example.com",
"redirectUrl": "https://example.com/return",
"transactionId": 625327
}
Responses
201: Embedded link request created
application/json
| Property | Type | Required | Description |
|---|---|---|---|
expiresAt |
string (date-time) |
Yes | Timestamp when the returned flow URL expires. |
url |
string (uri) |
Yes | Short-lived URL to start the embedded dispute flow. |
Example response:
{
"expiresAt": "2026-06-15T13:23:20.265Z",
"url": "https://wise-sandbox.com/embedded-flows?embeddedLinkRequestId=9f5f5812-2609-4e48-8418-b64437c0c7cd#token=0d0bdc88-bcf4-43dd-85be-7ca65441db20"
}
400: Invalid request, such as an invalid redirect URL or a transaction that doesn't exist
401: User is not authorised to access the resource
403: The dispute creation flow is not enabled for the profile
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.
load
GET /embedded-flows/link-requests/{embeddedLinkRequestId}
Operation ID: embeddedLinkRequestGet.
Authentication: bearer token (UserToken).
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
embeddedLinkRequestId |
path |
string (uuid) |
Yes | The embedded link request ID. |
X-External-Correlation-Id |
header |
string (uuid) |
No | Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more. |
Responses
200: Embedded link request found
application/json
| Property | Type | Required | Description |
|---|---|---|---|
clientKey |
string |
Yes | Client key that created the embedded link request. |
id |
string (uuid) |
Yes | Embedded link request ID. |
metadata |
object |
Yes | Flow-specific metadata. |
metadata.targetCurrency |
string |
No | Optional target currency for hosted recipient creation. |
profileId |
integer (int64) |
Yes | Profile that owns the embedded flow. |
redirectUrl |
string (uri) |
Yes | URL where Wise redirects the user after the flow resolves. |
type |
enum: RECIPIENT, KYC |
Yes | Embedded Flow type. |
Example response:
{
"clientKey": "partner-client-key",
"id": "ea5eb6ca-3af7-4e88-a2e2-6a68dd92f198",
"metadata": {
"targetCurrency": "USD"
},
"profileId": 12345,
"redirectUrl": "https://example.com/return",
"type": "RECIPIENT"
}
401: User is not authorised to access the resource
404: Embedded link request not found
429: Rate limit exceeded. Retry after the number of seconds specified in the Retry-After header
application/json
The response is object.