The Refunds feature enables businesses to automate and simplify the process of issuing customer refunds. Built on Lean’s existing payout infrastructure, it allows clients to initiate refunds seamlessly. The feature automatically identifies the connected Payout account and processes a reverse transaction, refunding the payment directly to its original source

Getting access to Refunds

To use the refunds feature, you need to have access to the following services:

• Payments: Refunds reverse customer payments processed through Lean Payments. The refunds are hence processed directly to the bank account connected with Lean while making the payment.
• Reconciliation: Refunds are only allowed for payments that have been successfully reconciled, ensuring funds that are received in your bank account are only refunded.
• Payouts:This enables Lean to process the refund by transferring the amount back to the customer's original payment source from the connected business account.

How does Refunds work ?

Lean's Refunds API allows you to initiate and manage refunds for payments processed through the Lean platform. This can be done by two ways - through the application dashboard or programmatically through public APIs. The system supports:

• Full and partial refunds for reconciled payments
• Refunds to the source bank account
• Status tracking through the complete refund lifecycle
• Reason code management for refund categorization

Creating Refunds from the Lean Application Dashboard

1. Your can go on the Payments tab in the Application Dashboard and select the payment which has to be refunded and click on the refunds

🚧

Refunds are only available for transactions that have been reconciled. This ensures users cannot initiate refunds for payments that have not yet settled in the bank.

2. On the "Confirm Refund" section, fill in the details of the transaction. Enter the refund amount, reason, and reference number, then click "Initiate Refund". This will create the refund for the approver to review and confirm.

3. After initiating the refund, navigate to the Refunds tab, where you will see a new payment entry. Click on it to review the refund details. Once reviewed, click "Refund" to queue the refund payment for bank processing.

☝️

The status of the queued refund can be tracked real-time on the same page

Details of payment status can be found in Payouts Lifecycle

Creating Refunds via Lean APIs

Lean provides an API-driven solution that enables clients to process refunds programmatically. This automated workflow allows clients to seamlessly integrate their refund process with Lean, ensuring efficient and streamlined refund management.

1. Create a Refund

Initiate a new refund:

POST /payouts/refunds

Request Body:

[
    {
        "payment_id": "uuid",
        "amount": 100.00,
        "currency": "AED",
        "reason_code": "CUSTOMER_REQUEST",
        "description": "Customer requested refund",
        "external_reference": "REF123",
        "beneficiary": {
            "name": "John Doe",
            "iban": "AE123456789",
            "city": "Dubai"
        }
    }
]

For more , details please refer to the API reference doc

☝️

Reason code is a mandatory field in this request .

This can be fetched from the Get Refund Reasons API as explained below.

Get Refund Reasons

Retrieve available reason codes for refunds:

GET /payouts/refunds/reasons

Example Response:

[
    {
        "code": "CUSTOMER_REQUEST",
        "description": "Requested by the client"
    },
    {
        "code": "DUPLICATED_PAYMENT",
        "description": "Duplicated Payment"
    },
    {
        "code": "ORDER_CANCELLED",
        "description": "Service/Order Cancellation"
    },
    {
        "code": "FRAUDULENT_PAYMENT",
        "description": "Fraudulent Payment"
    }
]

Error Handling

The API uses standard HTTP response codes:

• 201 - Created (Successful refund creation)
• 200 - OK (Successful operation)
• 400 - Bad Request (Invalid parameters)
• 403 - Forbidden (Missing permissions)

Error Response Example:

{
    "status": "OPERATION_NOT_ALLOWED",
    "message": "Operation Not Allowed, payouts not configured",
    "timestamp": "2024-11-01T00:00:00Z"
}

2. Update Refund Status

Once the refund is created, update the status of a refund to "CONFIRMED" or "REJECTED" via the PUT/payouts/refunds endpoint.

PUT /payouts/refunds

Request Body:

[
    {
        "refund_id": "uuid",
        "status": "CONFIRMED"
    }
]

3. List Refunds

For fetching a list of refunds with optional status filtering, hit the GET/payouts/refunds endpoint

GET /payouts/refunds?status=CONFIRMED

Best Practices

1. Include meaningful descriptions and external references for better tracking
2. Store the refund-id returned from the creation API for future reference
3. Regularly check refund status using the GET endpoint
4. Handle all possible status codes in your integration