Action Links

Kashia provides hosted action pages that you can redirect your users to. This is the recommended approach — your users confirm actions on a Kashia-secured page without needing a Kashia account.

Action Types

Every link is generated for a specific person — the user_id you pass must hold the role the action expects, and the escrow must be in a status where the action makes sense:

deliver — can only be generated for the escrow's seller, while the escrow is active. On the hosted page the seller confirms shipment with optional tracking details (goods), or the provider marks the job completed with a summary and work evidence (services) — the page adapts to the escrow's kind.
confirm — can only be generated for the escrow's buyer, while the escrow is awaiting_confirmation. The buyer confirms receipt (goods) or the client confirms completion (services), and the funds are released.
dispute — for either party (the user_id decides who the page acts as; their messages are attributed to them). Opens the dispute thread. Requires the escrow to be active, awaiting_confirmation, or disputed. Disputes are hosted-page-first by design: the API opens a dispute and hands out links; all conversation happens here, where buyer, seller, merchant, and Kashia's dispute officer converge.
view — for either party, in any status. A read-only view of the escrow.

A user_id that is a party but holds the wrong role (e.g. a deliver link for the buyer), or an escrow in the wrong status, returns 400 with a message saying which rule failed. A user_id that is not a party to the escrow at all returns 403.

Token Security

Links expire after 24 hours (configurable)
Deliver and confirm links are one-time use, and generating a new one deactivates the previous active link of the same type for that user — only the newest can execute the action
Dispute and view links can be accessed multiple times and stay valid until they expire — minting a new one does not kill links already sent (e.g. by email)

Generate an Action Link

The :escrowId in the path is the escrow'sid — not the payment link's. The escrow is created when the payment link is paid; you receive its id in the escrow.created webhook, or as the escrow_id field when you fetch a paid payment link. Easier still: resolve it from your own order_id (or the payment link) via GET /external/escrows/lookup.

POST/api/v1/external/escrows/:escrowId/action-links

Generate a secure hosted action link for a buyer or seller.

Request example

bash

curl -X POST https://vault-api.kashiahq.com/api/v1/external/escrows/3ee0c97c-87f8-4158-b83b-134a187b7781/action-links \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "f7b16e1f-6761-48e7-9ceb-5d0981e8e650",
    "action_type": "deliver"
  }'

Request body (JSON)

json

{
  "user_id": "f7b16e1f-6761-48e7-9ceb-5d0981e8e650",
  "action_type": "deliver"
}

Response

json

{
  "success": true,
  "data": {
    "action_url": "https://vault.kashiahq.com/action/aee07d5d1ddb438c…",
    "action_type": "deliver",
    "expires_at": "2025-01-16T10:30:00Z",
    "escrow_reference": "ESC-98e7d9bb"
  }
}

Redirect (or send) the user to action_url.

Errors

400 BAD_REQUEST— the user doesn't hold the role the action expects (e.g. a confirm link for someone who isn't the buyer), or the escrow isn't in a status that allows the action (e.g. deliver on a completed escrow). The message says which.
403 FORBIDDEN — the escrow belongs to another merchant, or the user_id is not a party to this escrow.
404 NOT_FOUND— no escrow with that id. The most common cause is passing the payment link's id instead of the escrow's.

json

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "validation error: ..."
  }
}

Parameters
Parameter	Type	Required	Description
`user_id`	string (UUID)	Yes	The customer the link is for. Must match the role the action expects: the escrow's seller for deliver, its buyer for confirm, either party for dispute and view.
`action_type`	string	Yes	One of "deliver", "confirm", "dispute", or "view".

Recommended Integration

When escrow becomes active, generate a deliver link for the seller
Embed or send this link in your app
The seller confirms shipment — or the provider marks the job completed — on Kashia's hosted page
When escrow is awaiting confirmation, generate a confirm link for the buyer
For disputes, always use the hosted dispute page