Update Payment Link Information

With Payiano you can update Payment Links seamlessly. You can make adjustments to certain parts of your existing Payment Links. This means you can keep your Payment Links up-to-date without having to start from scratch each time. Just remember, only specific attributes of the Payment Links can be changed. This restriction is in place because once a Payment Link is created and an invoice is sent to the customer, changing certain details like the payment amount could lead to confusion or compromise the integrity of the data. Keeping some attributes fixed ensures that the payment process remains clear and reliable for both you and your customers. If you need to change the amount on a Payment Link, the best approach is to create a new one. This ensures clarity and accuracy in your transactions.

PUT/payment_links/{id}
Sandbox: https://api.payiano.dev/v1/payment_links/{id}
Live: https://api.payiano.com/v1/payment_links/{id}
Security
  • Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
  • Your access token should be associated to this permission payment_links_update
Request
Request body schema:
application/json
Path parameters:
id
required
Type: ulid
Length: 26

The unique ID assigned to each payment link 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 payment link. This ULID is automatically created by our system and is used to uniquely identify and track each payment link in our database.

Query parameters:
identify_by
Type: enum|null
Possible values:
[
"id", "reference_id" ]

This attribute specifies which identifier is being used to interact with a resource in the Payiano API. It helps the system understand how to identify resource when processing API requests. By default, the identify_by attribute is set to id, so you only need to specify it if you're using a different identifier.

includes
Type: array_of_enums|null
Possible values:
[
"payment_link.payment_details", "payment_link.payment_details.taxes", "payment_link.payment_details.taxes.metadata", "payment_link.customer", "payment_link.customer.tags", "payment_link.customer.tags.metadata", "payment_link.customer.metadata", "payment_link.customer.billing_address", "payment_link.customer.billing_address.country", "payment_link.customer.shipping_address", "payment_link.customer.shipping_address.country", "payment_link.metadata" ]

A list of additional payment link 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:
reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each payment link. It's primary role is to distinguish one payment link from another, ensuring that each payment link 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 payment link endpoint with sending identify_by query parameter with value reference_id.

due_date
Type: date|null
Format: Y-m-d

It should a date newer than today. Indicating the final date by which the payment should be made. This helps in setting clear expectations for timely payments and aids in better financial planning for both the payer and the recipient. The value format is Y-m-d (e.g 2023-10-28).

expires_at
Type: timestamp|null

It indicates when the payment link becomes invalid. It ensures payments are made within a specified timeframe, useful for time-sensitive offers. It informs both the payer and the recipient about the exact deadline until which the payment can be processed.

metadata
Type: object|null

The payment link 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
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
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
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
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
200
Response schema:
application/json
Response body:
payment_link
Type: object

The payment link model details.

id
Type: ulid
Length: 26

The unique ID assigned to each payment link 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 payment link. This ULID is automatically created by our system and is used to uniquely identify and track each payment link in our database.

title
Type: string
Min: 2
Max: 255

It's a clear label that quickly tells both the person paying and the person receiving the payment what the transaction is about.

payment_details
Type: object

The payment details model for the payment link.

currency_code
Type: enum
Possible values:
[
"EGP" ]

The three-character ISO-4217 Currency Code that identifies the currency for the payment link. Your business should be eligible to use the selected currency code.

amount
Type: decimal
Min: 1
Max: 9999999

The original payment link amount value before adding any taxes. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

taxes
Type: array_of_objects

The tax models for the payment link.

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
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
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
Type: enum
Possible values:
[
"PERCENTAGE", "FLAT" ]

The tax value 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
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
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
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
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
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
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
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
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
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
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
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
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.

tax_strategy
Type: enum|null
Possible values:
[
"EXCLUSIVE", "INCLUSIVE" ]

When you add Taxes, sometimes you need to change the usual way those Taxes are calculated. You can use this attribute to apply specific tax strategy for all applied Taxes.

exclusive_tax_amount
Type: decimal

The payment link exclusive tax(es) amount value. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

inclusive_tax_amount
Type: decimal

The payment link inclusive tax(es) amount value. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

total_tax_amount
Type: decimal

The payment link total tax(es) amount value. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

amount_after_tax
Type: decimal

The payment link amount value after applying tax(es) value. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

total_amount
Type: decimal

The payment link amount value. It's the final value after adding the tax(es). The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

paid_amount
Type: decimal

The payment link amount value that has already been paid. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

