{
    "openapi": "3.0.3",
    "info": {
        "title": "Mercantil Settlement\u2122 Partner API",
        "version": "1.0.0",
        "description": "API institucional para integraciones B2B (PSPs, exchanges, bancos, fintechs, ERPs, payroll). Autenticaci\u00f3n por API key (Bearer sk_*) + firma HMAC-SHA256.",
        "contact": {
            "name": "Mercantil Settlement Developers",
            "url": "https://settlement.mercantil.com.do/docs"
        }
    },
    "servers": [
        {
            "url": "https://settlement.mercantil.com.do/api/v1",
            "description": "Producci\u00f3n / Sandbox (mismo host, aislado por modo de key)"
        },
        {
            "url": "https://sandbox.settlement.mercantil.com.do/api/v1",
            "description": "Sandbox dedicado (sk_test_)"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "sk_live_\u2026 / sk_test_\u2026",
                "description": "Authorization: Bearer sk_live_xxx. Adem\u00e1s: X-Mercantil-Timestamp, X-Mercantil-Nonce, X-Mercantil-Signature = HMAC_SHA256(timestamp.nonce.body, signing_secret)."
            }
        },
        "schemas": {
            "PartnerEvent": {
                "type": "object",
                "required": [
                    "eventId",
                    "transactionId",
                    "status",
                    "occurredAt"
                ],
                "properties": {
                    "eventId": {
                        "type": "string",
                        "example": "evt_9f8a72"
                    },
                    "transactionId": {
                        "type": "string",
                        "example": "txn_88213"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "ON_CHAIN_DEPOSIT_RECEIVED",
                            "TRADE_COMPLETED",
                            "FIAT_TRANSFER_COMPLETED",
                            "FIAT_TRANSFER_FAILED",
                            "ON_CHAIN_SENT",
                            "ON_CHAIN_CONFIRMED",
                            "SETTLEMENT_CREATED",
                            "SETTLEMENT_APPROVED",
                            "SETTLEMENT_EXECUTED",
                            "SETTLEMENT_FAILED",
                            "COMPLIANCE_HOLD",
                            "COMPLIANCE_RELEASED"
                        ],
                        "example": "ON_CHAIN_DEPOSIT_RECEIVED"
                    },
                    "occurredAt": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-09-11T05:04:43+00:00"
                    },
                    "amount": {
                        "type": "string",
                        "example": "1000"
                    },
                    "currency": {
                        "type": "string",
                        "enum": [
                            "USDC",
                            "USDT",
                            "DOP",
                            "USD"
                        ],
                        "example": "USDC"
                    }
                }
            },
            "EventAck": {
                "type": "object",
                "properties": {
                    "received": {
                        "type": "boolean"
                    },
                    "duplicate": {
                        "type": "boolean"
                    },
                    "eventRef": {
                        "type": "integer"
                    },
                    "internalStatus": {
                        "type": "string"
                    },
                    "correlationId": {
                        "type": "string"
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string"
                    },
                    "correlation_id": {
                        "type": "string"
                    }
                }
            }
        }
    },
    "security": [
        {
            "ApiKey": []
        }
    ],
    "paths": {
        "/partners/events": {
            "post": {
                "summary": "Ingesta de evento externo",
                "operationId": "createEvent",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PartnerEvent"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Aceptado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventAck"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Duplicado (idempotente)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventAck"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "No autorizado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Esquema inv\u00e1lido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit"
                    }
                }
            },
            "get": {
                "summary": "Listar eventos del partner",
                "operationId": "listEvents",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/partners/events/{transactionId}/timeline": {
            "get": {
                "summary": "Timeline de una transacci\u00f3n",
                "operationId": "timeline",
                "parameters": [
                    {
                        "name": "transactionId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/partners/event-types": {
            "get": {
                "summary": "Cat\u00e1logo de estados",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/status": {
            "get": {
                "summary": "Estado del servicio",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/version": {
            "get": {
                "summary": "Versi\u00f3n",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    }
}