Settlement events

POST

https://api.opensylo.com/api/v1/webhooks/marketplace/settlement

Receives settlement events from the marketplace: settlement creation and
transfer confirmation. The request body is polymorphic, discriminated by
the event field.

Supported events:

settlement.created -- A settlement batch was created with loan deductions

settlement.transferred -- Settlement funds were transferred

Idempotency: Events are deduplicated by event_id.

Request

Authorization

API Key

Add parameter in header

X-Marketplace-Signature

Example:

X-Marketplace-Signature: ********************

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Webhook processed.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠409

🟠429

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.opensylo.com/api/v1/webhooks/marketplace/settlement' \
--header 'X-Marketplace-Timestamp: 1712495400' \
--header 'X-Marketplace-Id: mkt_live_abc123def456' \
--header 'X-Marketplace-Event-Id: evt_rp_20260407_001' \
--header 'X-Marketplace-Signature: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "event": "settlement.created",
    "event_id": "evt_stl_created_20260407_001",
    "timestamp": "2026-04-07T20:00:00.000Z",
    "marketplace": {
        "id": "mkt_live_abc123def456",
        "name": "Jumia Nigeria"
    },
    "settlement": {
        "reference": "STL-20260407-001",
        "period_start": "2026-04-01T00:00:00.000Z",
        "period_end": "2026-04-07T23:59:59.000Z",
        "settlement_date": "2026-04-08",
        "currency": "NGN"
    },
    "summary": {
        "total_amount": 85000,
        "transaction_count": 18,
        "by_status": {
            "successful": {
                "count": 15,
                "amount": 75000
            },
            "failed": {
                "count": 15,
                "amount": 75000
            },
            "reversed": {
                "count": 15,
                "amount": 75000
            }
        }
    },
    "loans_included": [
        {
            "opensylo_loan_id": "loan_f1e2d3c4-b5a6-7890-1234-567890abcdef",
            "deduction_count": 5,
            "total_amount": 25000,
            "transaction_references": [
                "DED-20260401-001",
                "DED-20260402-001",
                "DED-20260403-001",
                "DED-20260405-001",
                "DED-20260407-001"
            ]
        }
    ],
    "bank_transfer": {
        "expected_amount": 85000,
        "sender_name": "Jumia Nigeria Limited",
        "narration": "OpenSylo repayment settlement STL-20260407-001"
    }
}'

Response Example

200 - Success Example

{
    "status": "received",
    "event_id": "evt_stl_20260407_001",
    "opensylo_reference": "stl_a1b2c3d4",
    "received_at": "2026-04-07T14:35:00.000Z"
}

Modified at 2026-06-10 14:59:29

Repayment events

loan.approved