When using Payiano's APIs, it's essential to authenticate each request with a
set of unique API credentials that are linked to your Payiano account. This
process begins with registering an App on your Payiano dashboard, which
is a necessary step to obtain these credentials. Once your App is registered, it acts as a
bridge between you and the Payiano API, allowing you to perform a variety of
functions relevant to your business needs.
For instance, your App can send Payment Links, list Tax information, access account Balances, modify product details, add shipping methods, or manage Customers data. The versatility of the app is further enhanced by its customizable settings, which include
setting up the webhook URL, success redirect URL, failed redirect URL, and defining the scope of
permissions it has. This level of customization ensures that you can tailor the app to suit a wide
range of tasks, enabling efficient and effective interaction with your Payiano
account through the API, thereby streamlining various aspects of your business operations.
GET/app/whoami
Sandbox: https://api.payiano.dev/v1/app/whoami
Live: https://api.payiano.com/v1/app/whoami
Security
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
A list of additional app relations to return, if available. Feel free
to send the relations you would like to return with every item. See Including Resources to better understand how this is working.
Response
200
Response schema:
application/json
Response body:
app
app
Type: object
The app model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each app which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every app. This ULID is
automatically created by our system and is used to uniquely identify
and track each app in our database.
name
name
Type: string
Min: 2
Max: 255
This attribute represents the app's name. It's 'a crucial identifier
for the app within the ecosystem. The name should be descriptive and
concise, reflecting the app's purpose or functionality. It's essential
to ensure that each app has a distinct name to avoid conflicts and
confusion when used. Please notice that duplicate values are not
allowed and it's allowed to use alpha dash only [A-Za-z0-9-_].
key
key
Type: string
This attribute is a unique identifier for your application.
When your app communicates with Payiano's APIs,
the app key is often used to identify the app making the request.
This key is typically public, meaning it's visible to both
the app and the server it's communicating with, but it doesn't give
away any sensitive information about your app. It's used in conjunction
with the app secret for a more secure authentication process.
token
token
Type: string
This attribute is a confidential piece of information, akin to a password
for your application. It is used to authenticate the identity of the
application to the Payiano's API. This token should
be kept private and secure, as it allows access to the API
and other critical functions. If someone else obtains your app token, they
could potentially misuse your application's identity to access sensitive
data or resources.
platform
platform
Type: string|null
Min: 2
Max: 255
The platform field specifies the target platform or environment for
which the app is designed, like Shopify, Wordpress, iOS, Android, or
web. This attribute helps in categorizing the app and can be used to
filter or tailor the app's behavior based on the platform it is meant
to interact with. The optional nature of this attribute allows for
flexibility in cases where the app is platform-agnostic.
is_active
is_active
Type: boolean
Default: true
This value indicates whether the app is active or not. This flag can be used
to control the app's availability in runtime environments or listings without
deleting or removing the app from records. A true value means the app
is active and functioning, while a false value implies that the app is
deactivated or not in use.
error_redirect_url
error_redirect_url
Type: url|null
Max: 1000
This attribute specifies the URL to which a user is redirected to in case of a failure in the
checkout's process. It is used for error handling and user experience improvement, allowing users
to be informed and take appropriate actions in case of a process failure. The URL should be
carefully crafted to provide useful information or alternatives to the user following a
failure event.
success_redirect_url
success_redirect_url
Type: url|null
Max: 1000
Similar to error_redirect_url, this attribute defines the URL where users are redirected
after a successful operation or transaction within the checkout. It's a critical part of user
experience, ensuring users are guided to the correct next step or confirmation page after a
successful interaction.
webhook_urls_count
webhook_urls_count
Type: integer
This attribute shows the number of direct webhook URLs associated
with the app.
webhook_urls
webhook_urls
Type: array_of_objects
The assigned webhook URLs models to the app.
id
id
Type: ulid
Length: 26
The unique ID assigned to each webhook URL which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every webhook URL. This ULID is
automatically created by our system and is used to uniquely identify
and track each webhook URL in our database.
url
url
Type: url
Max: 1000
This attribute specifies the endpoint where the webhook notifications will
be sent. This should be a valid URL that points to the server or service
that will handle the incoming webhook requests allowing the merchant to
handle these events programmatically.
name
name
Type: string
Min: 1
Max: 50
This attribute is a human-readable identifier for the webhook URL. This
attribute helps users distinguish between different webhook endpoints by
providing a clear, descriptive name (e.g., "Sandbox Server", "Production
Server"). It is useful for organizational purposes and does not impact the
functionality of the webhook. Please notice that duplicate values are
not allowed and it's allowed to use alpha dash only [A-Za-z0-9-_ ].
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each webhook URL. It's
primary role is to distinguish one webhook URL from another, ensuring
that each webhook URL can be individually tracked and managed without
any confusion. Please notice that duplicate values are not allowed
and it's allowed to use alpha dash only [A-Za-z0-9-_]. The reference_id
value is used to Identify Resource when you consume any webhook URL endpoint with sending identify_by
query parameter with value reference_id.
is_active
is_active
Type: boolean
Default: true
This value indicates whether the webhook URL is active or not. This flag can be used
to control the webhook URL's availability in runtime environments or listings without
deleting or removing the webhook URL from records. A true value means the webhook URL
is active and functioning, while a false value implies that the webhook URL is
deactivated or not in use.
signature_secret
signature_secret
Type: string
This attribute holds the secret key used to generate the HMAC
signature for the webhook event payload. This key is unique to each
webhook URL and is used to ensure the integrity and authenticity of the webhook
event. It should be kept private and secure and only known to the
receiving server and authorized parties. This secret key is important for
verifying that the payload has not been tampered with and that it indeed comes from
Payiano. Please note this value is retrievable in the sandbox
environment only, and it will be masked in the production environment.
employee_actions_enabled
employee_actions_enabled
Type: boolean
Default: false
This attribute indicates whether the webhook should fire events
when employees perform certain actions, such as creating a new
resource or updating an existing one. If true, events will
be triggered for these actions. If false, such events will
not trigger the webhook for employee actions.
apps_count
apps_count
Type: integer
This field shows the number of apps associated with the webhook URL.
event_types_count
event_types_count
Type: integer
This field shows the number of events associated with the webhook URL.
event_types
event_types
Type: array_of_objects
The assigned webhook event types models to webhook URL.
name
name
Type: enum
Possible values:
["payment_link.created","checkout.created"]
This attribute specifies the unique identifier for that particular
event. This name is used to distinguish between different types of
events that the webhook can handle (e.g., payment_link.created,
checkout.created). Each event name corresponds to a specific
action or occurrence that the webhook is intended to monitor.
metadata
metadata
Type: object|null
The webhook URL metadata model details. Metadata serves as a tool
for keeping extra, organized details about a resource. For example,
you can use it to store a user's preferences like prefered color,
notes or any other data that aids in personalizing services, improving
customer relations, or optimizing internal workflows. This information
isn't utilized by Payiano – meaning it's not
involved in authorizing or declining transactions and remains invisible
to your users. Its value is entirely private for your internal
use, and we ensure it remains confidential, not shared with any
external parties.
info
info
Type: array_of_objects
Max: 50
This array consists of objects, each containing a key and a value.
These pairs of key-value are structured in a way that's more suitable
for programmatic access. You can add up to 50 objects.
key
key
Type: string
Min: 1
Max: 50
It's a unique identifier to avoid confusion or data overlap.
The keys serve as identifiers for the corresponding values, making
it easier to retrieve specific pieces of information as needed.
value
value
Type: string
Min: 1
Max: 255
The value is the actual data associated with that key. It could be
a simple string, a number, a URL, or any other data format that
conveys the necessary information.
list
list
Type: array_of_strings
Max: 50
The list attribute is particularly useful for scenarios where
the data needs to be presented in a straightforward, unstructured
format. It's ideal for quick overviews, simple data logging, or
when the information does not require the more complex organization
that nested JSON objects provide. Please
notice that duplicate values are not allowed, you can add up
to 50 item and the max list item length is 255
characters.
is_deleted
is_deleted
Type: boolean
Default: false
This value indicates whether the webhook URL is deleted or not. This flag can be used to
control the webhook URL's availability in runtime without actual deleting or removing the
webhook URL from records. A true value means the webhook URL is deleted, while a false
value implies that the webhook URL is not deleted and functioning.
created_at
created_at
Type: datetime
The created datetime of the webhook URL.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the webhook URL.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
deleted_at
deleted_at
Type: datetime|null
The deleted datetime of the webhook URL.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
description
description
Type: string|null
Max: 10000
This attribute is for a textual description of the app. It can
include information about the app's purpose, features, usage
instructions, and any other relevant details. This description
is valuable for administrative purposes and for providing other
developers with an overview of what the app does.
permissions_count
permissions_count
Type: integer
This attribute shows the number of permissions granted to the app.
permissions
permissions
Type: array_of_objects
The assigned permission models to role.
name
name
Type: string
This attribute is the unique permission name. It is used to identify the exact access
allowed for a company employee or company app. This means it helps in specifying what each
employee or app can do or see within the company's system.
is_app
is_app
Type: boolean
This attribute specifies the scope of the permission. When set to true,
the permission can be assigned to both any app and any company employee.
If set to false, the permission is restricted and can only be only
assigned to company employees.
created_at
created_at
Type: datetime
The created datetime of the app.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the app.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.