Payment Links+ API

Payment Links+ is the solution for creating secure payment links with your branding. With Payment Links+, you can effortlessly set up and share payment links, regardless of the sales channel or payment method. To learn more, check out Payment Links+.

This document explains the Payment Links+ API functions.

🔓 Authorization

The Payment Links+ API requires an API key to authenticate calls. Retrieve this key from Settings > API Keys on the Payment Links+ dashboard, and pass it in the Authorization header.

curl --location 'https://linksplus-api.omise.co/external/links' \
--header 'Authorization: {{key}}'

🧾 Objects

Every endpoint on this page returns one of the objects described here. Rather than repeating the full shape under each endpoint, each one is defined once and referenced by name throughout.

The Link object

{
  "id": 12840,
  "name": "Adidas School Wear",
  "state": "active",
  "amount": 4000,
  "currency": "THB",
  "multiple_usage": true,
  "additional": "Order #12345 - priority shipping",
  "expired_at": "2026-12-31T23:59:59Z",
  "features": {
    "Type": "School Bags",
    "Size": "Medium"
  },
  "transaction_id": "lNeJd4VbUI",
  "url": "https://linksplus.omise.co/lNeJd4VbUI",
  "template_id": 3672,
  "kind": null,
  "created_at": "2024-04-20T12:23:39.321Z",
  "updated_at": "2024-04-20T12:23:39.321Z"
}

The Template object

{
  "id": 3672,
  "name": "Adidas Bags",
  "features": [
    { "display_name": "Type", "value": null, "type": "string" },
    { "display_name": "Size", "value": null, "type": "string" }
  ],
  "capabilities": [
    "... see The Capability object for the \"card\" entry ...",
    "... a second entry with \"payment_method\": \"promptpay\" ..."
  ],
  "zero_interest_installment": false,
  "created_at": "2024-04-19T10:16:49.689Z",
  "updated_at": "2024-04-19T10:16:49.689Z"
}

The Capability object

Each entry in a Template object's capabilities array describes one payment method available on it. A template supporting multiple payment methods has one Capability object per method — the example following shows a single card entry, followed by what the full array looks like when a template also accepts PromptPay.

{
  "payment_method": "card",
  "currencies": ["THB", "JPY", "USD", "EUR", "GBP", "SGD", "AUD", "CHF", "CNY", "DKK", "HKD", "MYR"],
  "card_brands": ["JCB", "Visa", "MasterCard"],
  "installment_terms": [],
  "banks": [],
  "manual": false,
  "saveCard": false
}

A capabilities array with more than one payment method looks like this — note that manual and saveCard only appear on the card entry, matching the preceding table:

[
  {
    "payment_method": "card",
    "currencies": ["THB", "JPY", "USD", "EUR", "GBP", "SGD", "AUD", "CHF", "CNY", "DKK", "HKD", "MYR"],
    "card_brands": ["JCB", "Visa", "MasterCard"],
    "installment_terms": [],
    "banks": [],
    "manual": false,
    "saveCard": false
  },
  {
    "payment_method": "promptpay",
    "currencies": ["THB"],
    "card_brands": ["JCB", "Visa", "MasterCard"],
    "installment_terms": [],
    "banks": []
  }
]

🚫 Errors

Every error response shares the same shape:

{
  "object": "error",
  "code": "bad_request",
  "message": "human-readable description of what went wrong"
}

The 401 authentication error additionally includes a location field linking to the API errors reference:

{
  "object": "error",
  "location": "https://www.omise.co/api-errors#authentication-failure",
  "code": "authentication_failure",
  "message": "authentication failed"
}

Only unique error cases are called out again under individual endpoints. Every endpoint can also return 400, 401, and 403, whether or not they're repeated there.

🛠️ Endpoints

Retrieve a template

GET /external/templates/:template_id

Returns the Template object for the specified ID. Find a template's ID on the Payment Links+ dashboard, under Create Template — the 4-digit number shown under each template thumbnail.

Path parameter: template_id (integer, required)

curl 'https://linksplus-api.omise.co/external/templates/3655' \
-X GET \
-h 'Authorization: {{key}}'

Returns: a Template object on success (200):

