Mercantil Settlement™ Partner API
Integra depósitos on-chain, conversiones, settlements y transferencias fiat. Un endpoint de eventos, webhooks firmados, sandbox aislado y paso a producción sin intervención manual.
Base URL
https://settlement.mercantil.com.do/api/v1
Auth
Authorization: Bearer sk_live_… + firma HMAC
Quick Start
Envía tu primer evento en 3 pasos:
1 · Genera una API key de test
Desde el Partner Dashboard genera una sk_test_… y tu signing_secret (se muestran una sola vez).
2 · Firma la petición
Calcula signature = HMAC_SHA256(timestamp + "." + nonce + "." + body, signing_secret) en hex.
3 · POST del evento
sk_test_; en producción sk_live_. Los datos de test nunca tocan settlements reales.Authentication
Cada petición requiere una API key (Bearer) y una firma HMAC. Cabeceras:
| Header | Descripción |
|---|---|
Authorization | Bearer sk_live_… / sk_test_… |
X-Mercantil-Timestamp | Unix epoch (segundos). Ventana ±300s. |
X-Mercantil-Nonce | Único por petición (replay protection). |
X-Mercantil-Signature | hex de HMAC_SHA256(ts.nonce.body, signing_secret) |
Idempotency-Key | Opcional; refuerza la idempotencia. |
Requisitos de seguridad: TLS obligatorio, IP allow-list opcional, scopes por key, rate limit por partner. Los secretos jamás se guardan en claro.
API Keys
Prefijos: sk_test_ (sandbox) y sk_live_ (producción). Se muestran una sola vez; solo se almacena su SHA-256. Cada key tiene scopes, último uso, IP, fecha de creación y expiración. Soporta rotación y revocación inmediata.
| Scope | Permite |
|---|---|
events:write | Enviar eventos a /partners/events |
events:read | Listar eventos y timelines |
Sandbox
Ambiente aislado con base separada por mode=test. Nunca contiene datos reales.
- Host dedicado:
sandbox.settlement.mercantil.com.do(acepta solosk_test_). - Mismo contrato de API que producción.
- Eventos y webhooks simulados; replay disponible.
- Logs completos por request.
settlement.mercantil.com.do) acepta únicamente sk_live_.Events
POST /partners/events. El cuerpo mínimo:
Catálogo de estados
| status | Estado interno |
|---|---|
ON_CHAIN_DEPOSIT_RECEIVED | CRYPTO_RECEIVED · Depósito on-chain recibido |
TRADE_COMPLETED | FX_CONVERTED · Conversión completada |
FIAT_TRANSFER_COMPLETED | FIAT_SETTLED · Transferencia fiat completada |
FIAT_TRANSFER_FAILED | FIAT_FAILED · Transferencia fiat fallida |
ON_CHAIN_SENT | CRYPTO_SENT · Envío on-chain emitido |
ON_CHAIN_CONFIRMED | CRYPTO_CONFIRMED · Envío on-chain confirmado |
SETTLEMENT_CREATED | PENDING · Settlement creado |
SETTLEMENT_APPROVED | APPROVED · Settlement aprobado |
SETTLEMENT_EXECUTED | EXECUTED · Settlement ejecutado |
SETTLEMENT_FAILED | FAILED · Settlement fallido |
COMPLIANCE_HOLD | COMPLIANCE_HOLD · Retención de compliance |
COMPLIANCE_RELEASED | COMPLIANCE_RELEASED · Liberada por compliance |
Respuesta 201 (nuevo) o 200 (duplicate:true):
Idempotency
Un evento nunca se procesa dos veces. La clave de idempotencia es eventId o la combinación transactionId + status. Un reenvío responde 200 con duplicate:true sin reprocesar ni reejecutar el workflow interno.
Webhooks
Registra un endpoint HTTPS y recibe eventos firmados. Cabecera:
X-Mercantil-Signature: t=<timestamp>,v1=<hmac> donde hmac = HMAC_SHA256(t + "." + body, whsec_…).
Reintentos automáticos con backoff (1m · 5m · 15m · 1h · 6h · 24h), replay manual e histórico completo (status HTTP, tiempo de respuesta, intentos, payload, headers).
Rate Limits
Límite por partner por minuto (configurable, default 120). Al exceder devuelve 429 rate_limited. Los reintentos deben respetar backoff exponencial.
Error Codes
| HTTP | error | Causa |
|---|---|---|
| 401 | unauthorized | Falta o formato inválido del Bearer |
| 401 | invalid_api_key | Key desconocida |
| 401 | api_key_revoked / api_key_expired | Key revocada/expirada |
| 401 | invalid_signature / invalid_timestamp | Firma o ventana de tiempo inválida |
| 403 | forbidden_scope | La key no tiene el scope requerido |
| 403 | ip_not_allowed | IP fuera de la allow-list |
| 403 | test_key_on_production / live_key_on_sandbox | Key en el host equivocado |
| 409 | nonce_reused | Nonce repetido (replay) |
| 422 | invalid_schema | Campos faltantes/ inválidos (ver fields) |
| 429 | rate_limited | Límite por minuto excedido |
API Explorer
Construye la petición y genera el curl firmado. (La firma se calcula localmente en tu servidor; aquí generamos el comando.)
— pulsa "Generar curl" —
SDK Examples
Ejemplos completos de firma + envío. Elige tu lenguaje:
Health
| Endpoint | Uso |
|---|---|
GET /health | Liveness básico |
GET /api/v1/status | Estado de componentes (db, webhooks, notif) |
GET /api/v1/version | Versión y release |
Changelog
| Versión | Cambios |
|---|---|
v1.0.0 | Partner API inicial: eventos, idempotencia, webhooks firmados, sandbox, dashboard, OpenAPI. |
FAQ
¿Cómo paso de sandbox a producción?
Genera una sk_live_, registra tu webhook de producción y apunta al host de producción. Mismo contrato.
¿Qué pasa si reenvío un evento?
Se responde duplicate:true sin reprocesar (idempotencia por eventId o transactionId+status).
¿Los secretos se pueden recuperar?
No. Las keys y secrets se muestran una sola vez; solo guardamos su hash cifrado. Usa rotación.