Changelog

Summary

🚀 Hosted Sessions Listing API: Added a new read endpoint to list hosted payment sessions for a customer, including idempotency lookup by client_reference_id.

New Features

Hosted Experience Sessions

• New endpoint: GET /v1/customers/{customer_id}/sessions
• Primary idempotent lookup flow: GET /v1/customers/{customer_id}/sessions?client_reference_id={ref}
• Supports pagination using page and limit
• Response includes sessions and meta with pagination fields (page, limit, total_records, total_pages)
• Session records include fields such as:
  • session_id
  • client_reference_id
  • client_customer_ref
  • customer_id
  • created_at
  • session_expires_at
  • latest_status
  • has_payment and payment_id (when available)

Documentation Updates

• Updated the payment reconciliation guide to include a retry recovery pattern:
  • If session creation response is lost or a retry occurs, first query sessions by client_reference_id for the same customer_id to fetch the existing session and avoid duplicate creation.

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):

1
"recipient_details": [
2
  {
3
    "amount": {
4
      "currency": "AED",
5
      "value": 3000.25
6
    },
7
    "recipient": {
8
      "name": "John Doe",
9
      "type": "Individual",
10
      "payment_reference": "RentAug",
11
      "address": { ... },
12
      "recipient_bank_details": { ... },
13
      "purpose_of_transaction": "PROPERTY_PURCHASE"
14
    }
15
  }
16
]

New Structure (Required):

1
"recipient_details": [
2
  {
3
    "amount": {
4
      "currency": "AED",
5
      "value": 3000.25
6
    },
7
    "payment_reference": "RentAug",
8
    "purpose_of_transaction": "PROPERTY_PURCHASE",
9
    "recipient_id": "123456"
10
  }
11
]

API Reference Updates

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

Summary

🚀 Currency Expansion & Recipient Management Enhancements: Added support for payout currencies and enhanced recipient management with currency-specific fields for better compliance and data management.

New Features

Payout Currencies Support

Get Currencies

• What’s New: Added payout_currencies array to the currencies reference endpoint
• Purpose: Returns the list of currencies that can be used for payouts in your organisation
• Benefits:
  • Enables clients to programmatically determine available payout currencies
  • Supports dynamic currency selection in payment workflows
  • Provides clear visibility into supported payout options

Enhanced Recipient Management

Add a New Recipient & Update a Recipient’s Account

• What’s New: Added additional_details object to both recipient creation and update payloads
• Purpose: Support currency-specific fields required for different payout currencies
• Key Features:
  • Flexible map structure for currency-specific information
  • Example structure:

    1
    "additional_details": {
    2
      "tax_id": "AH12345678"
    3
    }
  • Supported Currencies and Fields:
    • BRL (Brazilian Real): Tax ID must be provided in the tax_id field
    • KRW (South Korean Won): Business Registration number must be provided in the tax_id field
    • PKR (Pakistani Rupee): Identification number must be provided in the tax_id field
    • ISK (Icelandic Króna): Supported currency for currency-specific recipient payloads
  • Enables compliance with local regulatory requirements
  • Allows modification of tax identification numbers or registration details when updating recipients

Get Recipients & Get Recipient Details

• What’s New: Response now includes additional_details object
• Purpose: Retrieve tax identification numbers or registration numbers for recipients when available
• Key Features:
  • Returns currency-specific recipient information
  • Provides complete recipient profile including compliance data
  • Supports audit and compliance workflows

Breaking Changes

• None. All changes are additive and backward compatible.

Summary

🚀 Create Payment API Enhancement: The Create Payment API now supports optional FX conversion, allowing you to create same-currency payments without requiring a quote. FX conversion is optional - provide a quote_id only when currency conversion is needed.

API Updates

Create Payment

• Endpoint: POST /v3/customers/:customer_id/payments
• What’s New: FX conversion is now optional in the payment creation workflow
• Key Changes:
  • FX Conversion (Optional): If you need to convert currency, provide a quote_id from an active quote
    • The quote must be active and not expired
    • Quote validation ensures accurate FX rates and conversion amounts
  • Same Currency Payment: If no currency conversion is needed (same currency payment), do not send quote_id
    • Enables direct same-currency payments without requiring a quote
    • Streamlines payment creation for domestic or same-currency transfers

Usage Guidelines:

• For FX Conversion Payments: Include quote_id in the request payload. The quote must be active and not expired.
• For Same Currency Payments: Omit quote_id from the request payload. The payment will be processed without currency conversion.

Webhook Updates

Payment Status Updated Event

Updated payment status descriptions to clarify when each status applies:

Status Flow Differences:

• Same Currency Payments: Start with PROCESSING status immediately after payment creation
• FX Conversion Payments: Start with AWAITING_FUNDS status, then transition to RECEIVED_FUNDS when funds are received

Breaking Changes

• None. The quote_id field remains optional, maintaining backward compatibility with existing integrations.

Summary

📋 Legacy Payment APIs Documentation: Documented legacy v2 Payment API endpoints and provided migration guidance to help existing integrations transition to the improved v3 Payments API.

Legacy Payment APIs

Legacy APIs

• What’s New: Documented legacy v2 Payment API endpoints
• Purpose: Provide migration guidance for existing integrations
• Status: These endpoints remain functional but are no longer actively developed. New features and improvements are only available in the v3 Payments API.

Migration Guide

The following legacy endpoints have been superseded by v3 alternatives:

