Valyrion's Partner Integration
Get up and running in no time by following the instructions below.
Get up and running in no time by following the instructions below.
For partners to manage merchants, debtors and transactions, Valyrion provides access to a secure file server, where files containing the required information are uploaded.
The supported file formats are JSON, CSV and XML
The allowed values for <content type> are merchants, debtors and transactions. The format of content for each file is described below.
The file naming convention is:
<partner name>_<content type>_<date (yyyymmddhhmmss)>.<file extension>
E.g. myname_merchants_20240301153010.json.
To ensure that files are not processed before being fully uploaded, the file should be given a temporary extension (e.g. .tmp) while uploading and renamed to the final extension after completion.
To ensure that files are not processed before being fully uploaded, the file should be given a temporary extension (e.g. .tmp) while uploading and renamed to the final extension after completion.
The data structures are categorized into Mandatory, Marketing Critical, and Optional fields, ensuring optimal system performance and marketing accuracy.
🔴
Mandatory: Required for system functionality and essential for correct operation.
🟡
Marketing Critical: Important for marketing segmentation and improving personalised communications.
🟢
Optional: Beneficial for enhanced insights but not essential for core system functionality.
Note: If any property cannot be provided due to technical limitations or other constraints, a workaround may be available. In such cases, it is recommended to contact gh@valyrion.com to discuss alternative solutions or adjustments to the integration requirements. Our team will assist in identifying a suitable approach to maintain system integrity while addressing any challenges.
Property
Datatype
Description
Importance
ID
UUID/String
Unique identifier for the Merchant
Mandatory
Name
String Max(200)
The Merchant's name
Mandatory
Created
DateTime
Date and time when the Merchant was created
Mandatory
Updated
DateTime
Date and time when the Merchant was last updated
Mandatory
Url
String (URL) Max(2000)
The website URL of the Merchant
Mandatory
Active
Boolean
Indicates if the Merchant is currently active
Mandatory
Webshop Categories
Array [String]
List of product categories sold on the webshop
Optional
Other Segmentation
Object
Additional segmentation fields that help categorize the webshop
Optional
Country
String Max(200)
Country where the Merchant is registered
Optional
CMS Type
String Max(255)
Content Management System used by the webshop
Optional
Property
Datatype
Description
Importance
ID
UUID/String Max(500)
Unique identifier for the User
Mandatory
Created
DateTime
Date and time when the User account was created
Mandatory
Updated
DateTime
Date and time when the User account was last updated
Mandatory
Active
Boolean
Indicates if the User account is active
Mandatory
String Max(255)
The User's registered email address
Mandatory
First Name
String Max(500)
The User's first name
Mandatory
Marketing Status
Boolean
Indicates if the User has opted-in for marketing
Mandatory
Gender
String Max(50)
The User's gender
Marketing Critical
Age
Integer
The User's age
Marketing Critical
Zip Code
String Max(50)
Postal code where the User resides
Marketing Critical
Phone Number
String Max(200)
The User's contact number
Marketing Critical
Last Name
String Max(500)
The User's last name
Optional
Country
StringMax(500)
The User's country of residence
Optional
Current Credit Availability
Decimal
The User’s available credit
Optional
Payment Tier
StringMax(500)
Total credit available to the User
Optional
Installments
Integer
Number of installments
Optional
Property
Datatype
Description
Importance
Transaction ID
UUID/String Max(200)
Unique identifier for the Transaction
Mandatory
Created
DateTime
Date and time when the Transaction was created
Mandatory
Updated
DateTime
Date and time when the Transaction was last updated
Mandatory
Status
String
Current status of the Transaction (e.g., completed)
Mandatory
IsRefunded
Boolean
Indicates whether the Transaction has been refunded
Mandatory
Customer Identifier
UUID / StringMax(200)
User ID or email linked to the Transaction
Mandatory
Merchant Identifier
UUID / StringMax(200)
Unique identifier of the Merchant in the Transaction
Mandatory
Currency
String (ISO 4217)
Currency in which the Transaction was made
Mandatory
Total Amount excl. Tax
Integer
Total transaction amount excluding taxes, in the smallest currency unit **
Mandatory
Total Amount incl. Tax
Integer
Total transaction amount including taxes, in the smallest currency unit **
Mandatory
Items
Array[Object]
List of purchased items
Marketing Critical
Items[].Product Name
String
Name of the purchased product
Marketing Critical
Items[].Product ID
String
Identifier of the purchased product
Marketing Critical
Items[].Quantity
Integer
Quantity of the purchased product
Marketing Critical
Items[].Unit Price
Integer
Price per unit in the smallest currency unit **
Marketing Critical
** All monetary values are represented as positive integers in the smallest currency unit. For example, 100 cents represents $1.00. This approach ensures precision in handling financial transactions across different currencies.
The Partner is required to configure an endpoint that Valyrion will use to notify the Partner when users unsubscribe from marketing communications. The endpoint must accept POST requests with the following payload:
The supported file formats are JSON, CSV and XML
{
"userId": "string", // Unique identifier of the user
"email": "string", // Email address of the unsubscribed user
"unsubscribeDate": "string" // Date and time of the unsubscription
}For secure communication, Valyrion will include an authentication token, provided by Valyrion, in the request header:
Authorization: Bearer <authToken>If configuring an endpoint is not possible, the unsubscribe data can alternatively be retrieved from a secure file upload, which Valyrion will provide on the designated Secure File Server. The file will contain the necessary user identifiers and unsubscription details.
Configuration of the domain's DNS is required to ensure proper email configuration and delivery. Valyrion will provide a detailed DNS task list, which the domain administrator must implement to complete the setup.