remaining_amount
Type: decimal

The payment link remaining amount value to be paid. The length includes the value, the decimal digit and the decimal value. The API accepts 2 digits like 50.53.

status
Type: enum
Possible values:
[
"UNPAID", "PENDING", "CANCELLED", "PAID", "OVER_PAID", "FULLY_REFUNDED", "PARTIALLY_REFUNDED", "INITIATED", "PARTIALLY_PAID" ]

This attribute tells that what stage the payment link payment is in.

is_completed
Type: boolean

This attribute indicates whether the payment link payment is completed or not.

paid_at
Type: datetime|null

This attribute indicates when the payment link was paid. 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.

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each payment link. It's primary role is to distinguish one payment link from another, ensuring that each payment link 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 payment link endpoint with sending identify_by query parameter with value reference_id.

customer_id
Type: ulid|null

This field is the key to associating each payment link with the correct customer account, enhancing the personalization and accuracy of the transaction process. It's not only enhances transaction precision but also contributes significantly to effective customer relationship management and data analysis.

customer
Type: object|null

The customer model for the payment link.

id
Type: ulid
Length: 26

The unique ID assigned to each customer 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 customer. This ULID is automatically created by our system and is used to uniquely identify and track each customer in our database.

name
Type: string
Min: 2
Max: 255

This is the fundamental attribute representing the customer's full legal or preferred name. It's used in all forms of communication and identification. It's crucial for personalization and ensures that all correspondences and documents are correctly addressed.

email
Type: string|null
Min: 5
Max: 255

The email address is a key point of contact for digital communication. It's used for sending transactional emails, marketing material and support communications.

billing_emails
Type: array_of_strings
Max: 20

In addition to the primary email, customers might have separate email addresses specifically for billing purposes. This field can store multiple emails, ensuring that all billing-related documents reach the appropriate contacts, which is especially useful in business settings.

cc_emails
Type: array_of_strings
Max: 20

These are carbon copy email addresses where copies of communications are sent. This is particularly useful in a business context where multiple parties, like account managers or financial departments, need to be kept in the loop.

shipping_address_as_billing_address
Type: boolean
Default: true

Another boolean attribute indicating whether the customer's shipping address is identical to their billing address. This simplifies the process for customers who use the same address for both purposes and streamlines data entry and management.

billing_email_as_customer_email
Type: boolean
Default: true

This attribute indicates whether the customer's primary email address, which is used for general communication and account management, is the same as the email address used specifically for billing purposes.

phone_number
Type: string|null

This attribute stores the customer's telephone or mobile number. It's essential for direct contact, SMS notifications, and can also be used in cases where email communication is insufficient or inappropriate.

type
Type: enum|null
Possible values:
[
"INDIVIDUAL", "BUSINESS" ]

This attribute is used to differentiates between types of customers, such as individual consumers, business clients, or other classifications. The type can influence how the profile is managed and what kind of communication is sent.

gender
Type: enum|null
Possible values:
[
"MALE", "FEMALE", "NON_BINARY" ]

Recording the customer's gender can help in creating more personalized marketing strategies and customer interactions. It's useful for demographic segmentation and can be leveraged to tailor products, services, and communication to better align with the customer's preferences.

country_code
Type: string|null

Specify the unique two-letter country code ( e.g EG, SA or AE ) corresponding to the country where your customer is based. This code is part of the standard international country codes set by the ISO .

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each customer. It's primary role is to distinguish one customer from another, ensuring that each customer 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 customer endpoint with sending identify_by query parameter with value reference_id.

is_active
Type: boolean
Default: true

This value indicates whether the customer is active or not. This flag can be used to control the customer's availability in runtime environments or listings without deleting or removing the customer from records. A true value means the customer is active and functioning, while a false value implies that the customer is deactivated or not in use.

description
Type: string|null
Max: 10000

This free-form text field allows for adding additional notes or details about the customer. It can include information like customer preferences, special instructions, past interactions, or any other relevant data that doesn't fit into more structured fields.

tags
Type: array_of_objects
Max: 20

The list of customer tags objects.

id
Type: ulid
Length: 26

The unique ID assigned to each customer tag 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 customer tag. This ULID is automatically created by our system and is used to uniquely identify and track each customer tag in our database.

name
Type: string
Min: 1
Max: 100

