Vudy payment requests

Payment requests let a payee create a payable request that a payer can fulfill. Prefer dedicated /channel/vudy/request/* routes (not capability execute).

Prerequisites#

  • API key with Vudy channel enabled for your app
  • Profile context: session, x-profile-id + x-team-id, or a team-bound key
  • Optional: webhook subscription for requestPaid

Flow overview#

  1. Create a request
  2. Share url / embedUrl
  3. Process payment when the payer is ready
  4. Sign and broadcast the returned payer transactions
  5. Poll status and/or listen for requestPaid
  6. Optionally notify the client by email or fetch an invoice PDF

List requests through GET /v1/txs?type=profile|team and filter the returned transactions.

1. Create#

curl -sS https://api-stg.vudy.app/channel/vudy/request/create \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "x-profile-id: PROFILE_UUID" \
  -H "x-team-id: TEAM_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.5,
    "channelParams": {
      "customId": "invoice-2024-001",
      "note": "Payment for services",
      "currencyToken": "USD",
      "requestedChain": "ethereum",
      "requestedToken": "USDC"
    }
  }'
const { data } = await fetch(
	"https://api-stg.vudy.app/channel/vudy/request/create",
	{
		method: "POST",
		headers: {
			"x-api-key": process.env.VUDY_API_KEY,
			"x-profile-id": profileId,
			"x-team-id": teamId,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			amount: 100.5,
			// targetAddress optional
			channelParams: {
				customId: "invoice-2024-001",
				note: "Payment for services",
				currencyToken: "USD",
				// addedFee: { bps: 150, recipient: "0x..." } // max 20% (2000 bps)
			},
		}),
	},
).then((r) => r.json());

// { id, url, embedUrl, txId, channelTableType: "ch_vudy_request" }

2. Get request details#

curl -sS https://api-stg.vudy.app/channel/vudy/request/REQUEST_ID \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

3. Process (payer)#

curl -sS -X POST https://api-stg.vudy.app/channel/vudy/request/REQUEST_ID \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "0xPAYER_WALLET",
    "chain": "ethereum",
    "token": "USDC"
  }'
const { data } = await fetch(
	`https://api-stg.vudy.app/channel/vudy/request/${requestId}`,
	{
		method: "POST",
		headers: {
			"x-api-key": process.env.VUDY_API_KEY,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			sender: "0xPAYER_WALLET",
			chain: "ethereum",
			token: "USDC",
		}),
	},
).then((r) => r.json());
// { txs, tokenPrice, amountInToken, gasEstimation }

Process is rejected if the request is already completed or its parent transaction has failed. Sign and broadcast each returned transaction with the payer wallet. The payment is not complete merely because this endpoint returned successfully.

4. Confirm status#

StageStatus
Createdpending
Paid / confirmedcompleted

After broadcasting, poll GET /channel/vudy/request/{id}, GET /channels/vudy/{txId}, or GET /v1/tx/{id} until the request is completed.

When payment completes, the API sends requestPaid to the webhook configured for the API key that created the transaction and to matching app subscriptions.

5. Optional follow-ups#

# Email notify (request must already be completed)
curl -sS -X POST \
  https://api-stg.vudy.app/v1/vudy/request/REQUEST_ID/notify-client \
  -H "x-api-key: vudy_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"client@example.com","language":"en"}'

# Invoice PDF (API key required; request must be completed)
curl -sS -OJ \
  https://api-stg.vudy.app/v1/vudy/request/REQUEST_ID/invoice-pdf \
  -H "x-api-key: vudy_sandbox_YOUR_KEY"

Next steps#