API Release Notes
Track the evolution of Younited Pay API with detailed release notes, new features, and migration guides.
v2026-07-01
Sandbox Released Q3 2026What's New
-
Webhook Subscriptions
Programmatically register webhook endpoints to receive event notifications. Supported event types:
payment.created,payment.updated,refund.created,personal-loan.customer-withdrawal. -
Shop External Reference
Shops now expose an
externalReferencefield: the reference of the shop in your own system (nullwhen none is set).GET /shopsaccepts anexternalReferencequery parameter to filter on it, and the newGET /shops/{shopCode}endpoint returns a single active shop. Also available on v2025-01-01 and v2026-02-01. -
Shipping Address Moved to Customer Information
On
POST /payments, the shipping address of the order is now sent incustomerInformation.shippingAddress, next topostalAddress. It replacesmerchantContext.shippingAddress, which was never used and is no longer read: a value sent there is ignored. Every field is optional. Same change on v2026-02-01.
New Endpoints
Create a new webhook subscription. The subscription will receive event notifications for the specified event types at the provided HTTPS URL.
Request Body Parameters
| Parameter | Required | Description |
|---|---|---|
|
webhookUrl
string |
Required | The HTTPS URL that will receive event notifications. |
|
eventTypes
string[] |
Required | List of event types to subscribe to. At least one is required. Supported values: payment.created, payment.updated, refund.created, personal-loan.customer-withdrawal. |
|
description
string |
Optional description for the subscription. Max 500 characters. |
List all webhook subscriptions for the authenticated reseller.
Retrieve a specific webhook subscription by its unique identifier.
Update an existing webhook subscription. All fields are optional — only the fields provided will be updated.
Request Body Parameters
| Parameter | Required | Description |
|---|---|---|
|
webhookUrl
string |
New HTTPS URL for the subscription. | |
|
eventTypes
string[] |
Replaces the full list of subscribed event types. At least one value required if provided. | |
|
description
string |
New description for the subscription. |
Delete a webhook subscription. Once deleted, the subscription URL will no longer receive event notifications.
Sandbox only
Version 2026-07-01 is currently available in the Sandbox environment only. Production availability will be announced in a future release.
v2026-02-01
Released Q1 2026What's New
-
Split Payment
New payment type enabling customers to divide purchases into multiple installments (2x, 3x, 4x) without traditional credit approval. Designed for smaller transaction amounts with streamlined approval process.
-
Shop External Reference
Shops now expose an
externalReferencefield: the reference of the shop in your own system (nullwhen none is set).GET /shopsaccepts anexternalReferencequery parameter to filter on it, and the newGET /shops/{shopCode}endpoint returns a single active shop. Also available on v2025-01-01 and v2026-07-01. -
Shipping Address Moved to Customer Information
On
POST /payments, the shipping address of the order is now sent incustomerInformation.shippingAddress, next topostalAddress. It replacesmerchantContext.shippingAddress, which was never used and is no longer read: a value sent there is ignored. Every field is optional. Same change on v2026-07-01.
New Endpoints
Retrieve all available payment options (Personal Loan and Split Payment) for a given amount and context. This endpoint enables dynamic display of payment methods tailored to customer eligibility.
Important
You must provide at least one installment count via the InstallmentCount parameter to get results. Returns an empty list if no payment options are available.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
|
PurchaseAmount
number |
Required | The purchase amount for the payment options. |
|
ShopCode
string |
Required | The shop code where the payment will be placed. |
|
InstallmentCount.List
string |
A comma-separated list of installment counts (e.g., "3,4,10,12"). | |
|
InstallmentCount.Range.Min
integer |
The minimum value for the installment range. | |
|
InstallmentCount.Range.Max
integer |
The maximum value for the installment range. | |
|
InstallmentCount.Range.Step
integer |
The step value for the installment range. |
InstallmentCount.List Rules
| Rule | Description |
|---|---|
Optional |
List may be null or empty |
Format |
Comma-separated list of installment counts (e.g., "12, 24, 36") |
Values |
Must be positive integers |
Whitespace |
Ignored |
Duplicates |
Allowed but removed in final result |
InstallmentCount.Range Rules
| Rule | Description |
|---|---|
Optional |
Range may be null |
Min, Max, Step |
Must be positive integers |
Min ≤ Max |
Min must be less than or equal to Max |
Step ≥ 1 |
Must produce a finite sequence |
Sequence |
Min, Min+Step, ..., ≤ Max |
Combining List and Range
List: 2,3,4 + Range.Min=6, Range.Max=24, Range.Step=6 → [2, 3, 4, 6, 12, 18, 24]
Response Examples
{
"purchaseAmount": 1000,
"installmentCount": 3,
"totalAmountDue": 1010,
"type": "SplitPayment",
"splitPaymentDetails": {
"loanTerms": {
"amount": 1000,
"installmentCount": 3,
"interestRate": 0,
"feeAmount": 10
},
"loanDetails": {
"annualPercentageRate": 0.05,
"installmentAmount": 336.67,
"interestAmount": 0,
"totalAmountPayable": 1010
},
"installments": [
{ "installmentNumber": 1, "dueDate": "2025-11-15", "loanAmount": 333.34, "feeAmount": 10, "totalAmount": 343.34 },
{ "installmentNumber": 2, "dueDate": "2025-12-15", "loanAmount": 333.33, "feeAmount": 0, "totalAmount": 333.33 },
{ "installmentNumber": 3, "dueDate": "2026-01-15", "loanAmount": 333.33, "feeAmount": 0, "totalAmount": 333.33 }
]
}
}
{
"purchaseAmount": 1000,
"installmentCount": 12,
"totalAmountDue": 1027,
"type": "PersonalLoan",
"personalLoanDetails": {
"downPaymentAmount": 200,
"loanTerms": {
"amount": 800,
"installmentCount": 12,
"interestRate": 0.05,
"feeAmount": 0
},
"loanDetails": {
"annualPercentageRate": 0.05,
"installmentAmount": 86,
"interestAmount": 27,
"totalAmountPayable": 827
}
}
}
Unified payment creation endpoint supporting all payment types (Personal Loan and Split Payment). This consolidates payment creation into a single, flexible interface.
-
Payment will be created with
Initializedstatus -
The system will emit a
payment.creatednotification when the payment is created
Request Header
| Header | Required | Description |
|---|---|---|
|
x-api-version
string |
Required | API version. Default: 2026-02-01 |
Request Body Parameters
| Parameter | Required | Description |
|---|---|---|
|
paymentType
string (enum) |
Required | Type of payment: PersonalLoan or SplitPayment |
|
purchaseAmount
number (decimal) |
Required | The amount of the purchase that the customer wants to pay using this payment option. Min: 1, Max: 100000 |
|
installmentCount
integer (int32) |
Required | Number of installments, i.e., the number of payments the customer will make to repay the total amount due. Min: 1, Max: 480 |
|
basketDescription
object |
Required | Description of purchased items with name, quantity, and unit price. |
|
merchantContext
object |
Required | Contains shopCode and merchantReference. |
|
technicalInformation
object |
Required | Contains webhookNotificationUrl and webhookNotificationApiVersion. |
|
customerInformation
object |
Optional customer details (name, email, phone, address). | |
|
riskInsights
object |
Optional risk assessment data (IP address, etc.). | |
|
customExperience
object |
Optional custom experience configuration. |
Key Change: Simplified Structure
loanRequest object removed
The purchaseAmount and installmentCount fields have been moved from the nested loanRequest object to the root level of the request body. This simplifies the structure and makes it consistent across payment types.
{
"paymentType": "PersonalLoan",
"purchaseAmount": 1000,
"installmentCount": 12,
"basketDescription": { ... },
"merchantContext": { ... },
"technicalInformation": { ... }
}
✓ Amount & installments at root level
{
"loanRequest": {
"requestedAmount": 1000,
"requestedMaturityInMonths": 12
},
"basketDescription": { ... },
"merchantContext": { ... },
"technicalInformation": { ... }
}
✗ Amount & maturity nested in loanRequest
Migration Note
This endpoint supersedes POST /payments/personal-loan, which remains available for backward compatibility. New integrations should use this unified endpoint.
Changes & Enhancements
Field renamed in technicalInformation. The apiVersion field has been renamed to webhookNotificationApiVersion to clearly indicate that this version controls the webhook notification event payload format, independently of the API version used to create the payment.
"technicalInformation": {
"webhookNotificationUrl": "https://...",
"webhookNotificationApiVersion": "2025-01-01"
}
✓ Explicit: controls webhook payload format
"technicalInformation": {
"webhookNotificationUrl": "https://...",
"apiVersion": "2025-01-01"
}
✗ Ambiguous: could be confused with request API version
Enhanced response structure. Now includes payment-type-specific details with comprehensive information for both Personal Loan and Split Payment types.
-
Type-discriminated response structure based on
paymentTypefield -
New
splitPaymentDetailsobject for Split Payment type -
Backward compatible with existing integrations using
personalLoanDetails
Migration Guide
Adopt Unified Payment Creation
Migrate from POST /payments/personal-loan to POST /payments. Move requestedAmount and requestedMaturityInMonths from the loanRequest object to root-level fields purchaseAmount and installmentCount. Add the paymentType field.
Rename apiVersion to webhookNotificationApiVersion
In the technicalInformation object, rename the apiVersion field to webhookNotificationApiVersion. This field specifies which API version's schema to use for webhook notification event payloads, independently of the API version used for the request.
Implement Payment Options Display
Integrate GET /payments/options to dynamically display all available payment methods (Personal Loan + Split Payment) to your customers based on amount and eligibility.
Update Response Handling
Update your integration to handle the enhanced response from GET /payments/{id}/payment-type-details, which now includes type-specific details in a discriminated union format.
v2025-01-01
Stable Released January 2025Version 2025-01-01 introduced a comprehensive API redesign with improved error handling following RFC 7807 standards, enhanced rate limiting, and real-time webhook notifications. This version supports Personal Loan payment type with complete lifecycle management from creation to execution.
Available Endpoints
Personal Loans
/personal-loans/offers
Get loan offers
/payments/personal-loan
Create personal loan
Payment Operations
/payments/{id}
Get payment details
/payments/{id}/status
Get payment status
/payments/{id}/link
Generate payment link
/payments/{id}/application-status
Get application status
/payments/{id}/payment-type-details
Get payment type details
/payments/{id}/cancel
Cancel payment
/payments/{id}/execute
Execute payment
/payments/{id}/update-amount
Update payment amount
Refunds
/refunds
List refunds
/refunds
Create refund
Balance & Payouts
/balance/transactions
List transactions
/balance/payouts
List payouts
/balance/payouts/{id}/entries
Get payout entries
Merchant & Shops
/merchants/me
Get merchant info
/shops
List shops, filterable by externalReference
/shops/{shopCode}
Get a shop, with its externalReference
Webhooks & Special Cases
/webhooks/verify-integration
Test webhook
/specific-use-cases/door-to-door-sales/confirm-contract-signature-date
D2D compliance
/specific-use-cases/legacy-contracts/{reference}/payment-id
Legacy lookup
/specific-use-cases/payments/{id}/merchant-reference
Update reference
Platform Improvements
-
Enhanced Rate Limiting
Sophisticated API protection with endpoint-specific rate limits for optimal service stability.
-
Standardized Error Responses
Error responses now follow RFC 7807 Problem Details specification for consistent error handling.
-
Advanced Pagination
Balance transactions and payouts endpoints support comprehensive pagination for efficient data handling.
-
Real-time Webhook Notifications
Instant notifications for payment lifecycle events (payment.created, payment.updated, refund.created).
Support & Resources
Our integration support team is available to assist with API integration, migration planning, and technical questions.
-
Integration Support
Contact your dedicated Younited Pay integration manager for personalized assistance.
-
API Documentation
Complete technical documentation available in the API Reference.
-
Sandbox Environment
Test all features in our comprehensive sandbox environment before production deployment.