{
  "id": 3655,
  "name": "Nike Shoes",
  "features": [],
  "capabilities": ["... see The Capability object ..."],
  "zero_interest_installment": false,
  "created_at": "2024-04-17T08:35:55.390Z",
  "updated_at": "2024-04-17T08:35:55.390Z"
}

Unique errors: 404 if the template ID doesn't exist ("message": "template not found").

Retrieve all templates for a team

GET /external/:team_id/templates

Returns the templates belonging to the specified team. Find a team's ID on the dashboard, under Settings > Teams.

Path parameter: team_id (integer, required)

curl 'https://linksplus-api.omise.co/external/3388/templates' \
-X GET \
-h 'Authorization: {{key}}'

Returns: {"templates": [Template, ...], "total": N}:

{
  "templates": [
    {
      "id": 3672,
      "name": "Adidas Bags",
      "features": [
        { "display_name": "Type", "value": null, "type": "string" },
        { "display_name": "Size", "value": null, "type": "string" }
      ],
      "capabilities": [
        "... see The Capability object for the \"card\" entry ...",
        "... a second entry with \"payment_method\": \"promptpay\" ..."
      ],
      "zero_interest_installment": false,
      "created_at": "2024-04-19T10:16:49.689Z",
      "updated_at": "2024-04-19T10:16:49.689Z"
    },
    {
      "id": 3655,
      "name": "Nike Shoes",
      "features": [],
      "capabilities": ["... see The Capability object ..."],
      "zero_interest_installment": false,
      "created_at": "2024-04-17T08:35:55.390Z",
      "updated_at": "2024-04-17T08:35:55.390Z"
    }
  ],
  "total": 2
}

Unique errors: 404 if the team ID doesn't exist ("message": "team not found").

Retrieve a link

GET /external/links/:link_id

Returns the Link object for the specified ID. Click Overview, then a payment link, to find its ID in the dashboard URL.

Path parameter: link_id (integer, required)

curl 'https://linksplus-api.omise.co/external/links/12838' \
-X GET \
-h 'Authorization: {{key}}'

Returns: a Link object on success (200):

{
  "id": 12838,
  "name": "Adidas Bags",
  "state": "active",
  "amount": 200000,
  "currency": "THB",
  "multiple_usage": true,
  "additional": null,
  "expired_at": null,
  "features": {
    "Type": "School Bags",
    "Size": "Medium"
  },
  "transaction_id": "q16j2t7uF2",
  "url": "https://linksplus.omise.co/q16j2t7uF2",
  "template_id": 3672,
  "kind": null,
  "created_at": "2024-04-19T10:58:37.429Z",
  "updated_at": "2024-04-19T10:58:37.429Z"
}

Unique errors: 404 if the link ID doesn't exist ("message": "link not found").

Retrieve all links for a team

GET /external/:team_id/links

Returns the links belonging to the specified team. Find a team's ID on the dashboard, under Settings > Teams.

Path parameter: team_id (integer, required)

curl 'https://linksplus-api.omise.co/external/3388/links' \
-X GET \
-h 'Authorization: {{key}}'

Returns: {"links": [Link, ...], "total": N}:

{
  "links": [
    {
      "id": 12838,
      "name": "Adidas Bags",
      "state": "active",
      "amount": 200000,
      "currency": "THB",
      "multiple_usage": true,
      "additional": null,
      "expired_at": null,
      "features": {
        "Type": "School Bags",
        "Size": "Medium"
      },
      "transaction_id": "q16j2t7uF2",
      "url": "https://linksplus.omise.co/q16j2t7uF2",
      "template_id": 3672,
      "kind": null,
      "created_at": "2024-04-19T10:58:37.429Z",
      "updated_at": "2024-04-19T10:58:37.429Z"
    }
  ],
  "total": 1
}

Unique errors: 404 if the team ID doesn't exist ("message": "team not found").

Create a payment link

POST /external/links

Creates a link from the specified template. If the template has product detail fields configured, you must pass the value of each as a features key/value pair.

Parameters

curl 'https://linksplus-api.omise.co/external/links' \
    -X POST \
    -h 'Authorization: {{key}}' \
    -d "template_id=3672" \
    -d "team_id=3388" \
    -d "name=Adidas School Wear" \
    -d "currency=THB" \
    -d "amount=4000" \
    -d "features[Type]=School Bags" \
    -d "features[Size]=Medium" \
    -d "multiple_usage=true" \
    -d "additional=Order #12345 - priority shipping" \
    -d "expired_at=2026-12-31T23:59:59Z" \
    -d "custom_webhook=https://merchant.com/payment-webhook" \
    -d "returnUrl=https://demostore.com/payment_status"

