Payment Links+

このページで扱うトピック

Authorization
Objects and Endpoints
Retrieve a template
Retrieve all templates for a team
Retrieve a link
Retrieve all links for a team
Create a Payment Link

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. Start selling quickly with Payment Links+ and enjoy a seamless omnichannel experience. To learn more, check out Payment Links+ today!

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.

Objects and Endpoints

Object	Endpoint
template Retrieve link templates. Transform your links with customizable templates and enhance your organization's branding. With the option for each team to have its templates, your payment links can have a unified and professional look across all teams while catering to each team's unique requirements.	GET /external/templates/:template_id GET /external/:team_id/templates
link Streamline your payment process with custom links created specifically for your team's unique requirements. Maintain a consistent and professional look across your organization while offering a seamless payment experience for your customers. With our easy-to-use platform, retrieving and sharing your payment links has never been easier.	GET /external/links/:link_id GET /external/:team_id/links POST /external/links

Retrieve a template

Returns the template definition for the specified template ID.

The template ID is displayed on the Payment Links+ dashboard.

Template retrieval example call

Curl Example:

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

Retrieve the template with ID 3655.

Template retrieval parameters

[Required] template_id
integer
The ID of the template to retrieve.

Response on Success

{
    "object": "template",
    "id": 3655,
    "team_id": 3388,
    "created_by": 3590,
    "name": "Nike Shoes",
    "language": "th",
    "status": "active",
    "features": [],
    "capabilities": [
        {
            "payment_method": "card",
            "currencies": [
                "THB",
                "JPY",
                "USD",
                "EUR",
                "GBP",
                "SGD",
                "AUD",
                "CHF",
                "CNY",
                "DKK",
                "HKD",
                "MYR"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "internet_banking_bbl",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "promptpay",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        }
    ],
    "zero_interest_installment": false,
    "created_at": "2024-04-17T08:35:55.390Z",
    "updated_at": "2024-04-17T08:35:55.390Z"
}

Template retrieval response codes

Code	Example
200 - OK	See Response on Success
400 - Bad Request Check whether the template ID is an integer.	{ "object": "error", "code": "bad_request", "message": "\"template_id\" must be a number" }
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether the template ID is valid.	{ "object": "error", "code": "not_found", "message": "template not found" }

Retrieve all templates for a team

Returns the list of templates for the provided team ID.

To view the team ID, navigate to Team Settings on the Payment Links+ dashboard.

Team templates example call

Curl Example:

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

Retrieve all templates for the team with ID 3388.

Team templates parameters

[Required] team_id integer
The ID of the team for which to retrieve the templates.

Response on Success

{
    "object": "list",
    "offset": 0,
    "limit": 0,
    "total": 2,
    "order": "reverse_chronological",
    "data": [
        {
            "object": "template",
            "id": 3672,
            "team_id": 3388,
            "created_by": 3590,
            "name": "Adidas Bags",
            "language": "th",
            "status": "active",
            "features": [
                {
                    "display_name": "Type: School Bags",
                    "value": null,
                    "type": "string"
                },
                {
                    "display_name": "Size: Medium",
                    "value": null,
                    "type": "string"
                }
            ],
            "capabilities": [
                {
                    "payment_method": "card",
                    "currencies": [
                        "THB",
                        "JPY",
                        "USD",
                        "EUR",
                        "GBP",
                        "SGD",
                        "AUD",
                        "CHF",
                        "CNY",
                        "DKK",
                        "HKD",
                        "MYR"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "internet_banking_bbl",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "truemoney",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "truemoney_jumpapp",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                }
            ],
            "zero_interest_installment": false,
            "created_at": "2024-04-19T10:16:49.689Z",
            "updated_at": "2024-04-19T10:16:49.689Z"
        },
        {
            "object": "template",
            "id": 3655,
            "team_id": 3388,
            "created_by": 3590,
            "name": "Nike Shoes",
            "language": "th",
            "status": "active",
            "features": [],
            "capabilities": [
                {
                    "payment_method": "card",
                    "currencies": [
                        "THB",
                        "JPY",
                        "USD",
                        "EUR",
                        "GBP",
                        "SGD",
                        "AUD",
                        "CHF",
                        "CNY",
                        "DKK",
                        "HKD",
                        "MYR"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "internet_banking_bbl",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "promptpay",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                }
            ],
            "zero_interest_installment": false,
            "created_at": "2024-04-17T08:35:55.390Z",
            "updated_at": "2024-04-17T08:35:55.390Z"
        }
    ]
}

Team templates response codes

Code	Example
200 - OK	See Response on Success
400 - Bad Request Check whether the team ID is an integer.	{ "object": "error", "code": "bad_request", "message": "\"team_id\" must be a number" }
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether the team ID is valid.	{ "object": "error", "code": "not_found", "message": "team not found" }

Retrieve a link

Retrieves the details for the link with the provided link ID.

Click Overview and then a payment link to view the link ID on the dashboard URL.

Link retrieval example call

Curl Example:

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

Retrieve a link with ID 12838.

Link retrieval parameters

[Required] link_id integer
The ID of the link to retrieve.

Response on Success

{
    "object": "link",
    "id": 12838,
    "team_id": 3388,
    "created_by": 3590,
    "name": "Adidas Bags",
    "state": "active",
    "status": "active",
    "amount": 200000,
    "currency": "THB",
    "multiple_usage": true,
    "additional": null,
    "transaction_url": "https://linksplus.omise.co/q16j2t7uF2",
    "transaction_id": "q16j2t7uF2",
    "features": {
        "Type: School Bags": "Type: School Bags",
        "Size: Medium": "Size: Medium"
    },
    "capabilities": [
        {
            "payment_method": "card",
            "currencies": [
                "THB",
                "JPY",
                "USD",
                "EUR",
                "GBP",
                "SGD",
                "AUD",
                "CHF",
                "CNY",
                "DKK",
                "HKD",
                "MYR"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "internet_banking_bbl",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "truemoney",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "truemoney_jumpapp",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        }
    ],
    "company": {
        "object": "company",
        "default_locale": "en"
    },
    "template": {
        "object": "template"
    },
    "expired_at": "2024-06-19T18:30:00.000Z",
    "created_at": "2024-04-19T10:58:37.429Z",
    "updated_at": "2024-04-19T10:58:37.429Z",
    "returnUrl": ""
}

Link retrieval response codes

Code	Example
200 - OK	See Response on Success
400 - Bad Request Check whether the link ID is an integer.	{ "object": "error", "code": "bad_request", "message": "\"link_id\" must be a number" }
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether the link ID is valid.	{ "object": "error", "code": "not_found", "message": "link not found" }

Retrieve all links for a team

Returns the list of links for the provided team ID.

To view the team ID, navigate to Team Settings on the Payment Links+ dashboard.

Team links example call

Curl Example:

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

Retrieve all templates for the team with ID 3388.

Team links parameters

[Required] team_id integer
The ID of the team for which to retrieve the links.

Response on Success

{
    "object": "list",
    "offset": 0,
    "limit": 30,
    "total": 2,
    "order": "reverse_chronological",
    "data": [
        {
            "object": "link",
            "id": 12838,
            "team_id": 3388,
            "created_by": 3590,
            "name": "Adidas Bags",
            "state": "active",
            "status": "active",
            "amount": 200000,
            "currency": "THB",
            "multiple_usage": true,
            "additional": null,
            "transaction_url": "https://linksplus.omise.co/q16j2t7uF2",
            "transaction_id": "q16j2t7uF2",
            "features": {
                "Type: School Bags": "Type: School Bags",
                "Size: Medium": "Size: Medium"
            },
            "capabilities": [
                {
                    "payment_method": "card",
                    "currencies": [
                        "THB",
                        "JPY",
                        "USD",
                        "EUR",
                        "GBP",
                        "SGD",
                        "AUD",
                        "CHF",
                        "CNY",
                        "DKK",
                        "HKD",
                        "MYR"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "internet_banking_bbl",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "truemoney",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "truemoney_jumpapp",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                }
            ],
            "company": {
                "object": "company",
                "default_locale": "en"
            },
            "template": {
                "object": "template"
            },
            "expired_at": "2024-06-19T18:30:00.000Z",
            "created_at": "2024-04-19T10:58:37.429Z",
            "updated_at": "2024-04-19T10:58:37.429Z",
            "returnUrl": ""
        },
        {
            "object": "link",
            "id": 12781,
            "team_id": 3388,
            "created_by": 3590,
            "name": "Nike Payment",
            "state": "active",
            "status": "active",
            "amount": 300000,
            "currency": "THB",
            "multiple_usage": true,
            "additional": null,
            "transaction_url": "https://linksplus.omise.co/1gX5ceiFR8",
            "transaction_id": "1gX5ceiFR8",
            "features": {},
            "capabilities": [
                {
                    "payment_method": "card",
                    "currencies": [
                        "THB",
                        "JPY",
                        "USD",
                        "EUR",
                        "GBP",
                        "SGD",
                        "AUD",
                        "CHF",
                        "CNY",
                        "DKK",
                        "HKD",
                        "MYR"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "internet_banking_bbl",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                },
                {
                    "payment_method": "promptpay",
                    "currencies": [
                        "THB"
                    ],
                    "card_brands": [
                        "JCB",
                        "Visa",
                        "MasterCard"
                    ],
                    "installment_terms": [],
                    "banks": []
                }
            ],
            "company": {
                "object": "company",
                "default_locale": "en"
            },
            "template": {
                "object": "template"
            },
            "created_at": "2024-04-17T08:36:50.320Z",
            "updated_at": "2024-04-17T08:36:50.320Z",
            "returnUrl": ""
        }
    ]
}

Team links response codes

Code	Example
200 - OK	See Response on Success
400 - Bad Request Check whether the team ID is an integer.	{ "object": "error", "code": "bad_request", "message": "\"team_id\" must be a number" }
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether the team ID is valid.	{ "object": "error", "code": "not_found", "message": "team not found" }

Create a Payment Link

Creates a Payment Link based on the template ID that you specify. If the template contains features, you must enter the value of each feature as a key:value pair.

Create link example call

Curl Example:

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 "returnUrl=https://demostore.com/payment_status"

The corresponding template with ID 3672, has Type and Size as features that you must specify.

Create link parameters

[Required] template_id integer
The ID of the template to use for creating the link.

[Required] team_id integer
The ID of the team for which to create the link.

[Required] name string
The name of the link to create.

[Optional] currency string
The currency of the payment. Defaults to the currency mentioned in the template (THB).

[Required] amount integer
The amount to pay.

[Optional] multiple_usage boolean
Can you use the link multiple times, or is it only for a one-time payment? The default is the setting mentioned in the template.

[Conditionally Required] features object
The value of the features mentioned in the template, if any. Pass them as key:value pairs. Required only if the template contains features.

[Optional] returnUrl string
The URL to redirect users to after payment completion. This field follows a priority hierarchy: 1) Link-level returnUrl (specified in this API call), 2) Template-level returnUrl (configured in the dashboard), 3) Account-level returnUrl (configured in Settings > Return URL). If the returnUrl is not configured at any level, then the redirect button will not appear on the payment success page.

Response on Success

{
    "object": "link",
    "id": 12840,
    "team_id": 3388,
    "created_by": null,
    "name": "Adidas School Wear",
    "state": "active",
    "status": "active",
    "amount": 2000,
    "currency": "THB",
    "multiple_usage": true,
    "additional": null,
    "transaction_url": "https://linksplus.omise.co/lNeJd4VbUI",
    "transaction_id": "lNeJd4VbUI",
    "features": {
        "Type": "School Bags",
        "Size": "Medium"
    },
    "capabilities": [
        {
            "payment_method": "card",
            "currencies": [
                "THB",
                "JPY",
                "USD",
                "EUR",
                "GBP",
                "SGD",
                "AUD",
                "CHF",
                "CNY",
                "DKK",
                "HKD",
                "MYR"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "internet_banking_bbl",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "truemoney",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        },
        {
            "payment_method": "truemoney_jumpapp",
            "currencies": [
                "THB"
            ],
            "card_brands": [
                "JCB",
                "Visa",
                "MasterCard"
            ],
            "installment_terms": [],
            "banks": []
        }
    ],
    "company": {
        "object": "company",
        "id": 569,
        "name": "Demo Store",
        "description": "Demo Store Selling Shoes",
        "primary email": "demostore@demostore.org",
        "logo": "https://linkplus-cdn.omise.co/merchants/569/17131610439-download.png",
        "refund_policy": null,
        "background_color": "#0F3AAA",
        "text_color": "#FFFFFF",
        "webhook": "https://linksplus-api.omise.co/api/hooks/569/9e09f4dbde1e8fe47ba",
        "updated_at": "2024-04-15T06:04:58.363Z",
        "created_at": "2024-04-15T06:04:09.834Z",
        "default_locale": "en",
        "review_status": "approved",
        "backgroundColor": "#0F3AAA",
        "buttonColor": "#FFFFFF",
        "createdAt": "2024-04-15T06:04:09.834Z",
        "updatedAt": "2024-04-15T06:04:58.363Z",
        "onboarded": true,
        "return_url": ""
    },
    "created_at": "2024-04-20T12:23:39.321Z",
    "updated_at": "2024-04-20T12:23:39.321Z",
    "returnUrl": "https://demostore.com/payment_status"
}

Create link response codes

Code	Example
200 - OK	See Response on Success
400 - Bad Request Check whether the parameters entered are valid.	{ "object": "error", "code": "bad_request", "message": "syntax error" }
401 - Unauthorized Check whether the authentication key is valid.	{ "object": "error", "location": "https://www.omise.co/api-errors#authentication-failure", "code": "authentication_failure", "message": "authentication failed" }
404 - Not found Check whether you have missed passing any required parameters.	{ "object": "error", "code": "not_found", "message": "template not found" }