Discover the latest feature releases, product improvements and bug fixes of Appian - Submerchant Register. Stay up to date with changes and updates to the batch submerchant onboarding endpoint POST /onboarding/v1/submerchants/batch in Peru 🇵🇪.We use the ISO 8601 standard (YYYY-MM-DD) for dates, and Semantic Versioning (MAJOR.MINOR.PATCH) for version numbers, increasing the:1.
MAJOR version when we make incompatible API changes,
2.
MINOR version when we add functionality in a backward-compatible manner, and
3.
PATCH version when we make backward-compatible bug fixes.
IMPROVEMENTS for changes in existing functionality.
DEPRECATED for soon-to-be removed features.
REMOVED for now removed features.
SECURITY in case of vulnerabilities.
Latest#
1.2.0 - 2026-08-31#
🆕 Submerchant Document Upload Endpoint & Multi-Region Support Peru 🇵🇪#
The batch submerchant document upload endpoint is now available for Peru 🇵🇪 to complete the onboarding workflow.Document Upload Endpoint: Introduced POST /onboarding/v1/submerchants/documents to allow uploading required KYC/KYB legal documents (e.g., tax certificates, IDs, or proof of address) associated with a submerchant record.
Regional Expansion: The batch onboarding and document management endpoints are fully supported for operational entities in Peru (PER).
🆕 Card Present and Card Not Present request variants#
Each item in the batch request now accepts one of two named request models. The documentation renders them as separate tabs (Card Present and Card Not Present) so you can pick the model that matches how the submerchant operates.Card Present (CP): for submerchants that accept in‑person, terminal‑based payments. Includes the point‑of‑sale fields (usesKushkiPos, operationMode, emails, paymentOptions, paymentTypes, terminalCount, storeName, storeAddress).
Card Not Present (CNP): for submerchants that accept online / remote payments. Point‑of‑sale fields are not applicable and are omitted.
A single batch call can mix CP and CNP items — each array element is validated against the variant it declares.
The variant is selected per item. Send the fields that belong to the chosen model; fields from the other model are not accepted.
IMPROVEMENTS — submerchantName and Soft Descriptor rules (per specification)
The length rule is corrected. It is not a fixed maximum of 18 characters:Dynamic maximum length: MIN(18, 21 − length(PSP Prefix) − 1).
The system normalizes to uppercase and trims spaces.
The system builds the Soft Descriptor: PREFIX*SUBMERCHANT_NAME (max 21 characters). The client sends only submerchantName; the prefix and * are added by the system.
Allowed charset: A-Z, 0-9, &, -, and single spaces; at least one letter.
Not allowed: accents, Ñ, special characters, *, or double spaces. E.g. use PENA instead of PEÑA.
Rejected if, after normalization, it exceeds the dynamic maximum length or contains unsupported characters.
submerchantName has been updated to clarify character constraints, automatic normalization, and dynamic length rules for building Soft Descriptors:Dynamic Length Limit: The effective maximum character length is calculated dynamically based on your PSP account's configured prefix using the formula:
Automatic Normalization: The input value is automatically converted to UPPERCASE and stripped of leading/trailing spaces (trim).
Allowed Characters: Uppercase letters (A–Z), numbers (0–9), ampersands (&), hyphens (-), and single spaces between words.
Letter Requirement: Must contain at least one letter (A–Z). Numeric-only strings (e.g., "12345") are rejected.
Prohibited Characters: Accents/tildes (Á, É), Ñ, asterisks (*), double spaces, and special symbols (@, #, $, %) are strictly prohibited.
Soft Descriptor: Do not include your PSP prefix, asterisks, or attempt to assemble the Soft Descriptor manually. The system automatically constructs the final descriptor as PREFIX*SUBMERCHANT NAME (maximum 21 total characters).
Requests will fail with a BAD_REQUEST error if submerchantName exceeds the dynamic maximum character length configured for your PSP prefix, or if it contains forbidden characters (such as accents or Ñ). Please normalize text before sending (e.g., use PENA instead of PEÑA).
Previous release notes#
1.1.0 - 2026-01-01#
🆕 Batch submerchant onboarding#
Initial release of the batch submerchant onboarding endpoint POST /onboarding/v1/submerchants/batch in Peru 🇵🇪, allowing multiple submerchants to be created in a single request.
Got a suggestion on this documentation? Contact us.
