Link Actions

Link Actions

Actions allow you to automate workflows by triggering external callbacks when a payment is made on a Gatepay link.

Action Types

• callback: Triggers an HTTP request to your specified URL when a payment is confirmed.

When Are Actions Triggered?

• Actions are executed automatically by Gatepay when a payment is successfully completed on a link.
• Use actions to notify your backend, update user access, or trigger business logic.

Adding Actions to Existing Links

Actions are added to existing links using the links API after the link is created:

// First, create a link
const link = await gatepay.createLink({
    name: "Premium Content",
    description: "Access to premium content with payment callback",
    resource: {
        type: "link",
        data: {
            url: "https://example.com/premium-content",
        },
    },
    toll: {
        tollPaymentRequirements: [
            {
                assetNetwork: "base",
                amount: "1000000", // 1 USDC
                assetAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                destinationAddress: "your-wallet-address",
            },
        ],
    },
})

// Then, add a callback action
await gatepay.links.postLinksByLinkUuidActions({
    linkUuid: link.uuid,
    postLinksByLinkUuidActionsRequest: {
        type: "callback",
        data: {
            url: "https://your-backend.com/webhooks/payment-completed",
            method: "POST",
        },
    },
})

Callback Action Configuration

The callback action requires these parameters:

{
    type: "callback",
    data: {
        url: "https://your-api.com/webhooks/payment-completed",
        method: "POST", // HTTP method
    }
}

Managing Actions

List Actions for a Link

// Note: Use direct API call as there's no convenience method
const response = await fetch(
    `https://api.gatepay.cloud/links/${linkUuid}/actions`,
    {
        headers: {
            Authorization: `Bearer ${apiToken}`,
            "Content-Type": "application/json",
        },
    }
)
const actions = await response.json()

Update an Action

await gatepay.links.putLinksByLinkUuidActionsByActionUuid({
    linkUuid: "your-link-uuid",
    actionUuid: "your-action-uuid",
    postLinksByLinkUuidActionsRequest: {
        type: "callback",
        data: {
            url: "https://your-new-endpoint.com/webhook",
            method: "POST",
        },
    },
})

Delete an Action

await gatepay.links.deleteLinksByLinkUuidActionsByActionUuid({
    linkUuid: "your-link-uuid",
    actionUuid: "your-action-uuid",
})

Example: Webhook Handler (Hono)

Here’s an example webhook handler using Hono:

import { Hono } from "hono"

const app = new Hono()

app.post("/webhooks/payment-completed", async (c) => {
    const payload = await c.req.json()

    // your business logic

    return c.text("OK", 200)
})

export default app

---

See also:

• Create Your First Link