Changelog

Summary

🚀 Hosted Payment Sessions Multi-Currency & Non-IBAN Support: Enhanced Hosted Payment Sessions to support multiple currencies and non-IBAN regions by enabling developers to reference pre-created recipients instead of embedding recipient details in session requests.

New Features

Recipient ID-Based Payment Sessions

Create Payment Session

• What’s New: Updated recipient_details structure to use recipient_id instead of embedded recipient objects
• Purpose: Enable support for multiple currencies and non-IBAN bank detail formats
• Key Changes:
  • recipient_details now requires recipient_id instead of full recipient object
  • Simplified structure: amount, payment_reference, purpose_of_transaction, and recipient_id
  • Recipients must be created separately using the Add a New Recipient API before creating a session

Enhanced Hosted Integration Workflow

Integration Guidelines

• What’s New: Updated Hosted integration workflow to include recipient creation step
• Workflow Changes:
  • Step 2: Recipient creation - New step added to create recipients before session creation
  • Step 3: Session creation - Updated to reference recipients by ID
  • Updated all examples to use the new simplified recipient_details structure

Breaking Changes

⚠️ Important: This is a breaking change for existing integrations using Hosted Payment Sessions.

The recipient_details structure in payment session requests has changed. Instead of embedding full recipient objects (name, address, bank details) directly in the session request, you must now reference pre-created recipients using recipient_id. This change enables support for multiple currencies and non-IBAN bank detail formats.

Migration Steps

1. Create Recipients First: Use the Add a New Recipient API to create recipients with their bank details
2. Store Recipient IDs: Save the recipient_id returned from the recipient creation response
3. Update Session Creation: Modify your payment session creation requests to use recipient_id instead of embedded recipient objects

Structure Comparison

Previous Structure (No Longer Supported):

"recipient_details": [
  {
    "amount": {
      "currency": "AED",
      "value": 3000.25
    },
    "recipient": {
      "name": "John Doe",
      "type": "Individual",
      "payment_reference": "RentAug",
      "address": { ... },
      "recipient_bank_details": { ... },
      "purpose_of_transaction": "PROPERTY_PURCHASE"
    }
  }
]

New Structure (Required):

"recipient_details": [
  {
    "amount": {
      "currency": "AED",
      "value": 3000.25
    },
    "payment_reference": "RentAug",
    "purpose_of_transaction": "PROPERTY_PURCHASE",
    "recipient_id": "123456"
  }
]

API Reference Updates

• Create Payment Session - Updated request structure
• Add a New Recipient - Required before creating sessions
• Integration Guidelines - Updated workflow documentation