This attribute serves as the identifier or label for the group. It's a concise and clear title that represents the essence of the group. For instance, a name could be 'Frequent Buyers' or 'Newsletter Subscribers'. This attribute should be chosen to reflect the common characteristic or purpose that links the customers in this tag, making it easy to identify and reference the group at a glance. Please notice that duplicate values are not allowed and it's allowed to use alpha dash only [A-Za-z0-9-_ ].

is_active
Type: boolean
Default: true

This value indicates whether the customer tag is active or not. This flag can be used to control the customer tag's availability in runtime environments or listings without deleting or removing the customer tag from records. A true value means the customer tag is active and functioning, while a false value implies that the customer tag is deactivated or not in use.

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each customer tag. It's primary role is to distinguish one customer tag from another, ensuring that each customer tag 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 customer tag endpoint with sending identify_by query parameter with value reference_id.

description
Type: string|null
Max: 10000

This attribute provides more detailed information about the customer tag. It's where you can explain the purpose or characteristics of the group in more depth. For example, for a tag named 'Frequent Buyers', the description might elaborate on criteria like “Customers who make purchases more than twice a month.” This attribute is particularly useful for understanding the context and nuances of the customer group, guiding how you interact with and cater to this segment.

metadata
Type: object|null

The customer tag 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
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
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
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
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
Type: boolean
Default: false

This value indicates whether the customer tag is deleted or not. This flag can be used to control the customer tag's availability in runtime without actual deleting or removing the customer tag from records. A true value means the customer tag is deleted, while a false value implies that the customer tag is not deleted and functioning.

created_at
Type: datetime

The created datetime of the customer tag. 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
Type: datetime

The updated datetime of the customer tag. 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
Type: datetime|null

The deleted datetime of the customer tag. 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.

metadata
Type: object|null

The customer 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
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
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
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
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.

billing_address
Type: object|null

The customer default billing address model details.

id
Type: ulid
Length: 26

The unique ID assigned to each customer address 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 customer address. This ULID is automatically created by our system and is used to uniquely identify and track each customer address in our database.

country_code
Type: string

Specify the unique two-letter country code ( e.g EG, SA or AE ) corresponding to the country where customer is located. This code is part of the standard international country codes set by the ISO .

type
Type: enum
Possible values:
[
"BILLING_ADDRESS", "SHIPPING_ADDRESS" ]

This attribute is used to differentiates between types of customer addresses, such as billing or shipping address.

is_default
Type: boolean
Default: false

This attribute specifies if the address is the default one selected for the customer for billing or shipping purposes. It comes into play when the user is directed to the checkout page or when an order is being delivered to them.

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each customer address. It's primary role is to distinguish one customer address from another, ensuring that each customer address 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 customer address endpoint with sending identify_by query parameter with value reference_id.

line_one
Type: string|null
Min: 2
Max: 255

This attribute is the primary address line. This is where the first part of the address is written, usually the house number and street name. It's where the mail starts to find where you live or work.

line_two
Type: string|null
Min: 2
Max: 255

An optional secondary address line used for additional information like apartment, suite, or building numbers that help refine the location for delivery services.

city
Type: string|null
Min: 2
Max: 50

This attribute specifies the city in which the address is located. It's essential for routing mail and deliveries within the correct geographical area.

state
Type: string|null
Min: 2
Max: 50

The state or region attribute further narrows down the location, especially in countries with large geographical areas divided into states, provinces, or regions.

zip_code
Type: string|null
Min: 2
Max: 30

Also known as postal code in some regions, this numeric or alphanumeric code is critical for sorting mail and determining delivery routes with precision.

phone_number
Type: string|null
Max: 30

A primary contact number that can be a mobile or cellular number, providing a direct line to the individual or entity associated with the address.

landline_number
Type: string|null
Max: 30

An alternative to the mobile number, this is a fixed-line telephone number associated with the location, useful for contact purposes where mobile signals may be unreliable.

fax_number
Type: string|null
Max: 30

Not used as much these days, but it's a number where you can receive documents sent over a telephone line.

first_name
Type: string|null
Min: 2
Max: 50

The given name of the individual associated with the address, important for personalizing communication and ensuring the correct recipient for mail or services.

last_name
Type: string|null
Min: 2
Max: 50

The family or surname of the individual, completing the personal identification and used in conjunction with the first name for full clarity on the recipient's identity.

is_deleted
Type: boolean
Default: false

