This guide helps you seamlessly upgrade from SingleView Payouts API V1.0 to Payouts API V2.0, enabling you to take advantage of a cleaner architecture, standardized payloads, and improved performance.

Payouts API V2.0 introduces modular endpoints, consistent request/response structures, and enhanced enquiry handling designed for scalability, auditability, and ease of integration.

What's New in Payouts API V2.0

Payouts API V2.0 delivers a streamlined payout experience with clearly separated flows for Single and Bulk operations.

You can now perform the following operations:

• Single Payment
• Single Payment Enquiry
• Bulk Payment
• Bulk Payment Enquiry

Each operation has a dedicated endpoint and standardized payload structure, ensuring predictable behavior and easier maintenance.

Key Changes in V2.0

When upgrading from V1.0 to V2.0, take note of the following updates:

1. Endpoint URL Structure Changes

V2.0 introduces separate endpoints for Single and Bulk payouts and their respective enquiries. This improves readability, routing clarity, and long-term maintainability.

Migration impact

• Update all payout and enquiry endpoint URLs.
• Remove conditional routing logic used in V1.0.

2.TransferType Tag Moved to Payload

In V1.0, transfer type was part of the URL.

In V2.0, it is removed from the URL and must be passed inside the request payload for both single and bulk payouts.

Migration impact

• Remove TransferType from endpoint URLs.
• Include TransferType explicitly in the request body.

3. Improved Payload Structure

V2.0 introduces a more intuitive and structured request/response format, improving field clarity and developer experience.

Key improvements include:

• Clear separation of header and transaction data
• Consistent naming conventions
• Better extensibility for future fields

Migration impact

• Refactor request and response parsers.
• Validate mandatory fields as per V2.0 specifications.

4. Removal ofbulkToSingle Tag

The bulkToSingle identifier used in V1.0 has been fully removed in V2.0.

This applies to:

• Single Payout payloads
• Bulk Payout payloads
• Single Payout Enquiry payloads
• Bulk Payout Enquiry payloads

Migration impact

• Remove bulkToSingle from all request payloads.
• Eliminate related conditional logic from your implementation.

5. Change in Payout EnquiryMessageType Tag

To improve clarity and consistency, the MessageType values for Payout Enquiries have been updated:

Migration impact

• Update enquiry request payloads with the new MessageType values.
• Ensure downstream validation logic accepts updated values.

6. Standardized Responses & Improved Error Handling

Payouts API V2.0 introduces:

• Uniform response structures across all payout flows
• Consistent status codes and messages
• Better alignment with bank-specific requirements
• Improved partial-success handling for bulk payouts

Migration impact

• Update response parsing logic.
• Handle standardized error codes and messages consistently.

Upgrade Checklist

Before going live with Payouts V2.0, ensure you've completed the following:

✅Update all payout and enquiry endpoint URLs

✅ Pass TransferType inside request payloads

✅ Refactor request and response models as per V2.0

✅ Remove deprecated fields such as bulkToSingle

✅ Update enquiry payloads with:

• MessageType: BPE for Bulk Payout Enquiry
• MessageType: SINGLEREQ for Single Payout Enquiry

✅ Perform full regression testing in the sandbox environment

Why Upgrade to V2.0?

Upgrading to V2.0 provides both immediate and long-term benefits:

• Simplified and modular API endpoints
• Clear separation between Single and Bulk flows
• Enhanced clarity and consistency across payloads
• Scalable architecture for future enhancements
• Better audit, reconciliation, and monitoring support
• Standardized request/response formats with minimal bank-specific changes
• Improved and consistent error handling
• OAS 3.0 compliant
• Improved performance quotient

📘

Need help?

If you face any challenges during the upgrade or need further clarification, don’t hesitate to contact the SingleView support team. We’re here to ensure your upgrade is seamless.