> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.redpincompany.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server.

## 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.

> **Note**
>
> Hosted Payment Sessions now support all currencies and bank detail formats, enabling international expansion beyond UAE/IBAN regions. Developers can now create recipients once and reuse them across multiple payment sessions.

## New Features

### Recipient ID-Based Payment Sessions

#### [Create Payment Session](/api-reference/customers/hosted-experience/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-reference/customers/api-integration/recipients/add-a-new-recipient) API before creating a session

### Enhanced Hosted Integration Workflow

#### [Integration Guidelines](/api-guide/partners/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-reference/customers/api-integration/recipients/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):**

```json
"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):**

```json
"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](/api-reference/customers/hosted-experience/sessions/create-payment-session) - Updated request structure
* [Add a New Recipient](/api-reference/customers/api-integration/recipients/add-a-new-recipient) - Required before creating sessions
* [Integration Guidelines](/api-guide/partners/integration-guidelines) - Updated workflow documentation