This value indicates whether the customer address is deleted or not. This flag can be used to control the customer address's availability in runtime without actual deleting or removing the customer address from records. A true value means the customer address is deleted, while a false value implies that the customer address is not deleted and functioning.

location
Type: object|null

This attribute is used to offer a precise, geographical identification of a place, which is crucial for various applications like mapping, navigation, and location-based services.

lat
Type: decimal
Min: -90
Max: 90

This stands for latitude. It's a way to tell exactly where the address is on the Earth using GPS. It tells you how far north or south the place is.

lng
Type: decimal
Min: -180
Max: 180

This is the longitude. Like latitude, but it tells you how far east or west the place is. Together with latitude, it can pinpoint any location on the globe.

note
Type: string|null
Min: 2
Max: 255

This free-text field allows for additional information or special instructions related to the address or delivery preferences to be included.

customer_id
Type: ulid

This field is the key to associating each address with the correct customer account, enhancing the personalization and accuracy of the transaction process. It's not only enhances transaction precision but also contributes significantly to effective customer relationship management and data analysis.

country
Type: object

This attribute is used to offer a precise, geographical identification of a place, which is crucial for various applications like mapping, navigation, and location-based services.

code
Type: string

It implies the unique two-letter country code ( e.g EG, SA or AE ) corresponding to the country. This code is part of the standard international country codes set by the ISO .

dial_code
Type: string

The international dialing code for the country, such as +1 for the United States, +44 for the United Kingdom or +20 for Egypt. This code is crucial for making international telephone calls and can be used in applications that require user phone number verification.

currency_code
Type: string

This attribute describes the official currency used in the country, typically denoted by its ISO currency code, such as USD for the United States Dollar, EUR for the Euro or EGP for Egyptian Pound.

name
Type: string

The official name of the country in English. This is the commonly recognized name that would be used in international contexts and is essential for any application that references countries by name.

name_ar
Type: string|null

The name of the country in Arabic. This attribute is particularly useful for applications serving Arabic-speaking users, allowing for a localized experience by presenting country names in the native script.

lang
Type: string|null

This attribute represents the primary language spoken in the country. It's typically expressed in ISO 639-1 format, a two-letter code identifying the language, making it easier for applications to adapt content or interfaces according to the user's region.

flag
Type: string|null

A Unicode representation of the country's flag. Unlike an image URL, Unicode flags are character codes that render as the country's flag emoji across compatible digital platforms. This allows for easy integration of flags into text-based content and interfaces without needing external images.

created_at
Type: datetime

The created datetime of the customer address. 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
Type: datetime

The updated datetime of the customer address. 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
Type: datetime|null

The deleted datetime of the customer address. 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.

shipping_address
Type: object|null

The customer default shipping address model details.

id
Type: ulid
Length: 26

The unique ID assigned to each customer address 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 customer address. This ULID is automatically created by our system and is used to uniquely identify and track each customer address in our database.

country_code
Type: string

Specify the unique two-letter country code ( e.g EG, SA or AE ) corresponding to the country where customer is located. This code is part of the standard international country codes set by the ISO .

type
Type: enum
Possible values:
[
"BILLING_ADDRESS", "SHIPPING_ADDRESS" ]

This attribute is used to differentiates between types of customer addresses, such as billing or shipping address.

is_default
Type: boolean
Default: false

This attribute specifies if the address is the default one selected for the customer for billing or shipping purposes. It comes into play when the user is directed to the checkout page or when an order is being delivered to them.

reference_id
Type: string|null
Max: 50

It's a unique identifier assigned to each customer address. It's primary role is to distinguish one customer address from another, ensuring that each customer address 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 customer address endpoint with sending identify_by query parameter with value reference_id.

line_one
Type: string|null
Min: 2
Max: 255

This attribute is the primary address line. This is where the first part of the address is written, usually the house number and street name. It's where the mail starts to find where you live or work.

line_two
Type: string|null
Min: 2
Max: 255

An optional secondary address line used for additional information like apartment, suite, or building numbers that help refine the location for delivery services.

city
Type: string|null
Min: 2
Max: 50

This attribute specifies the city in which the address is located. It's essential for routing mail and deliveries within the correct geographical area.

state
Type: string|null
Min: 2
Max: 50

The state or region attribute further narrows down the location, especially in countries with large geographical areas divided into states, provinces, or regions.

zip_code
Type: string|null
Min: 2
Max: 30

Also known as postal code in some regions, this numeric or alphanumeric code is critical for sorting mail and determining delivery routes with precision.

