DOCSEARCHbyAlgolia
Submit Docs

Fundiin Developer Documentation

website·Indexed 35 days ago

https://docs.fundiin.vn/v2/

API and integration guides for Fundiin's Buy Now, Pay Later service. Includes documentation for payment processing (v2), tokenization, lender webhooks, and plugins for e-commerce platforms such as Shopify, WooCommerce, Haravan, and Magento.

Tokens
62K
Snippets
191
Records
365
Agent score
47%

What's inside Fundiin

  1. Overview of Fundiin Multi-Lender Webhook Integration

    v2
    Fundiin uses a multi-lender webhook architecture where lenders notify Fundiin of loan lifecycle events (disbursement, payment receipts, repayment allocations, and installment schedules). Because the endpoint paths are generic, Fundiin identifies the specific lender using the Client-Id header and the lenderCode field in the request body. Each webhook is acknowledged independently with an HTTP 200 response.

  2. Overview of Fundiin Lender Webhooks

    v2
    Fundiin provides a multi-lender webhook system where lenders notify Fundiin of loan lifecycle events (disbursement, payment receipts, repayment allocations, and installment schedule updates). Fundiin identifies the lender using the Client-Id and lenderCode provided in the request, and authenticates the request body via a Signature header.

  3. Overview of Fundiin Webhook Families

    v2

    Fundiin uses webhooks to synchronize systems after asynchronous events. There are two primary webhook families:

    1. Merchant payment notification: Sent from Fundiin to the merchant to notify them when a payment reaches a final or updated status.
    2. Lender lifecycle webhooks: Sent from the Lender to Fundiin to notify about loan status, installment schedules, payment receipts, and repayment allocation.

  4. Overview of Fundiin Financial Platform integration surfaces

    v2

    The Fundiin Financial Platform provides two distinct integration surfaces depending on the user's role:

    1. Merchant BNPL: Designed for merchants, commerce platforms, and checkout teams. It is used to integrate Fundiin BNPL into checkout, refund, status, tokenization, and on-page messaging flows.
    2. Lender Integration: Designed for lenders, loan systems, and repayment teams. It is used to synchronize loan lifecycles, installment schedules, payment receipts, and repayment allocation data with Fundiin.

    Both surfaces share common platform primitives, including environments, credentials, HMAC signing, idempotency, webhooks, sandbox testing, and go-live reviews.

  5. Pay for an order using tokenizations

    v2
    Use the POST /v2/tokenizations/pay endpoint to process a payment for an order via tokenization. This request requires detailed information about the transaction, including merchant identifiers, amount, installment details, line items, customer information, seller details, and shipping address.
    POST /v2/tokenizations/pay

  6. Create a payment request via POST /v2/payments

    v2

    The POST /v2/payments endpoint allows merchants to initiate a payment request to Fundiin. It supports installment-based payments and requires detailed information about the order, customer, and shipping.

    Endpoint Hosts:

    • Sandbox: https://gateway-sandbox.fundiin.vn/v2/payments (Development, SIT, UAT)
    • Production: https://gateway.fundiin.vn/v2/payments (Live)

    Key Constraints:

    • referenceId must match regex: ^[0-9a-zA-Z_-]{1,60}$.
    • items array maximum: 200 items.
    • amount.value must be in VND minor units.
    • shipping.country must be VN.
    curl --request POST 'https://gateway-sandbox.fundiin.vn/v2/payments' \
  --header 'Content-Type: application/json' \
  --header 'Client-Id: YOUR_CLIENT_ID' \
  --header 'Request-Time: YYYY-MM-DD hh:mm:ss' \
  --header 'Signature: HMAC_SHA256_REQUEST_BODY' \
  --header 'Idempotency-Key: ORDER-20260621-001' \
  --data-raw '{
