Younited Pay API - Release Notes

v2026-02-01

Upcoming Expected Q1 2026

Sandbox Only

This version is only available in the Sandbox environment for testing purposes. It is not available in the Production environment yet.

What'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.

New Endpoints

GET /payments/options New

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

                                            Split Payment Response
                                        

{
  "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 }
    ]
  }
}
                                        

                                            Personal Loan Response
                                        

{
  "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
    }
  }
}
                                        

POST /payments New

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 Initialized status
The system will emit a payment.created notification 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.

NEW — POST /payments (v2026-02-01)

{
  "paymentType": "PersonalLoan",
  "purchaseAmount": 1000,
  "installmentCount": 12,
  "basketDescription": { ... },
  "merchantContext": { ... },
  "technicalInformation": { ... }
}

✓ Amount & installments at root level

Previous Version — POST /payments/personal-loan

{
  "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

POST /payments

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.

NEW — v2026-02-01

"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

GET /payments/{id}/payment-type-details

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 paymentType field
New splitPaymentDetails object 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 2025

Current Stable Version

This is the current production version of the Younited Pay API. It provides a complete set of endpoints for managing Personal Loan payments, refunds, balance operations, and merchant configurations.

Version 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

GET /personal-loans/offers Get loan offers

POST /payments/personal-loan Create personal loan

Payment Operations

GET /payments/{id} Get payment details

GET /payments/{id}/status Get payment status

GET /payments/{id}/link Generate payment link

GET /payments/{id}/application-status Get application status

GET /payments/{id}/payment-type-details Get payment type details

POST /payments/{id}/cancel Cancel payment

POST /payments/{id}/execute Execute payment

POST /payments/{id}/update-amount Update payment amount

Refunds

GET /refunds List refunds

POST /refunds Create refund

Balance & Payouts

GET /balance/transactions List transactions

GET /balance/payouts List payouts

GET /balance/payouts/{id}/entries Get payout entries

Merchant & Shops

GET /merchants/me Get merchant info

GET /shops List shops

Webhooks & Special Cases

POST /webhooks/verify-integration Test webhook

POST /specific-use-cases/door-to-door-sales/confirm-contract-signature-date D2D compliance

GET /specific-use-cases/legacy-contracts/{reference}/payment-id Legacy lookup

PATCH /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.