phone_number
Type: string|null
Max: 30

A primary contact number that can be a mobile or cellular number, providing a direct line to the individual or entity associated with the address.

landline_number
Type: string|null
Max: 30

An alternative to the mobile number, this is a fixed-line telephone number associated with the location, useful for contact purposes where mobile signals may be unreliable.

fax_number
Type: string|null
Max: 30

Not used as much these days, but it's a number where you can receive documents sent over a telephone line.

first_name
Type: string|null
Min: 2
Max: 50

The given name of the individual associated with the address, important for personalizing communication and ensuring the correct recipient for mail or services.

last_name
Type: string|null
Min: 2
Max: 50

The family or surname of the individual, completing the personal identification and used in conjunction with the first name for full clarity on the recipient's identity.

is_deleted
Type: boolean
Default: false

This value indicates whether the customer address is deleted or not. This flag can be used to control the customer address's availability in runtime without actual deleting or removing the customer address from records. A true value means the customer address is deleted, while a false value implies that the customer address is not deleted and functioning.

location
Type: object|null

This attribute is used to offer a precise, geographical identification of a place, which is crucial for various applications like mapping, navigation, and location-based services.

lat
Type: decimal
Min: -90
Max: 90

This stands for latitude. It's a way to tell exactly where the address is on the Earth using GPS. It tells you how far north or south the place is.

lng
Type: decimal
Min: -180
Max: 180

This is the longitude. Like latitude, but it tells you how far east or west the place is. Together with latitude, it can pinpoint any location on the globe.

note
Type: string|null
Min: 2
Max: 255

This free-text field allows for additional information or special instructions related to the address or delivery preferences to be included.

customer_id
Type: ulid

This field is the key to associating each address with the correct customer account, enhancing the personalization and accuracy of the transaction process. It's not only enhances transaction precision but also contributes significantly to effective customer relationship management and data analysis.

country
Type: object

This attribute is used to offer a precise, geographical identification of a place, which is crucial for various applications like mapping, navigation, and location-based services.

code
Type: string

It implies the unique two-letter country code ( e.g EG, SA or AE ) corresponding to the country. This code is part of the standard international country codes set by the ISO .

dial_code
Type: string

The international dialing code for the country, such as +1 for the United States, +44 for the United Kingdom or +20 for Egypt. This code is crucial for making international telephone calls and can be used in applications that require user phone number verification.

currency_code
Type: string

This attribute describes the official currency used in the country, typically denoted by its ISO currency code, such as USD for the United States Dollar, EUR for the Euro or EGP for Egyptian Pound.

name
Type: string

The official name of the country in English. This is the commonly recognized name that would be used in international contexts and is essential for any application that references countries by name.

name_ar
Type: string|null

The name of the country in Arabic. This attribute is particularly useful for applications serving Arabic-speaking users, allowing for a localized experience by presenting country names in the native script.

lang
Type: string|null

This attribute represents the primary language spoken in the country. It's typically expressed in ISO 639-1 format, a two-letter code identifying the language, making it easier for applications to adapt content or interfaces according to the user's region.

flag
Type: string|null

A Unicode representation of the country's flag. Unlike an image URL, Unicode flags are character codes that render as the country's flag emoji across compatible digital platforms. This allows for easy integration of flags into text-based content and interfaces without needing external images.

created_at
Type: datetime

The created datetime of the customer address. 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
Type: datetime

The updated datetime of the customer address. 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
Type: datetime|null

The deleted datetime of the customer address. 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.

created_at
Type: datetime

The created datetime of the customer. 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
Type: datetime

The updated datetime of the customer. 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
Type: string|null
Min: 2
Max: 10000

It provides clear, concise details about what the payment is for. It ensures the transparency and understanding between the payer and the payee.

due_date
Type: date|null
Format: Y-m-d

It should a date newer than today. Indicating the final date by which the payment should be made. This helps in setting clear expectations for timely payments and aids in better financial planning for both the payer and the recipient. The value format is Y-m-d (e.g 2023-10-28).

expires_at
Type: datetime|null

It indicates when the payment link becomes invalid. It ensures payments are made within a specified timeframe, useful for time-sensitive offers. It informs both the payer and the recipient about the exact deadline until which the payment can be processed. 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.

metadata
Type: object|null

The payment link 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
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
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
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
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
Type: datetime

The created datetime of the payment link. 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
Type: datetime