Benefits of Migrating to v3

The v3 Payments API provides several improvements over the legacy endpoints:

• Unified workflow: Combined FX conversion and payment creation in a single request
• Enhanced tracking: More detailed payment status information
• Bank transfer instructions: Dedicated endpoint for retrieving funding instructions
• Improved error handling: More detailed and actionable error responses
• Same-currency support: Handles both FX conversion and same-currency payments

Breaking Changes

• None. Legacy endpoints remain functional. However, we strongly recommend migrating to v3 for improved functionality and consistency.

Summary

Regulatory Compliance Updates: Added comprehensive guides for Confirmation of Payee (CoP) and Verification of Payee (VoP), covering all error codes, step-by-step resolution workflows, and updated API support for regulatory verification retries.

New Documentation

Regulatory Compliance Guides

• Confirmation of Payee (CoP) Guide: Complete guide covering CoP verification errors and their corresponding resolution workflows for UK payments.

• Verification of Payee (VoP) Guide: Complete guide covering VoP verification errors and their corresponding resolution workflows for EUR(SEPA) payments.

API Updates

New Request Fields

• confirm_recipient (optional): Added under recipient_details in the Create Payment API to allow retrying a payment for recipients that failed CoP or VoP checks
  • Enables retrying payments after CoP/VoP verification failures
  • Includes customer_action, request_identifier, and event_id fields

Summary

Third Party Customer Status Webhook: Added webhook notifications for third party customer status updates.

New Features

Third Party Customer Status Webhook

• What’s New: Platforms can now receive real-time webhook notifications when the status of a third party customer changes (e.g., from PENDING to APPROVED or REJECTED).
• How it Works: When a third party customer’s compliance status is updated, Redpin will send a webhook event to your configured endpoint with the latest status and customer reference.
• Benefits:
  • Enables instant updates to your platform when customer onboarding or compliance review is completed.
  • Reduces the need for polling the API for status changes.
• Event Payload Example:

  1
  {
  2
    "event_id": "3",
  3
    "event_timestamp": "2025-01-01T00:00:00Z",
  4
    "customer_id": "0201001008132685",
  5
    "client_customer_ref": "CUST_001",
  6
    "status": "APPROVED"
  7
  }
• Documentation: See Third Party Customer Webhook Events for integration details and setup instructions.

Bug Fixes

• N/A

Breaking Changes

• None. This is a non-breaking, additive change.

Summary

📖 New Integration Guides: Added comprehensive documentation to help developers integrate with Redpin’s APIs more effectively.

New Documentation

Integration Guides

• Getting Started: Overview of Redpin’s APIs and core payment workflows
• Making Your First Payment: Step-by-step tutorial for processing test payments
• Error Handling: Best practices for handling API errors and implementing retry logic
• Integration Guidelines: Complete guide for partners choosing integration approaches
• Sandbox to Production: Requirements and checklist for production deployment

Summary

🚀 New Third Party Customer APIs: Added APIs for property developers and real estate platforms to manage end-user customer profiles.

New Features

Create Third-Party Customer

• Api-Reference: Create Third Party Customer
• Endpoint: POST /api/v1/customers/{customer_id}/third-parties
• Purpose: Onboard end users (buyers/investors) for property transactions without creating direct Redpin customer relationships

Get Third-Party Customer

• Api-Reference: Get Third Party Customer
• Endpoint: GET /api/v1/customers/{customer_id}/third-parties/{client_customer_reference}
• Purpose: Retrieve customer profiles and compliance status for ongoing transaction management

Update Third-Party Customer

• Api-Reference: Update Third Party Customer
• Endpoint: PUT /api/v1/customers/{customer_id}/third-parties/{client_customer_reference}
• Purpose: Update customer information and trigger re-verification when needed

Create Payment Session API

• Endpoint: POST /api/v1/customers/:customer_id/sessions
• Purpose: Start a hosted payment session for cross-border payments.
• Highlights:
  • Generates a secure, time-limited session URL for embedding in your app or website
  • Supports multi-recipient payments with detailed recipient and bank account data
  • Configurable allowed origins and callback URLs for real-time status updates
  • Secured with OAuth 2.0 authentication
  • Sessions automatically expire at the defined timestamp; a new session must be created if the previous one expires before completion

Summary

🚀 New Recipient Management APIs: The B2B API suite now includes new endpoints to add, update, and retrieve recipient details, making it easier to manage business payments.

Recipient API Endpoints

Add Recipient

• Endpoint: POST /v2/customers/:customer_id/recipients.
• Purpose: Register a new recipient with personal and bank account details for future payments.
• Highlights:
  • Supports both individual and corporate recipients.
  • Collects comprehensive recipient information (name, contact, address, country).
  • Flexible bank account input: IBAN, account number + SWIFT, routing codes, and more.

Update Recipient

• Endpoint: PUT /v2/customers/:customer_id/recipients/:recipient_id.
• Purpose: Update an existing recipient’s details, such as contact information or bank account data.
• Highlights:
  • Modify recipient personal, contact, or bank details.
  • Maintain up-to-date records for compliance and payment accuracy.

Get All Recipients

• Endpoint: GET /v2/customers/:customer_id/recipients.
• Purpose: Retrieve a list of all recipients registered for a specific customer.
• Highlights:
  • List all recipients for a customer, including their details and status.
  • Supports pagination for large recipient lists.
  • Useful for displaying recipient options in your application.