If you have a few taxes, it's easy to create and manage them in the
Payiano Dashboard or thorugh the API. These Taxes
can then be applied to various transactions in Payiano
Payment Links, Invoices and Orders. Here, you can create and apply these
taxes to your business transactions. It's important to create a catalog of
taxes that comply with the tax laws of the country where your business operates.
Note that once set, you can't change the value , value_type , type , strategy , or country_code properties. To update these, you'll need to create a new tax and archive the old one.
POST/taxes
Sandbox: https://api.payiano.dev/v1/taxes
Live: https://api.payiano.com/v1/taxes
Security
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission taxes_create
Request
Request body schema:
application/json
Query parameters:
includes
includes
Type: array_of_enums|null
Possible values:
["tax.metadata"]
A list of additional tax 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.
Request body:
name
required
name
required
Type: string
Min: 2
Max: 255
The name is a clear label that quickly tells the person paying the
payment what the tax is about. It's a customer-facing term used to
identify and explain the taxes on various transaction-related documents
and platforms. It's important for this name to be clear and descriptive,
as it aids in ensuring transparency and understanding for the customer
regarding the taxes applied to their purchase or service.
value
required
value
required
Type: decimal
Min: 0.01
Max: 9999999 when value_type is FLAT and 10000 when the
value_type is PERCENTAGE.
The tax amount value. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
value_type
required
value_type
required
Type: enum
Possible values:
["PERCENTAGE","FLAT"]
The tax value type.
type
required
type
required
Type: enum
Possible values:
["AMUSEMENT_TAX","SALES_TAX","SERVICE_TAX","VAT"]
Each of these taxes is specific to certain types of transactions and is subject to the
prevailing laws and regulations of that region. Businesses operating in multiple regions
or countries often need to manage several of these tax types concurrently.
AMUSEMENT_TAX:
A tax levied on the fees charged for entertainment or amusement services.
This could be applied to movie tickets, theme park entries, etc.
SALES_TAX:
A general tax on the sale of goods and services, usually calculated as a percentage
of the purchase price.
VAT:
A consumption tax placed on a product whenever value is added at each stage of the supply
chain, from production to the point of sale.
strategy
required
strategy
required
Type: enum
Possible values:
["EXCLUSIVE","INCLUSIVE"]
Determines if the tax is calculated as part of the total amount or added on top.
The total amount payable by a customer varies significantly based on whether a tax
rate is inclusive or exclusive.
EXCLUSIVE:
Added to the subtotal, increasing the final amount the customer pays.
INCLUSIVE:
Included within the listed price, not increasing the final amount but reducing the net
revenue you receive.
A 20% tax will have a different impact on the total charge amount, depending
on its inclusivity. In an exclusive scenario, it adds to the customer's cost, while
in an inclusive scenario, it's a part of the already stated price.
Scenario: Selling a Product for $100 with 20% Tax
Tax Value
Total
Exclusive
20% of $100 = $20
$120
Inclusive
$100 - ( $100 / 1.20 ) = $16.67
$100
country_code
required
country_code
required
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where your tax was officially registered. This code is part of the standard
international country codes set by the ISO .
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each tax. It's
primary role is to distinguish one tax from another, ensuring
that each tax 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 tax endpoint with sending identify_by
query parameter with value reference_id.
is_active
is_active
Type: boolean
Default: true
This value indicates whether the tax is active or not. This flag can be used
to control the tax's availability in runtime environments or listings without
deleting or removing the tax from records. A true value means the tax
is active and functioning, while a false value implies that the tax is
deactivated or not in use.
description
description
Type: string|null
Min: 2
Max: 255
It provides clear, concise details about what the tax is for.
It serves as an identifier or reference that helps in organizing,
tracking, or categorizing taxes internally. This string will not
be shown to customers.
metadata
metadata
Type: object|null
The tax 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
required
key
required
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
required
value
required
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.
Response
201
Response schema:
application/json
Response body:
tax
tax
Type: object
The tax model details.
id
id
Type: ulid
Length: 26
The unique ID assigned to each tax 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 tax. This ULID is
automatically created by our system and is used to uniquely identify
and track each tax in our database.
name
name
Type: string
Min: 2
Max: 255
The name is a clear label that quickly tells the person paying the
payment what the tax is about. It's a customer-facing term used to
identify and explain the taxes on various transaction-related documents
and platforms. It's important for this name to be clear and descriptive,
as it aids in ensuring transparency and understanding for the customer
regarding the taxes applied to their purchase or service.
value
value
Type: decimal
Min: 0.01
Max: 9999999 when value_type is FLAT and 10000 when the
value_type is PERCENTAGE.
The tax amount value. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.
value_type
value_type
Type: enum
Possible values:
["PERCENTAGE","FLAT"]
The tax value type.
type
type
Type: enum
Possible values:
["AMUSEMENT_TAX","SALES_TAX","SERVICE_TAX","VAT"]
Each of these taxes is specific to certain types of transactions and is subject to the
prevailing laws and regulations of that region. Businesses operating in multiple regions
or countries often need to manage several of these tax types concurrently.
AMUSEMENT_TAX:
A tax levied on the fees charged for entertainment or amusement services.
This could be applied to movie tickets, theme park entries, etc.
SALES_TAX:
A general tax on the sale of goods and services, usually calculated as a percentage
of the purchase price.
VAT:
A consumption tax placed on a product whenever value is added at each stage of the supply
chain, from production to the point of sale.
strategy
strategy
Type: enum
Possible values:
["EXCLUSIVE","INCLUSIVE"]
Determines if the tax is calculated as part of the total amount or added on top.
The total amount payable by a customer varies significantly based on whether a tax
rate is inclusive or exclusive.
EXCLUSIVE:
Added to the subtotal, increasing the final amount the customer pays.
INCLUSIVE:
Included within the listed price, not increasing the final amount but reducing the net
revenue you receive.
A 20% tax will have a different impact on the total charge amount, depending
on its inclusivity. In an exclusive scenario, it adds to the customer's cost, while
in an inclusive scenario, it's a part of the already stated price.
Scenario: Selling a Product for $100 with 20% Tax
Tax Value
Total
Exclusive
20% of $100 = $20
$120
Inclusive
$100 - ( $100 / 1.20 ) = $16.67
$100
country_code
country_code
Type: string
Specify the unique two-letter country code ( e.g EG, SA or AE )
corresponding to the country where your tax was officially registered. This code is part of the standard
international country codes set by the ISO .
reference_id
reference_id
Type: string|null
Max: 50
It's a unique identifier assigned to each tax. It's
primary role is to distinguish one tax from another, ensuring
that each tax 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 tax endpoint with sending identify_by
query parameter with value reference_id.
is_active
is_active
Type: boolean
Default: true
This value indicates whether the tax is active or not. This flag can be used
to control the tax's availability in runtime environments or listings without
deleting or removing the tax from records. A true value means the tax
is active and functioning, while a false value implies that the tax is
deactivated or not in use.
description
description
Type: string|null
Min: 2
Max: 255
It provides clear, concise details about what the tax is for.
It serves as an identifier or reference that helps in organizing,
tracking, or categorizing taxes internally. This string will not
be shown to customers.
metadata
metadata
Type: object|null
The tax 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.
created_at
created_at
Type: datetime
The created datetime of the tax.
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 tax.
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.
Response sample:
1{2"tax": {3"id": "01hqh45s7826hfwdze8dp1z21f",4"name": "Value added tax",5"value": 14,6"value_type": "PERCENTAGE",7"type": "VAT",8"strategy": "EXCLUSIVE",9"country_code": "EG",10"reference_id": "b438800f-9e32-36a1-aee8-725aca982cc7",11"is_active": true,12"description": "The value added tax",13"metadata": {14"info": [15{16"key": "Company name",17"value": "Pyngy"18}19],20"list": [21"Cairo, Nasr City, 7th District, Building 12 floor 5"22]23},24"created_at": "1722572118554",25"updated_at": "1722572118554"26}27}