Programmatic Checkout

The Payiano JavaScript SDK exposes the PayianoPayButton class, which lets you open the checkout modal entirely from JavaScript. Unlike the HTML element approach, the programmatic API does not render a button for you. Instead, you decide exactly when, where, and how the checkout is triggered. This makes it perfect for custom button designs, conditional payment flows, and single-page applications.

For an overview of all integration approaches, see the Pay Button page.

Setup

1. Include the Payiano Script

Load the Payiano JavaScript library the same way as the HTML element approach.

2. Create the PayianoPayButton Instance

Instantiate PayianoPayButton with your company's public key.

Constructor Options

public_key `required`	public_key `required` Type: `string` Your company's public key, which uniquely identifies your merchant account and authenticates every checkout session. This key is safe to expose in client-side code because it can only be used to create checkout sessions and cannot read or modify account data. You can find and rotate your public key in the Developer section of your Payiano dashboard.
debug	debug Type: `boolean` When set to true, the SDK logs detailed information about the checkout lifecycle to the browser console, including iframe creation, message passing, and error details. This is invaluable during development and should be disabled in production. Defaults to false.

openCheckout

Call openCheckout() on the instance to immediately open the checkout modal.

Options

resource_name

required

resource_name

required

Type: enum

Possible values:

JSON

[ "payment.payment_link", "payment.checkout" ]

Identifies the type of Payiano resource to collect payment for. This tells the checkout modal which API resource to load so it can display the correct amount, currency, and payment details to the customer.

resource_id

required

resource_id

required

Type: ulid

The unique identifier of the specific resource instance to pay for. For payment links, this is the ID returned in the API response when you create a payment link. Each checkout should reference the correct resource ID so the modal can load the right payment details and process the transaction successfully.

locale

Type: object

Locale configuration object that controls the language of the entire checkout interface, including labels, input placeholders, validation messages, and error text.

code

Type: string

Possible values:

JSON

[ "ar", "en" ]

The language code for the checkout interface, including all labels, input placeholders, validation messages, and error text. Choosing the correct locale ensures customers see the checkout in their preferred language, which improves conversion rates.

theme

Type: object

Theme configuration object that controls the visual appearance of the checkout modal so it blends seamlessly with your website's design.

mode	mode Type: `string` Possible values: JSON [ "light", "dark" ] Controls the visual appearance of the checkout modal. Use light for light-background sites and dark for dark-background sites to maintain a consistent look and feel with your website's design.

onReady

Type: callback

A callback function invoked once the checkout modal has fully loaded and is ready for customer interaction. Use this to hide a custom loading spinner, fire an analytics event, or perform any post-load logic in your application.

onError

Type: callback

A callback function invoked when an error occurs during the checkout lifecycle. The function receives an error object with a type property (a machine-readable error code such as invalid_public_key or network_error) and a message property (a human-readable description). Use this to display user-friendly error messages or log issues for debugging.

Error Types

The following error types may be passed to the onError callback. Each error object contains a type property set to one of the values below and a human-readable message property.

Error Types Reference

invalid_checkout_params	invalid_checkout_params Type: `string` One or more required checkout parameters are missing or malformed. Verify that resource_name, resource_id, and public_key are all provided and correctly formatted.
invalid_resource_name	invalid_resource_name Type: `string` The supplied resource_name does not match any supported resource type. Check the allowed values in the resource_name parameter documentation.
invalid_resource_id	invalid_resource_id Type: `string` The supplied resource_id is not a valid ULID or does not correspond to an existing resource. Ensure the ID was copied correctly from the API response.
invalid_public_key	invalid_public_key Type: `string` The public_key is missing, expired, or does not belong to an active merchant account. Verify the key in your Payiano dashboard.
invalid_pay_request	invalid_pay_request Type: `string` The payment request could not be created on the server. This usually means the referenced resource is in an unpayable state (e.g. already paid, expired, or cancelled).
invalid_iframe_origin	invalid_iframe_origin Type: `string` The checkout iframe responded from an unexpected origin. This is a security check failure and typically indicates a misconfigured environment or a man-in-the-middle attempt.
network_error	network_error Type: `string` A network request failed, either due to connectivity issues, DNS resolution failure, or a server timeout. Retry the operation or check the customer's internet connection.
unexpected_error	unexpected_error Type: `string` An unexpected error occurred that does not fall into any other category. Check the browser console for additional details and contact support if the issue persists.
unhandled_rejection	unhandled_rejection Type: `string` A JavaScript promise was rejected without a catch handler during the checkout lifecycle. This usually points to a bug in custom callback code. Wrap your callback logic in try/catch blocks to prevent this.

Interactive Playground

Use the controls below to customise the checkout options and see the generated JavaScript update in real time.

Resource Name

payment.payment_link

Resource Name

Resource ID

Public Key

Locale Code

Theme Mode

light

Theme Mode

Debug Mode

The interactive preview loads on the client side.

If you encounter any issues during integration or need further assistance with the provided examples, or have any other inquiries, our team is here to help. Please don't hesitate to contact us . We are committed to ensuring your integration process is smooth and successful.