"merchantId":"Your merchant code",
"referenceId":"Your order number",
"storeId":"Your store id",
"platformId":"Your platform id",
"requestType":"installment",
"paymentMethod":"WEB",
"terminalType":"DESKTOP_BROWSER",
"lang":"vi",
"extraData":"jsonstring",
"description":"description",
"successRedirectUrl":"https://merchant.example/success",
"unSuccessRedirectUrl":"https://merchant.example/failed",
"installment":{"packageId":"packageId"},
"amount":{"currency":"VND","value":400000},
"items":[{"productId":"170594","productName":"clothes","description":"Red","quantity":2,"price":200000,"currency":"VND","totalAmount":400000}],
"customer":{"phoneNumber":"0912345678","rank":"standard","description":"Customer description","email":"youremail@email.com","firstName":"Doe","lastName":"Test","gender":"F","dateOfBirth":"17-04-1999"},
"seller":{"id":"SELLER-001","email":"seller@example.com","name":"Seller Name","address":"Ho Chi Minh"},
"shipping":{"city":"Ho Chi Minh","zipCode":"00700","district":"5","ward":"","street":"Tran Nhan Ton","streetNumber":"Apt 214","houseNumber":"214","houseExtension":"","country":"VN"},
"transExpiredTime":1800000,
"sendSms":true,
"sendEmail":true
}'

  7. Configure the Payment Received Notification request body

    v2

    The request body for the payment receipt notification requires common request fields (defined in the Lender Notification API Overview) and the following specific parameters:

    • contractNumber (String): The contract number.
    • lenderReferenceId (String, Conditional): Stable application or loan identifier generated by the lender. Required if available at the time of receipt.
    • lenderTransactionCode (String): Unique transaction code generated by the lender; serves as the idempotency key for the payment event.
    • bankTransactionSequenceId (String, Conditional): Sequence ID assigned by the lender's bank. Used to link this event to a corresponding Repayment Allocation notification.
    • receivedAmount (Number): Amount received in VND.
    • receivedDatetime (Timestamp): Datetime the payment was received. Format: yyyy-MM-ddTHH:mm:ss+0700.
    • receivedStatus (String): Must be either SUCCESS or REVERSED.
    • reversalReason (String, Conditional): Required if receivedStatus is set to REVERSED.

  8. Configure Lender Lifecycle webhooks

    v2
    Lender webhooks are used to notify Fundiin about loan statuses, installment schedules, payment receipts, and repayment allocations. The following endpoints are used for these events:
    EventEndpoint
    Loan Application Status/lender/open/notify/loan-application-status
    Installment Schedule/lender/open/notify/installment-schedule
    Payment Receipt/lender/open/notify/payment-receipt
    Repayment Allocation/lender/open/notify/repayment-allocation

  9. Handle Merchant Payment Notification callbacks

    v2

    When Fundiin notifies a merchant about payment results, the merchant's implementation must meet these minimum handling requirements:

    • Verify the Signature header for security.
    • Match the incoming event to the corresponding referenceId.
    • Return the required acknowledgement response.
    • Implement safe internal processing retries using a custom idempotency key.

  10. Configure the Payment Received Notification request body

    v2

    The request body for the payment receipt notification requires common request fields (defined in the Lender Notification API Overview) and the following specific parameters:

    • contractNumber (String): The contract number.
    • lenderReferenceId (String, Conditional): Stable application or loan identifier generated by the lender. Required if available at the time of receipt.
    • lenderTransactionCode (String): Unique transaction code generated by the lender; serves as the idempotency key for the payment event.
    • bankTransactionSequenceId (String, Conditional): Sequence ID assigned by the lender's bank. Used to link this event to a corresponding Repayment Allocation notification.
    • receivedAmount (Number): Amount received in VND.
    • receivedDatetime (Timestamp): Datetime the payment was received. Format: yyyy-MM-ddTHH:mm:ss+0700.
    • receivedStatus (String): Must be either SUCCESS or REVERSED.
    • reversalReason (String, Conditional): Required when receivedStatus is set to REVERSED.

  11. Create a payment request via POST /v2/payments

    v2
    Use the POST /v2/payments endpoint to initiate a payment request from a Merchant to Fundiin. The request must be sent with Content-Type: application/json. This endpoint is used to set up installment payments, providing details about the customer, seller, shipping, and the items being purchased. Upon a successful request, the API returns a paymentUrl and qrData to redirect the user to the Fundiin payment gateway.
    POST /v2/payments