The updated datetime of the payment link. 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
"payment_link": {
3 "id": "01hqjmrh1hjg315bhnytk0k7ne", 4 "title": "Office accessories for Gawaab corporate", 5
"payment_details": {
6 "currency_code": "EGP", 7 "amount": 1000, 8
"taxes": [
9
{
10 "id": "01hqh45s7826hfwdze8dp1z21f", 11 "name": "Value added tax", 12 "value": 14, 13 "value_type": "PERCENTAGE", 14 "type": "VAT", 15 "strategy": "EXCLUSIVE", 16 "country_code": "EG", 17 "reference_id": "b438800f-9e32-36a1-aee8-725aca982cc7", 18 "is_active": true, 19 "description": "The value added tax", 20
"metadata": {
21
"info": [
22
{
23 "key": "Company name", 24 "value": "Pyngy" 25 } 26 ], 27
"list": [
28 "Cairo, Nasr City, 7th District, Building 12 floor 5" 29 ] 30 }, 31 "created_at": "1722572118554", 32 "updated_at": "1722572118554" 33 }, 34
{
35 "id": "01ht1mz21w0b63gffe17fhzvk2", 36 "name": "Sales tax", 37 "value": 100, 38 "value_type": "FLAT", 39 "type": "SALES_TAX", 40 "strategy": "INCLUSIVE", 41 "country_code": "EG", 42 "reference_id": "62824653-0d70-3580-8beb-6144971cc93b", 43 "is_active": true, 44 "description": "The value added tax", 45
"metadata": {
46
"info": [
47
{
48 "key": "Company name", 49 "value": "Pyngy" 50 } 51 ], 52
"list": [
53 "Cairo, Nasr City, 7th District, Building 12 floor 5" 54 ] 55 }, 56 "created_at": "1722572118554", 57 "updated_at": "1722572118554" 58 } 59 ], 60 "tax_strategy": null, 61 "exclusive_tax_amount": 140, 62 "inclusive_tax_amount": 100, 63 "total_tax_amount": 240, 64 "amount_after_tax": 1140, 65 "total_amount": 1140, 66 "paid_amount": 0, 67 "remaining_amount": 1140, 68 "status": "UNPAID", 69 "is_completed": false, 70 "paid_at": null 71 }, 72 "reference_id": "e07ac088-4cb3-3797-bfae-bc4ddca71648", 73 "customer_id": "01hqjp3f48879znt9v4dysrk2r", 74
"customer": {
75 "id": "01hqjp3f48879znt9v4dysrk2r", 76 "name": "Mohsen Ali", 77 "email": "mohsen@gawaab.com", 78
"billing_emails": [
79 "shady.abbas@gawaab.com", 80 "diab.maged@gawaab.com" 81 ], 82
"cc_emails": [
83 "ramy.tarek@gawaab.com", 84 "dina.mourad@gawaab.com" 85 ], 86 "shipping_address_as_billing_address": true, 87 "billing_email_as_customer_email": true, 88 "phone_number": "+201000333000", 89 "type": "INDIVIDUAL", 90 "gender": "MALE", 91 "country_code": "EG", 92 "reference_id": "7193edd2-7574-3b76-9103-e0e37580129b", 93 "is_active": true, 94 "description": "Business development head at Gawaab", 95
"tags": [
96
{
97 "id": "01hqjp31wcww3jhnagehc16r04", 98 "name": "Frequent Buyers", 99 "is_active": true, 100 "reference_id": "7193edd2-7574-3b76-9103-e0e37580129b", 101 "description": "Customers who make purchases more than twice a month.", 102
"metadata": {
103
"info": [
104
{
105 "key": "Company name", 106 "value": "Pyngy" 107 } 108 ], 109
"list": [
110 "Cairo, Nasr City, 7th District, Building 12 floor 5" 111 ] 112 }, 113 "is_deleted": false, 114 "created_at": "1722572118554", 115 "updated_at": "1722572118554", 116 "deleted_at": null 117 } 118 ], 119
"metadata": {
120
"info": [
121
{
122 "key": "Company name", 123 "value": "Pyngy" 124 } 125 ], 126
"list": [
127 "Cairo, Nasr City, 7th District, Building 12 floor 5" 128 ] 129 }, 130
"billing_address": {
131 "id": "01ht3tph1szfa5b02qsay22hk1", 132 "country_code": "EG", 133 "type": "BILLING_ADDRESS", <