Both form-encoded (as shown) and raw JSON request bodies work — Postman's Body → raw → JSON mode sends the same fields as a nested JSON object instead of -d flags.

Returns: a Link object on success (201):

{
  "id": 12840,
  "name": "Adidas School Wear",
  "state": "active",
  "amount": 4000,
  "currency": "THB",
  "multiple_usage": true,
  "additional": "Order #12345 - priority shipping",
  "expired_at": "2026-12-31T23:59:59Z",
  "features": {
    "Type": "School Bags",
    "Size": "Medium"
  },
  "transaction_id": "lNeJd4VbUI",
  "url": "https://linksplus.omise.co/lNeJd4VbUI",
  "template_id": 3672,
  "kind": null,
  "created_at": "2024-04-20T12:23:39.321Z",
  "updated_at": "2024-04-20T12:23:39.321Z"
}

Unique errors: 400 if the template has product detail fields but a required features key is missing ("message": "invalid features. \"Date\" is required").

Webhook configuration

Payment Links+ supports up to three webhook endpoints per payment:

• Default System Webhook — configured automatically by Payment Links+.
• Dashboard Webhook — configured in your Merchant Dashboard and fetched automatically.
• Custom API Webhook — set per link via custom_webhook (v3.10.0+).

Update a link

PUT /external/links/:link_id

Updates an existing link. Every body field is optional — send only what you want to change.

Path parameter: link_id (integer, required)

Parameters

curl 'https://linksplus-api.omise.co/external/links/789' \
    -X PUT \
    -h 'Authorization: {{key}}' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "Updated Payment for Order #12345",
      "amount": 15000,
      "expired_at": "2026-12-31T23:59:59Z"
    }'

Returns: the updated Link object on success (200):

{
  "id": 789,
  "name": "Updated Payment for Order #12345",
  "state": "active",
  "amount": 15000,
  "currency": "THB",
  "multiple_usage": false,
  "additional": null,
  "expired_at": "2026-12-31T23:59:59Z",
  "features": {},
  "transaction_id": "wz4qSdsqCG",
  "url": "https://linksplus.omise.co/wz4qSdsqCG",
  "template_id": 2615,
  "kind": null,
  "created_at": "2024-09-30T06:21:37.251Z",
  "updated_at": "2024-10-01T09:26:21.416Z"
}

Unique errors: 404 if the link ID doesn't exist.

💳 Tracking payments after creating a link

Once you've created a link, send its url to the customer to complete the payment.

Finding a charge on the Omise dashboard

After a customer attempts or completes a transaction, find the matching charge using either the link's id or its features:

1. Go to Charges on the Omise Payments dashboard.
2. Select Advanced Search.
3. Choose Metadata as the filter.
4. Enter the id or features value from the API response.

❓ FAQ

Q: Does the create-link endpoint accept JSON, or only form-encoded data? A: Both. Send parameters as form-encoded -d fields in curl, or as a raw JSON body — Postman's Body → raw → JSON mode works the same way.

Q: What format does expired_at expect? A: The same on both endpoints — an ISO 8601 date-time string with any timezone offset (e.g. 2026-12-31T23:59:59Z), stored and returned in UTC, and must be a future date.

Q: Can I change which team a link belongs to? A: No. team_id is required when creating a link but isn't accepted when updating one — a link can't move between teams after creation.

Q: I passed a features value and still got a validation error. Why? A: The keys must exactly match the product detail field names configured on the template, not any name you choose. Check the template's configuration in Create Template on the dashboard for the exact field names.

Q: What values can a link's state have? A: active, expired, or used — see The Link object.

Q: I don't see a charge on the Omise dashboard right after creating a link. Is something wrong? A: No — a charge only appears there once the customer attempts the transaction. It appears immediately on the Payment Links+ dashboard.

Q: How do I set a custom webhook without going through the dashboard? A: Pass a HTTPS URL in custom_webhook when creating the link — see Webhook configuration.

👉 Related content

• Payment Links+ product page