Multi Lender Webhooks Overview

Use Case

This page describes common standards for all multi-lender webhook APIs. The detailed request body and examples are split into separate API pages for easier reading.

This contract is designed for a multi-lender integration. The endpoint path does not include a specific lender name. Fundiin identifies the lender by Client-Id, Signature, and lenderCode.

Integration Flow

Key points for lender integration:

1. The customer is Fundiin's user and performs loan and repayment actions inside Fundiin App.
2. Fundiin sends the loan application to the selected lender and passes fundiinRequestId.
3. The lender notifies Fundiin about application lifecycle changes through Loan Application Status Notification.
4. After a loan or contract is created, the lender sends the latest loan summary and installment schedule through Installment Schedule Notification.
5. For repayment, the customer pays directly to the lender virtual account. The lender then sends Payment Received Notification and Repayment Notification to Fundiin.

Multiple Lender Invoice Selection

When a Fundiin user has invoices from multiple lenders, Fundiin App prevents cross-lender selection in the same repayment action.

If the user selects an invoice from Lender A, invoices from Lender B are disabled. Fundiin App displays a toast message using the same behavior as the existing BNPL invoice selection logic.

This rule keeps repayment, payment received, and debt clearance flows aligned to one lender at a time.

Base URL

Environment	URL
Sandbox	https://api-qa.fundiin.vn
Production	https://api.fundiin.vn

Webhook APIs

Webhook	Method	Endpoint	Purpose
Loan Application Status Notification	POST	/lender/open/notify/loan-application-status	Notify Fundiin about loan application, contract, and disbursement lifecycle updates. Fundiin updates loanStatus from this notification.
Payment Received Notification	POST	/lender/open/notify/payment-received	Notify Fundiin that the lender has successfully received a payment from the user, with transaction ID, bank sequence ID, and amount.
Installment Schedule Notification	POST	/lender/open/notify/installment-schedule	Sync the latest loan summary and installment schedule from the lender so Fundiin can display repayment schedule and status to customers.
Repayment Notification	POST	/lender/open/notify/repayment	Notify Fundiin about repayment or debt clearance allocation for the loan.

These notification APIs can be used depending on each lender's integration scope with Fundiin.

Security

Each webhook request must be signed by the lender using HMAC SHA-256.

Request Headers

Header Name	Type	Required	Description
Content-Type	String		application/json; charset=UTF-8
Client-Id	String		Partner ID assigned by Fundiin for the lender.
Signature	String		HMAC SHA-256 signature in hexadecimal format.

Signature Calculation

Signature = HMAC_SHA256(<raw request body>, secretKey)

The lender must:

1. Convert the request body to a JSON string.
2. Compute the HMAC SHA-256 hash using the shared secretKey.
3. Encode the hash in hexadecimal format.
4. Send the result in the Signature header.

See HMAC Signatures for implementation examples.

The JSON string used to create the signature must be the same body sent in the HTTP request. Avoid reformatting or reordering fields after calculating the signature.

Common Request Fields

Parameter	Type	Required	Description
requestId	String		Unique webhook request ID generated by the lender. Used for idempotency and tracing.
fundiinRequestId	String		Request ID previously passed by Fundiin to the lender.
lenderCode	String		Lender code assigned by Fundiin.
requestingDatetime	Timestamp		Request timestamp. Format: yyyy-MM-ddTHH:mm:ss+0700.

Common Response

Fundiin returns an HTTP status code and a responseCode.

{
  "responseCode": "SUCCESS",
  "responseMessage": "The request was successfully received and processed.",
  "responseTime": "2025-05-30T10:15:01+0700"
}

Common Response Codes

Response Code	HTTP Status	Meaning
SUCCESS	200 OK	The request was successfully received and processed.
BUSINESS_ERROR	200 OK	The request was received but contains a business logic error.
BAD_REQUEST	400 Bad Request	The request is invalid due to incorrect format or missing required fields.
UNAUTHORIZED	401 Unauthorized	The request failed HMAC signature validation or missing authentication headers.
FORBIDDEN	403 Forbidden	The API key is invalid or the partner is not authorized to access this resource.
NOT_FOUND	404 Not Found	The requested resource does not exist.
SYSTEM_ERROR	500 Internal Server Error	An unexpected error occurred on Fundiin's side. The lender should retry the request.

Error Handling and Retries

If Fundiin returns SYSTEM_ERROR or the webhook request times out, retry using exponential backoff. Recommended retry policy: maximum 3 retries over 10 minutes.

Do not retry requests that fail with BAD_REQUEST, UNAUTHORIZED, or FORBIDDEN until the payload, credentials, or signature issue is corrected.