Request Body:
{
  "merchantId": "Your merchant code",
  "referenceId": "Your order number",
  "storeId": "Your store id",
  "platformId": "Your platform id",
  "requestType": "installment",
  "paymentMethod": "WEB",
  "terminalType": "DESKTOP_BROWSER",
  "lang": "vi",
  "extraData": "jsonstring",
  "description": "description",
  "successRedirectUrl": "https://merchant.example/success",
  "unSuccessRedirectUrl": "https://merchant.example/failed",
  "installment": {
    "packageId": "packageId"
  },
  "amount": {
    "currency": "VND",
    "value": 400000
  },
  "items": [
    {
      "productId": "170594",
      "productName": "clothes",
      "description": "Red",
      "quantity": 2,
      "price": 200000,
      "currency": "VND",
      "totalAmount": 400000
    }
  ],
  "customer": {
    "phoneNumber": "0912345678",
    "rank": "standard",
    "description": "Customer description",
    "email": "youremail@email.com",
    "firstName": "Doe",
    "lastName": "Test",
    "gender": "F",
    "dateOfBirth": "17-04-1999"
  },
  "seller": {
    "id": "SELLER-001",
    "email": "seller@example.com",
    "name": "Seller Name",
    "address": "Ho Chi Minh"
  },
  "shipping": {
    "city": "Ho Chi Minh",
    "zipCode": "00700",
    "district": "5",
    "ward": "",
    "street": "Tran Nhan Ton",
    "streetNumber": "Apt 214",
    "houseNumber": "214",
    "houseExtension": "",
    "country": "VN"
  },
  "transExpiredTime": 1800000,
  "sendSms": true,
  "sendEmail": true
}

Response Body:
{
  "merchantId": "FundiinVN",
  "referenceId": "Your order number",
  "responseTime": "2023-07-24 09:33:55",
  "resultMsg": "Thành công",
  "resultStatus": "APPROVED",
  "paymentUrl": "https://fundiin.vn/v2/payment",
  "qrData": "https://fundiin.vn/v2/payment"
}

  12. Create a payment request via POST /v2/payments

    v2
    The /v2/payments endpoint allows merchants to initiate a payment request to Fundiin. It supports installment payments and requires detailed information about the order, customer, and shipping.
    curl --request POST 'https://gateway-sandbox.fundiin.vn/v2/payments' \
  --header 'Content-Type: application/json' \
  --header 'Client-Id: YOUR_CLIENT_ID' \
  --header 'Request-Time: YYYY-MM-DD hh:mm:ss' \
  --header 'Signature: HMAC_SHA256_REQUEST_BODY' \
  --header 'Idempotency-Key: ORDER-20260621-001' \
  --data-raw '{
    "merchantId":"Your merchant code",
    "referenceId":"Your order number",
    "storeId":"Your store id",
    "platformId":"Your platform id",
    "requestType":"installment",
    "paymentMethod":"WEB",
    "terminalType":"DESKTOP_BROWSER",
    "lang":"vi",
    "extraData":"jsonstring",
    "description":"description",
    "successRedirectUrl":"https://merchant.example/success",
    "unSuccessRedirectUrl":"https://merchant.example/failed",
    "installment":{"packageId":"packageId"},
    "amount":{"currency":"VND","value":400000},
    "items":[{
      "productId":"170594",
      "productName":"clothes",
      "description":"Red",
      "quantity":2,
      "price":200000,
      "currency":"VND",
      "totalAmount":400000
    }],
    "customer":{
      "phoneNumber":"0912345678",
      "rank":"standard",
      "description":"Customer description",
      "email":"youremail@email.com",
      "firstName":"Doe",
      "lastName":"Test",
      "gender":"F",
      "dateOfBirth":"17-04-1999"
    },
    "seller":{
      "id":"SELLER-001",
      "email":"seller@example.com",
      "name":"Seller Name",
      "address":"Ho Chi Minh"
    },
    "shipping":{
      "city":"Ho Chi Minh",
      "zipCode":"00700",
      "district":"5",
      "ward":"",
      "street":"Tran Nhan Ton",
      "streetNumber":"Apt 214",
      "houseNumber":"214",
      "houseExtension":"",
      "country":"VN"
    },
    "transExpiredTime":1800000,
    "sendSms":true,
    "sendEmail":true
  }'