{ "openapi": "3.0.3", "info": { "title": "Tilopay API BaaS", "version": "1.0.0", "description": "The Tilopay API BaaS lets merchants and integrated clients initiate\npayments (PIN and SINPE Móvil), check their status, manage accounts, and\nsubscribe to payment event webhooks — all scoped to the accounts the access\ntoken is authorized for.\n\n**Authentication**\n1. `POST /auth/login` — authenticates the client with its credentials and\n returns a GIDP ID token plus the available assignments (tenant/account\n contexts the client can act as).\n2. `POST /auth/token/exchange` — exchanges that ID token, together with the\n chosen `assignment_id`, for an access token (JWT).\n3. Send that JWT as `Authorization: Bearer ` on every subsequent call.\n The token determines the visible accounts automatically — never send\n `tenant_id`, `owner_id`, or `owner_type` in the body or query params of\n other endpoints.\n\n**Response format**\nEvery response uses the same envelope:\n```json\n{\n \"success\": true,\n \"http_status_code\": 200,\n \"response_code\": \"OK\",\n \"message\": \"The request was processed successfully.\",\n \"correlation_id\": \"...\",\n \"data\": { }\n}\n```\nOn error, `success` is `false`, `data` is absent, and `errors` carries\nadditional detail instead. `response_code` is always one of the values in\nthe `ResponseCode` schema — never a free-form string.\n\n**Correlation.** Send `X-Correlation-Id` on any request to trace it end-to-end; the\nsame value is always echoed back as `correlation_id` in the response envelope. If\nomitted, one is generated for you and still returned.\n\n**Idempotency.** `Idempotency-Key` is only implemented on\n`POST /api/public/v1/transactions/payments` (payment creation). Other POST endpoints\ndo not read or honor this header today — retries there are not deduplicated by key.\n\n**Walking the API**\n- **Payments** — create, check, and search payments (PIN, SINPE Móvil).\n- **Accounts** — validate destination accounts, list accounts and balances, request statements.\n- **Webhooks** — subscribe to payment events (succeeded, failed, reversed, payin\n received) with HMAC signing or optional encryption.\n- **Catalogs** — supporting catalogs (identification types by country).\n\n## Account identification standard\n\nAccounts are always identified by an **identifier scheme** plus a **value**\n(for example `type=IBAN` and the IBAN string). This is **not** the internal\naccount classification (e.g. `operational`).\n\n- **Request/response bodies:** `account: { type, value }`\n- **Query parameters:** `type` + `value` (same meaning as the body fields)\n\nSee `docs/ACCOUNT-IDENTIFIERS.md`.\n\n## Party identification (`identification.number`)\n\nPayment `source.identification` / `destination.identification` use platform catalog\nkeys (`cedula`, `juridica`, `dimex`, …) and a **public number**: the value submitted\non create, digits without SINPE hyphenation (not `01-1234-3005`).\n\nCreate stores that public value separately from the internal GX/SINPE form used to\ntalk to the rail. Subsequent reads (`GET /transactions/payments`,\n`GET /transactions/payments/{payment_id}`, `POST /transactions/payments/search`)\nreturn the same public number. Create `data` remains the compact ack\n(`payment_id`, `public_id`, `status`, …); identification is on the read APIs.\n\nPayments created **before** this persistence may still return the hyphenated SINPE\ndisplay form previously stored for GX resend. Those historical values are not\nrewritten. See `docs/PAYMENT-IDENTIFICATION.md`.\n\n## Webhook naming: payment vs payin/payout vs transaction\n\n- **payment**: the money-movement resource. The webhook envelope object is always\n `payment`. Outcome events use the `payment.*` prefix (`payment.succeeded`,\n `payment.succeeded`, `payment.failed`, `payment.reversed`). Correlate with REST `GET /transactions/payments` using\n `payment.public_id` or `payment.payment_id`.\n- **payin / payout**: direction of that payment (`PAYIN` inbound, `PAYOUT` outbound),\n same as REST `type`. `payin.posted` fires only when an inbound payment is\n ledger-posted (funds received). There is no public `payout.posted`.\n `payment.succeeded`, `payment.failed`, and `payment.reversed` apply to both directions.\n- **transaction**: REST URL namespace only (`/api/public/v1/transactions/...`).\n Not a webhook object and not an `event_type` prefix. There are no `transaction.*` events.\n\n## status vs result vs event_type\n\nThese fields are orthogonal. Do not treat them as aliases.\n\n- **status** — processing/lifecycle of the payment resource (`pending`, `processing`,\n `confirmed`, `posted`, `failed`). A later reversal does **not** change `status`\n to `failed`; a posted payment stays `posted`.\n- **result** — business outcome for reconciliation (`pending`, `succeeded`, `failed`,\n `reversed`). `reversed` when `has_reversal` is true.\n- **has_reversal** — boolean fact that a reversal was applied.\n- **event_type** (webhooks) — what just happened: `payment.succeeded` (provider\n confirmed success), `payment.failed` (processing ended in failure), `payment.reversed`\n (subsequent reversal of a payment that already progressed).\n\n## REST ↔ webhook payment contract (`payment.succeeded` / `payment.failed`)\n\nREST payment reads (`GET /transactions/payments`, `POST /transactions/payments/search`,\n`GET /transactions/payments/{payment_id}`) and webhooks `payment.succeeded` /\n`payment.failed` use the **same name, location, and meaning** for:\n\n- `schema_version` — `1.0.0` (REST: on `data` / each payment; webhook: envelope root)\n- `payment.external_reference` — rail/SINPE id (`metadata.sinpe_reference`, else\n `external_provider_tx_id`). Sibling of `client_reference`. `null` if none.\n- `payment.error` — `domain` + `platform.code` / `platform.message` (failed/reversed only)\n- `provider` — shared object on REST and webhooks: `correlation_id`, `occurred_at`,\n `provider_status_code`, `provider_status_desc`, `provider_status_semantic`.\n `provider.correlation_id` is the transaction UUID (`execution.correlation_id`),\n not `channel_reference`. Rail reference lives only on `payment.external_reference`.\n\nSee `docs/WEBHOOKS.md` §6.\n\nDeduplicate webhook deliveries with `event.event_id`.\n\n## Timestamps (RFC 3339)\n\nAll public datetime fields (REST and webhooks) use **RFC 3339** with this precision policy:\n\n- **UTC** with a `Z` suffix (never a numeric offset such as `+00:00`)\n- **Second precision** — fractional seconds are never emitted\n- Canonical example: `2026-01-15T12:00:00Z`\n\nRequests (`date_from`, `date_to`, and similar filters) may include a numeric offset\nor fractional seconds; they are interpreted as UTC and truncated to seconds.\nIntegrators should parse RFC 3339 rather than requiring a single incoming string\nlayout, but responses are stable for strict validators\n(`YYYY-MM-DDTHH:MM:SSZ`).\n" }, "servers": [ { "url": "https://api-baas-sandbox.tilopay.com" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "General", "description": "Health check and other cross-cutting endpoints." }, { "name": "Docs", "description": "Meta endpoints: raw spec and interactive docs UI." }, { "name": "Auth", "description": "Login and token exchange. These endpoints do not require a Bearer token." }, { "name": "Payments", "description": "Create, check, and search payments (PIN, SINPE Móvil), and validate destination accounts." }, { "name": "Accounts", "description": "List accessible accounts and their balances, and request account statements." }, { "name": "Webhooks", "description": "Manage webhook destinations and inspect the outbound payload contract for each event type." }, { "name": "Catalogs", "description": "Supporting reference catalogs (e.g. identification types by country)." } ], "paths": { "/openapi.yaml": { "get": { "summary": "OpenAPI specification file", "security": [], "tags": [ "Docs" ], "responses": { "200": { "description": "OpenAPI yaml", "content": { "application/yaml": { "schema": { "type": "string" } } } } } } }, "/docs": { "get": { "summary": "Scalar API documentation UI", "security": [], "tags": [ "Docs" ], "responses": { "200": { "description": "HTML docs page", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/api/public/v1/healthz": { "get": { "summary": "Health check", "security": [], "tags": [ "General" ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "message": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" } }, "required": [ "message", "service" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "500": { "content": { "application/json": { "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ], "description": "An unexpected error occurred. Please try again later." }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/auth/login": { "post": { "summary": "Login", "description": "Authenticates a customer and returns a GIDP ID token plus the available\ncustomer assignments for context selection. Use `assignment_id` with\n`gidp_id_token` in `POST /api/public/v1/auth/token/exchange` to obtain an access token.\n", "security": [], "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLoginRequest" } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "assignments": { "items": { "properties": { "assignment_id": { "type": "string" }, "country_code": { "type": "string" }, "owner_id": { "type": "string" }, "owner_type": { "type": "string" }, "role": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" }, "status": { "type": "string" }, "tenant_code": { "type": "string" }, "tenant_id": { "type": "string" } }, "required": [ "assignment_id", "owner_type", "owner_id", "tenant_id", "tenant_code", "country_code", "role", "roles", "status" ], "type": "object" }, "type": "array" }, "gidp_id_token": { "type": "string" } }, "required": [ "assignments", "gidp_id_token" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Invalid email or password.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INVALID_CREDENTIALS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_INVALID_CREDENTIALS": { "$ref": "#/components/examples/Error_INVALID_CREDENTIALS" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_CREDENTIALS", "message": "Invalid email or password." }, "http_status_code": 401, "message": "Invalid email or password.", "response_code": "INVALID_CREDENTIALS", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "INVALID_CREDENTIALS", "message": "Invalid email or password." } ] }, "403": { "content": { "application/json": { "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ], "description": "You do not have permission to perform this action." }, "500": { "content": { "application/json": { "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ], "description": "An unexpected error occurred. Please try again later." }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/auth/token/exchange": { "post": { "summary": "Exchange external token", "description": "Exchanges the `gidp_id_token` obtained from login, together with the\nchosen `assignment_id`, for an access token (JWT). Send that token as\n`Authorization: Bearer ` on every other endpoint.\n", "security": [], "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerExchangeRequest" } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "claims": { "properties": { "channel": { "type": "string" }, "country_code": { "type": "string" }, "idempotency_key": { "type": "string" }, "idp": { "type": "string" }, "idp_sub": { "type": "string" }, "locale": { "type": "string" }, "owner_id": { "type": "string" }, "owner_type": { "type": "string" }, "roles": { "items": { "type": "string" }, "type": "array" }, "scopes": { "items": { "type": "string" }, "type": "array" }, "sub": { "type": "string" }, "subject_kind": { "type": "string" }, "tenant_id": { "type": "string" }, "user_type": { "type": "string" } }, "required": [ "channel", "country_code", "idempotency_key", "idp", "idp_sub", "locale", "owner_id", "owner_type", "roles", "scopes", "sub", "subject_kind", "tenant_id", "user_type" ], "type": "object" }, "expires_in": { "type": "integer" }, "token": { "type": "string" } }, "required": [ "claims", "expires_in", "token" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "content": { "application/json": { "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ], "description": "You do not have permission to perform this action." }, "500": { "content": { "application/json": { "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ], "description": "An unexpected error occurred. Please try again later." }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/auth/request-set-password": { "post": { "summary": "Request set password", "description": "Starts the password set/reset process for the given email. Does not\nrequire prior authentication. Always responds the same way whether or\nnot the email exists, to avoid revealing account existence.\n", "security": [], "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPasswordResetRequest" } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "500": { "content": { "application/json": { "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ], "description": "An unexpected error occurred. Please try again later." }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/transactions/payments": { "get": { "operationId": "getPublicListPayments", "summary": "List customer payments", "description": "Simple REST list of payments for an owned account (IBAN).\n\nFilters are query parameters. Ownership (`tenant_id`, `owner_type`, `owner_id`)\nis derived from the access token; clients must not send ownership filters.\n\n**Account identification (required):** `type` + `value` (identifier\nscheme + value, e.g. `IBAN` + IBAN string). This is not the internal\naccount classification.\n\nPagination is cursor-based (`limit`, `cursor`). Default limit is 20 (max 100).\n\n`status` in the response and as a filter uses the public lowercase catalog\n(`pending`, `processing`, `confirmed`, `posted`, `failed`). Same values as webhooks.\nREST also returns `status_detail` (uppercase operational name).\n\nEach item includes a consolidated `result` (`succeeded`, `failed`, `reversed`, `pending`)\nfor reconciliation when a webhook was missed. `status` is only the processing/lifecycle\ncatalog and does not change to `failed` when a posted payment is later reversed —\nuse `result=reversed` and `has_reversal=true` (webhook `payment.reversed`).\n`error` is `null` when there is no failure information; it is an object only when\n`domain` / `platform` is present (`result` is `failed` or `reversed`), same shape\nas webhook `payment.failed` `payment.error`.\n`source` / `destination` use `null` for unknown `account`, `name`, and `identification`;\naccount values are IBAN or PHONE only (never ledger UUIDs).\nFor PIN payments created after public identification persistence,\n`identification.number` is the partner-submitted public number (no SINPE hyphens);\nolder payments may still show the hyphenated SINPE form. See `docs/PAYMENT-IDENTIFICATION.md`.\n", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/AccountIdentifierType" }, { "$ref": "#/components/parameters/AccountIdentifierValue" }, { "name": "status", "in": "query", "required": false, "description": "Optional payment status filter. Public catalog is lowercase:\n`pending`, `processing`, `confirmed`, `posted`, `failed`.\nUppercase aliases of the same values are accepted. Legacy values\nsuch as `INITIATED` map to `pending`.\n", "schema": { "$ref": "#/components/schemas/PublicPaymentStatus" } }, { "name": "date_from", "in": "query", "required": false, "description": "Inclusive lower bound for `created_at`. RFC 3339 (UTC `Z` or offset; optional fractional seconds).", "schema": { "$ref": "#/components/schemas/Rfc3339DateTimeInput" }, "example": "2026-01-01T00:00:00Z" }, { "name": "date_to", "in": "query", "required": false, "description": "Inclusive upper bound for `created_at`. RFC 3339 (UTC `Z` or offset; optional fractional seconds).", "schema": { "$ref": "#/components/schemas/Rfc3339DateTimeInput" }, "example": "2026-01-31T23:59:59Z" }, { "name": "client_reference", "in": "query", "required": false, "description": "Filter by partner client reference (exact match against the value sent at payment creation).", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Filter by payment currency (ISO 4217, e.g. CRC).", "schema": { "type": "string" }, "example": "CRC" }, { "name": "payment_method_code", "in": "query", "required": false, "description": "Filter by public payment method code.", "schema": { "type": "string", "enum": [ "PIN", "SINPE_MOVIL" ] }, "example": "PIN" }, { "name": "direction", "in": "query", "required": false, "description": "Filter by payment direction. Accepts public values `OUT`/`IN` or\n`PAYOUT`/`PAYIN` (internally normalized to `payout`/`payin`).\n", "schema": { "type": "string", "enum": [ "OUT", "IN", "PAYOUT", "PAYIN" ] }, "example": "OUT" }, { "name": "limit", "in": "query", "required": false, "description": "Page size (default 20, max 100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response `pagination.next_cursor`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "items": { "items": { "properties": { "amount": { "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "client_reference": { "type": "string" }, "created_at": { "type": "string" }, "destination": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "identification": { "properties": { "number": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "number" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "account", "name", "identification" ], "type": "object" }, "error": { "properties": { "domain": { "type": "string" }, "platform": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "domain", "platform" ], "type": "object" }, "external_reference": { "type": "string" }, "has_reversal": { "type": "boolean" }, "payment_id": { "type": "string" }, "payment_method_code": { "type": "string" }, "provider": { "properties": { "correlation_id": { "type": "string" }, "occurred_at": { "type": "string" }, "provider_status_code": { "type": "string" }, "provider_status_desc": { "type": "string" }, "provider_status_semantic": { "type": "string" } }, "required": [ "correlation_id", "occurred_at", "provider_status_code", "provider_status_desc", "provider_status_semantic" ], "type": "object" }, "public_id": { "type": "string" }, "result": { "type": "string" }, "reversed_at": { "type": "string" }, "schema_version": { "type": "string" }, "source": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "identification": { "properties": { "number": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "number" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "account", "name", "identification" ], "type": "object" }, "status": { "type": "string" }, "status_detail": { "type": "string" }, "succeeded_at": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "schema_version", "payment_id", "public_id", "type", "payment_method_code", "status", "result", "succeeded_at", "has_reversal", "reversed_at", "created_at", "updated_at", "amount", "source", "destination", "client_reference", "external_reference", "provider", "error" ], "type": "object" }, "type": "array" }, "pagination": { "properties": { "limit": { "type": "integer" }, "next_cursor": { "type": "string" } }, "required": [ "limit" ], "type": "object" }, "schema_version": { "type": "string" } }, "required": [ "schema_version", "items" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 5, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "429": { "description": "Too many requests. Please retry after a short delay.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ] }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 8, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Unable to complete the request with the payment provider. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PROVIDER_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PROVIDER_ERROR": { "$ref": "#/components/examples/Error_PROVIDER_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "payload": null, "response_code": "PROVIDER_ERROR", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." } ] }, "503": { "description": "A required service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ] } } }, "post": { "summary": "Create payment", "description": "Creates a payment using an authorized internal source account. Processing may be asynchronous; HTTP 201 does not imply the payment is finalized.\n`source.identification.number` and `destination.identification.number` are stored in public form (the submitted digits, without SINPE hyphens) and returned on later payment reads. The GX/SINPE hyphenated form is used only internally and is not the public contract.\nIdempotency-Key is optional; if omitted, each request is treated as a new attempt. A repeated `client_reference` returns 409 PAYMENT_DUPLICATE when an in-flight or completed payment already uses it; a prior `failed` (or rejected/cancelled/expired) payment does not block a retry with the same `client_reference`. If Idempotency-Key is provided, the same key with the same payload replays the prior response; a different payload with the same key returns 409 IDEMPOTENCY_CONFLICT.\n", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9._-]+$", "description": "Optional opaque client key for safe retries. When omitted, each call is a new attempt (duplicates are detected by client_reference on in-flight or completed payments). Reusing a key with a different body returns 409." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "responses": { "201": { "description": "The resource was created successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "created_at": { "type": "string" }, "payment_id": { "type": "string" }, "payment_method_code": { "type": "string" }, "public_id": { "type": "string" }, "status": { "type": "string" }, "status_detail": { "type": "string" } }, "required": [ "payment_id", "public_id", "status", "status_detail", "payment_method_code", "created_at" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "CREATED" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid payment request payload.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PAYMENT_INVALID_PAYLOAD", "INVALID_PAYMENT_METHOD", "INVALID_ACCOUNT_TYPE", "ACCOUNT_INVALID", "ACCOUNT_HOLDER_MISMATCH" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PAYMENT_INVALID_PAYLOAD": { "$ref": "#/components/examples/Error_PAYMENT_INVALID_PAYLOAD" }, "Error_INVALID_PAYMENT_METHOD": { "$ref": "#/components/examples/Error_INVALID_PAYMENT_METHOD" }, "Error_INVALID_ACCOUNT_TYPE": { "$ref": "#/components/examples/Error_INVALID_ACCOUNT_TYPE" }, "Error_ACCOUNT_INVALID": { "$ref": "#/components/examples/Error_ACCOUNT_INVALID" }, "Error_ACCOUNT_HOLDER_MISMATCH": { "$ref": "#/components/examples/Error_ACCOUNT_HOLDER_MISMATCH" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PAYMENT_INVALID_PAYLOAD", "message": "Invalid payment request payload." }, "http_status_code": 400, "message": "Invalid payment request payload.", "payload": null, "response_code": "PAYMENT_INVALID_PAYLOAD", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "PAYMENT_INVALID_PAYLOAD", "message": "Invalid payment request payload." }, { "number": 5, "code": "INVALID_PAYMENT_METHOD", "message": "Invalid or unsupported payment method." }, { "number": 6, "code": "INVALID_ACCOUNT_TYPE", "message": "Unsupported or invalid account type." }, { "number": 8, "code": "ACCOUNT_INVALID", "message": "The account is invalid or not enabled for the service." }, { "number": 9, "code": "ACCOUNT_HOLDER_MISMATCH", "message": "Account holder does not match the provided identification or name." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 7, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "404": { "content": { "application/json": { "examples": { "Error_ACCOUNT_NOT_FOUND": { "$ref": "#/components/examples/Error_ACCOUNT_NOT_FOUND" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "ACCOUNT_NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_NOT_FOUND", "message": "Account not found." }, "http_status_code": 404, "message": "Account not found.", "payload": null, "response_code": "ACCOUNT_NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 10, "code": "ACCOUNT_NOT_FOUND", "message": "Account not found." } ], "description": "Account not found." }, "409": { "description": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "IDEMPOTENCY_CONFLICT", "PAYMENT_DUPLICATE", "CONFLICT" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_IDEMPOTENCY_CONFLICT": { "$ref": "#/components/examples/Error_IDEMPOTENCY_CONFLICT" }, "Error_PAYMENT_DUPLICATE": { "$ref": "#/components/examples/Error_PAYMENT_DUPLICATE" }, "Error_CONFLICT": { "$ref": "#/components/examples/Error_CONFLICT" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress." }, "http_status_code": 409, "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress.", "payload": null, "response_code": "IDEMPOTENCY_CONFLICT", "success": false } } }, "x-error-codes": [ { "number": 11, "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress." }, { "number": 12, "code": "PAYMENT_DUPLICATE", "message": "An in-flight or completed payment with this client_reference already exists." }, { "number": 13, "code": "CONFLICT", "message": "The request conflicts with the current state." } ] }, "422": { "content": { "application/json": { "examples": { "Error_INSUFFICIENT_FUNDS": { "$ref": "#/components/examples/Error_INSUFFICIENT_FUNDS" }, "Error_LIMIT_EXCEEDED": { "$ref": "#/components/examples/Error_LIMIT_EXCEEDED" }, "Error_UNPROCESSABLE_ENTITY": { "$ref": "#/components/examples/Error_UNPROCESSABLE_ENTITY" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INSUFFICIENT_FUNDS", "LIMIT_EXCEEDED", "UNPROCESSABLE_ENTITY" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient funds to complete the payment." }, "http_status_code": 422, "message": "Insufficient funds to complete the payment.", "payload": null, "response_code": "INSUFFICIENT_FUNDS", "success": false } } }, "x-error-codes": [ { "number": 14, "code": "INSUFFICIENT_FUNDS", "message": "Insufficient funds to complete the payment." }, { "number": 15, "code": "LIMIT_EXCEEDED", "message": "A transaction or accumulation limit was exceeded." }, { "number": 16, "code": "UNPROCESSABLE_ENTITY", "message": "The request is well-formed but cannot be processed due to business rules." } ], "description": "Insufficient funds to complete the payment." }, "429": { "description": "Too many requests. Please retry after a short delay.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ] }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 19, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Unable to complete the request with the payment provider. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PROVIDER_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PROVIDER_ERROR": { "$ref": "#/components/examples/Error_PROVIDER_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "payload": null, "response_code": "PROVIDER_ERROR", "success": false } } }, "x-error-codes": [ { "number": 17, "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." } ] }, "503": { "description": "A required service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 18, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ] } } } }, "/api/public/v1/transactions/payments/search": { "post": { "operationId": "postPublicPaymentSearch", "summary": "Search payment by identifier", "description": "Looks up a single payment within the supplied customer account by exactly one of:\n- `payment_id` (internal UUID)\n- `public_id` (numeric public identifier)\n- `client_reference` (partner reference sent at creation)\n\nSending more than one identifier returns `400`. Response shape matches get-by-id\n(`schema_version`, payment-level `external_reference`, shared `provider` object,\n`provider.provider_status_*`, webhook-aligned `error`). Same public contract as\n`GET /transactions/payments`, including public `identification.number` for PIN\npayments created after public identification persistence.\nIf several payments share a `client_reference` (failed attempt plus retry), the in-flight or completed payment is returned when one exists.\n", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPaymentRequest" }, "examples": { "byPaymentId": { "summary": "Lookup by payment UUID", "value": { "account": { "type": "IBAN", "value": "CR08036900101010933608" }, "payment_id": "11111111-1111-1111-1111-111111111111" } }, "byPublicId": { "summary": "Lookup by public_id", "value": { "account": { "type": "IBAN", "value": "CR08036900101010933608" }, "public_id": "134729" } }, "byClientReference": { "summary": "Lookup by client_reference", "value": { "account": { "type": "IBAN", "value": "CR08036900101010933608" }, "client_reference": "INV-01082" } } } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "amount": { "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "client_reference": { "type": "string" }, "created_at": { "type": "string" }, "destination": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "identification": { "properties": { "number": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "number" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "account", "name", "identification" ], "type": "object" }, "error": { "properties": { "domain": { "type": "string" }, "platform": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "domain", "platform" ], "type": "object" }, "external_reference": { "type": "string" }, "has_reversal": { "type": "boolean" }, "payment_id": { "type": "string" }, "payment_method_code": { "type": "string" }, "provider": { "properties": { "correlation_id": { "type": "string" }, "occurred_at": { "type": "string" }, "provider_status_code": { "type": "string" }, "provider_status_desc": { "type": "string" }, "provider_status_semantic": { "type": "string" } }, "required": [ "correlation_id", "occurred_at", "provider_status_code", "provider_status_desc", "provider_status_semantic" ], "type": "object" }, "public_id": { "type": "string" }, "result": { "type": "string" }, "reversed_at": { "type": "string" }, "schema_version": { "type": "string" }, "source": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "identification": { "properties": { "number": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "number" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "account", "name", "identification" ], "type": "object" }, "status": { "type": "string" }, "status_detail": { "type": "string" }, "succeeded_at": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "schema_version", "payment_id", "public_id", "type", "payment_method_code", "status", "result", "succeeded_at", "has_reversal", "reversed_at", "created_at", "updated_at", "amount", "source", "destination", "client_reference", "external_reference", "provider", "error" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 5, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "404": { "description": "Payment not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PAYMENT_NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PAYMENT_NOT_FOUND": { "$ref": "#/components/examples/Error_PAYMENT_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PAYMENT_NOT_FOUND", "message": "Payment not found." }, "http_status_code": 404, "message": "Payment not found.", "payload": null, "response_code": "PAYMENT_NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "PAYMENT_NOT_FOUND", "message": "Payment not found." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 9, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Unable to complete the request with the payment provider. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PROVIDER_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PROVIDER_ERROR": { "$ref": "#/components/examples/Error_PROVIDER_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "payload": null, "response_code": "PROVIDER_ERROR", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 8, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/transactions/payments/{payment_id}": { "get": { "operationId": "getPublicPaymentById", "summary": "Get payment by id", "description": "Returns a single payment using the same public contract as the list endpoint,\nincluding consolidated `result`, `succeeded_at`, `has_reversal`, and `error`.\n`error` is `null` when there is no failure information; it is an object only when\n`domain` / `platform` is present (`result` is `failed` or `reversed`), same shape\nas webhook `payment.failed` `payment.error`.\n`source` / `destination` use `null` for unknown nested fields and never expose ledger UUIDs.\n`identification.number` on PIN payments created after public identification persistence\nis the partner-submitted public number (digits, no SINPE hyphens). Older payments may\nstill return the hyphenated SINPE form from processing metadata.\nUse this as a webhook backup.\n\nLooks up a payment by either identifier:\n- `payment_id` (internal UUID)\n- `public_id` (numeric public identifier)\n\nFor `client_reference`, use `POST /api/public/v1/transactions/payments/search`.\n", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "payment_id", "in": "path", "required": true, "description": "Internal payment UUID or numeric public_id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "amount": { "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "client_reference": { "type": "string" }, "created_at": { "type": "string" }, "destination": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "identification": { "properties": { "number": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "number" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "account", "name", "identification" ], "type": "object" }, "error": { "properties": { "domain": { "type": "string" }, "platform": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "domain", "platform" ], "type": "object" }, "external_reference": { "type": "string" }, "has_reversal": { "type": "boolean" }, "payment_id": { "type": "string" }, "payment_method_code": { "type": "string" }, "provider": { "properties": { "correlation_id": { "type": "string" }, "occurred_at": { "type": "string" }, "provider_status_code": { "type": "string" }, "provider_status_desc": { "type": "string" }, "provider_status_semantic": { "type": "string" } }, "required": [ "correlation_id", "occurred_at", "provider_status_code", "provider_status_desc", "provider_status_semantic" ], "type": "object" }, "public_id": { "type": "string" }, "result": { "type": "string" }, "reversed_at": { "type": "string" }, "schema_version": { "type": "string" }, "source": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "identification": { "properties": { "number": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "number" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "account", "name", "identification" ], "type": "object" }, "status": { "type": "string" }, "status_detail": { "type": "string" }, "succeeded_at": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "schema_version", "payment_id", "public_id", "type", "payment_method_code", "status", "result", "succeeded_at", "has_reversal", "reversed_at", "created_at", "updated_at", "amount", "source", "destination", "client_reference", "external_reference", "provider", "error" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "content": { "application/json": { "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ], "description": "Invalid request. Check the required fields and try again." }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 5, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "404": { "description": "Payment not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PAYMENT_NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PAYMENT_NOT_FOUND": { "$ref": "#/components/examples/Error_PAYMENT_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PAYMENT_NOT_FOUND", "message": "Payment not found." }, "http_status_code": 404, "message": "Payment not found.", "payload": null, "response_code": "PAYMENT_NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "PAYMENT_NOT_FOUND", "message": "Payment not found." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 9, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Unable to complete the request with the payment provider. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PROVIDER_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PROVIDER_ERROR": { "$ref": "#/components/examples/Error_PROVIDER_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "payload": null, "response_code": "PROVIDER_ERROR", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 8, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/accounts/validate": { "post": { "summary": "Validate external account for a payment method", "description": "Validates a counterparty account (IBAN or phone) via the SINPE provider for the given payment method.\nDoes not validate internal ledger accounts.\nWhen valid, `data.holder.id_type` uses the same identification catalog keys as\n`identification.type` in `POST /payments` (e.g. `cedula`, `juridica`, `dimex`).\n\n## SINPE_MOVIL field availability (expected, stable)\n\nFor `payment_method_code = SINPE_MOVIL`, the backing wallet operation\n(`ObtenerInfoMonedero`) does not return identification type or institution name.\nA successful validation **may** therefore return:\n\n- `data.holder.id_type` = `unknown`\n- `data.financial_institution.entity_name` = `\"\"` (empty string)\n\nThis is **expected, stable behavior**, not a mapping bug or a transient provider error.\nPIN (`ObtenerInformacionCuentaSinpe`) does populate both fields.\n\nIntegrators must not report these values as defects, and must not assume that\n`holder.id_type` or `financial_institution.entity_name` are always populated\nwhen `is_valid` is true.\n\n## SINPE rejection codes (`data.rejection`)\n\nWhen `is_valid` is `false`, `data.rejection` explains why (see the `rejected`\nexample on the `200` response below). `rejection.code` is one of a fixed set of\nnormalized semantics (see the `WebhookRejection.code` schema enum). **Most rows in\nthe table below do NOT get a distinct `code`** — only a subset of `reason_code`\nvalues has a dedicated semantic; every other `reason_code`, even one listed below\nwith a specific `message`, returns `code = SINPE_REJECTED` (e.g. `reason_code = 21`\n\"fondos insuficientes\" still returns `SINPE_REJECTED`). This same object and\ncatalog is also used by the `payment.failed` webhook's `rejection` field.\nA `reason_code` not listed here at all still produces a response — `message` falls\nback to a generic text and `code` falls back to `SINPE_REJECTED`.\n\n**Cuenta / perfil / límites**\n\n| Code | Message |\n|---|---|\n| 21 | Cuenta Cliente con fondos insuficientes |\n| 22 | Cuenta Cliente no admite créditos |\n| 23 | Cuenta Cliente cerrada |\n| 24 | Cuenta Cliente inactiva |\n| 25 | Cuenta Cliente no admite débitos |\n| 26 | Cuenta Cliente no es de fondos |\n| 27 | Moneda de la Cuenta Cliente no corresponde |\n| 28 | Cuenta cliente no existe |\n| 29 | Cuenta Cliente no registrada en el SINPE |\n| 30 | Cuenta Cliente no habilitada para el servicio |\n| 31 | Cuenta Cliente bloqueada |\n| 32 | Id cliente destino no coincide con registrado en la entidad |\n| 33 | Nombre del cliente destino no coincide con el registrado en la entidad |\n| 34 | Cuenta Cliente en proceso de cierre |\n| 35 | Cuenta Cliente embargada |\n| 36 | Cuenta Cliente con retención judicial |\n| 37 | Cuenta de expediente simplificado no permite el monto indicado |\n| 38 | Límite transaccional de la Cuenta Cliente excedido |\n| 39 | Cuenta Cliente incorrecta |\n| 40 | IBAN de la cuenta destino inválido |\n| 41 | IBAN de la cuenta origen inválido |\n| 42 | Tipo de cuenta no permite la transacción |\n| 43 | Cuenta Cliente no pertenece a la entidad indicada |\n| 44 | Producto de la cuenta no admite el servicio |\n| 45 | Cuenta Cliente en estado de cancelación |\n| 46 | Cuenta Cliente restringida por política de la entidad |\n| 47 | Cuenta Cliente no permite pagos inmediatos |\n| 48 | Cuenta Cliente no permite SINPE Móvil |\n| 49 | Titular de la cuenta destino fallecido |\n| 50 | Cuenta Cliente consolidada o migrada |\n| 51 | Identificación del cliente origen no coincide |\n| 52 | Identificación del cliente destino inválida |\n| 53 | Cliente destino no autorizado para recibir el pago |\n| 54 | Cliente origen no autorizado para enviar el pago |\n| 55 | Perfil del cliente origen no permite la transacción |\n| 56 | Monto inferior al mínimo permitido |\n| 57 | Monto superior al máximo permitido |\n| 58 | Cantidad de transacciones diarias excedida |\n| 59 | Cantidad de transacciones mensuales excedida |\n| 60 | Límite acumulado diario excedido |\n| 61 | Límite acumulado mensual excedido |\n| 62 | Comisión no pudo ser aplicada |\n| 63 | Tipo de cambio no disponible |\n| 64 | Transacción rechazada por control de lavado de dinero |\n| 65 | Transacción rechazada por listas de control |\n| 66 | Transacción en revisión de cumplimiento |\n| 67 | Documento de respaldo requerido no presente |\n| 68 | Firma o autenticación inválida |\n| 69 | Token o segundo factor inválido |\n| 70 | Sesión de usuario expirada |\n| 71 | Usuario no autorizado para el canal |\n| 72 | Dispositivo no registrado |\n| 73 | Geolocalización no permitida |\n| 74 | Operación no soportada en la moneda indicada |\n| 75 | Operación no soportada para el tipo de cliente |\n| 76 | Problemas de comunicación |\n| 77 | Tiempo de espera agotado en la entidad origen |\n| 78 | Tiempo de espera agotado en el SINPE |\n| 79 | Error interno de la entidad origen |\n| 80 | Error interno de la entidad destino |\n| 81 | Entidad origen no disponible |\n| 82 | Entidad destino no encontrada |\n| 83 | Problemas en la respuesta del destino |\n| 84 | Respuesta de la entidad origen incorrecta |\n| 85 | Mensaje con formato electrónico inválido |\n| 86 | Versión del estándar electrónico no soportada |\n| 87 | Campo obligatorio no informado |\n| 88 | Campo con valor fuera de catálogo |\n| 89 | Checksum o integridad del mensaje inválida |\n| 90 | Referencia SINPE duplicada |\n| 91 | Moneda no corresponde |\n| 92 | Transacción no autorizada por entidad destino |\n| 93 | Transacción no autorizada por cliente destino |\n| 94 | Transacción no autorizada por entidad origen |\n| 95 | Transacción no autorizada por cliente origen |\n| 96 | Reverso no permitido para el estado de la transacción |\n| 97 | Reverso ya aplicado |\n| 98 | Confirmación no permitida para el estado de la transacción |\n| 99 | Liquidación no permitida para el estado de la transacción |\n| 100 | Entidad Destino no disponible para procesar en tiempo real |\n| 101 | Entidad origen no disponible para procesar en tiempo real |\n| 102 | Servicio PIN no habilitado para la entidad destino |\n| 103 | Servicio PIN no habilitado para la entidad origen |\n| 104 | Código de entidad destino inválido |\n| 105 | Código de entidad origen inválido |\n| 106 | Código de país de la entidad destino inválido |\n| 107 | Código de país de la entidad origen inválido |\n| 108 | Número de referencia interna inválido |\n| 109 | Número de referencia SINPE inválido |\n| 110 | Transacción no se encuentra en un estado que permita la consulta |\n\n**Compensación con entidad destino**\n\n| Code | Message |\n|---|---|\n| 201 | Tiempo respuesta excedido por la entidad destino |\n| 202 | Respuesta de la entidad destino incorrecta según el estándar electrónico |\n| 203 | Se recibió una excepción de la entidad destino |\n| 204 | Error de comunicación con la entidad destino |\n| 205 | Falló procesamiento en el SINPE |\n| 206 | Transacción no autorizada por cliente destino |\n| 207 | Perfil transaccional del cliente destino no permite recibir el pago |\n| 208 | Falló la acreditación en la cuenta destino |\n| 209 | Falló el débito en la cuenta origen |\n| 210 | Conciliación de la transacción no fue posible |\n\n**Identificación**\n\n| Code | Message |\n|---|---|\n| 801 | Identificación inválida |\n| 802 | Identificación del cliente origen no encontrada |\n| 803 | Identificación del cliente destino no encontrada |\n| 804 | Identificación no vigente |\n| 805 | Identificación vencida |\n| 806 | Identificación no corresponde al tipo indicado |\n| 807 | Tipo de identificación inválido |\n| 808 | País de la identificación no soportado |\n| 809 | Identificación de menor de edad no permitida |\n| 810 | Identificación de persona jurídica no permitida para el servicio |\n\n**Validación de formato / Core Bancario**\n\n| Code | Message |\n|---|---|\n| 1001 | Cuenta cliente activa |\n| 1002 | El Id de cliente destino no cumple con el formato esperado por el SINPE |\n| 1003 | El Id de cliente origen no fue informado |\n| 1004 | El Id de cliente origen no cumple con el formato esperado por el SINPE |\n| 1005 | Monto con formato inválido |\n| 1006 | Moneda con formato inválido |\n| 1007 | Problemas de comunicación con el Core Bancario |\n| 1008 | Core Bancario no disponible |\n| 1009 | El valor para el campo no puede ser nulo o infringir su longitud mínima o máxima |\n| 1010 | El valor para el campo no corresponde al tipo de dato esperado |\n| 1011 | El valor para el campo no corresponde al catálogo permitido |\n| 1012 | Fecha con formato inválido |\n| 1013 | Hora con formato inválido |\n| 1014 | Número de referencia con formato inválido |\n| 1015 | IBAN con formato inválido |\n\n**Canal / tipo de identificación**\n\n| Code | Message |\n|---|---|\n| 1040 | Canal no informado |\n| 1041 | Canal inválido |\n| 1042 | Canal no corresponde |\n| 1043 | Canal no habilitado para la entidad |\n| 1044 | Canal no habilitado para el servicio |\n| 1045 | El formato de la identificación es inválido |\n| 1046 | Tipo de identificación no informado |\n| 1080 | Tipo de identificación no corresponde al cliente origen |\n| 1081 | Tipo de identificación no corresponde al cliente destino |\n| 1082 | Tipo de identificación no vigente |\n| 1083 | Tipo de identificación no soportado por el servicio |\n| 1084 | Tipo de identificación inválido |\n| 1085 | Tipo de identificación no soportado por la entidad |\n\n**SINPE Móvil (monedero)**\n\n| Code | Message |\n|---|---|\n| 15300 | El número de teléfono origen indicado es inválido |\n| 15301 | El número de teléfono origen no tiene activo el Servicio Monedero |\n| 15302 | El número de teléfono destino indicado es inválido |\n| 15303 | El número de teléfono destino no está registrado en el padrón móvil del BCCR |\n| 15304 | No es posible inactivar el monedero indicado pues no existe |\n| 15305 | El número de teléfono indicado ya se encuentra activo como monedero en el padrón local |\n\n⚠️ This catalog is under review — some entries (notably `208` and `209`)\nare known to be pending verification against the official SINPE source and\nmay be corrected in a future revision without notice.\n", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountValidateRequest" }, "examples": { "pin": { "summary": "PIN (external IBAN)", "value": { "payment_method_code": "PIN", "account": { "type": "IBAN", "value": "CR16010400000000000031" } } }, "sinpe_movil": { "summary": "SINPE_MOVIL (phone wallet)", "value": { "payment_method_code": "SINPE_MOVIL", "account": { "type": "PHONE", "value": "88887777" } } } } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "product_name": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value", "currency", "product_name" ], "type": "object" }, "financial_institution": { "properties": { "country_code": { "type": "string" }, "entity_code": { "type": "string" }, "entity_name": { "type": "string" } }, "required": [ "country_code", "entity_code", "entity_name" ], "type": "object" }, "holder": { "properties": { "id_number": { "type": "string" }, "id_type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "id_type", "id_number" ], "type": "object" }, "is_valid": { "type": "boolean" }, "provider": { "properties": { "correlation_id": { "type": "string" }, "occurred_at": { "type": "string" }, "operation": { "type": "string" } }, "required": [ "operation" ], "type": "object" }, "rejection": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "reason_code": { "type": "string" } }, "required": [ "code", "reason_code", "message" ], "type": "object" } }, "required": [ "is_valid", "account", "holder", "financial_institution", "rejection", "provider" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INVALID_REQUEST", "INVALID_ACCOUNT_TYPE", "INVALID_ACCOUNT_FORMAT", "INVALID_PAYMENT_METHOD" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" }, "Error_INVALID_ACCOUNT_TYPE": { "$ref": "#/components/examples/Error_INVALID_ACCOUNT_TYPE" }, "Error_INVALID_ACCOUNT_FORMAT": { "$ref": "#/components/examples/Error_INVALID_ACCOUNT_FORMAT" }, "Error_INVALID_PAYMENT_METHOD": { "$ref": "#/components/examples/Error_INVALID_PAYMENT_METHOD" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, { "number": 5, "code": "INVALID_ACCOUNT_TYPE", "message": "Unsupported or invalid account type." }, { "number": 6, "code": "INVALID_ACCOUNT_FORMAT", "message": "Invalid account format." }, { "number": 7, "code": "INVALID_PAYMENT_METHOD", "message": "Invalid or unsupported payment method." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 8, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "422": { "content": { "application/json": { "examples": { "Error_UNPROCESSABLE_ENTITY": { "$ref": "#/components/examples/Error_UNPROCESSABLE_ENTITY" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "UNPROCESSABLE_ENTITY" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNPROCESSABLE_ENTITY", "message": "The request is well-formed but cannot be processed due to business rules." }, "http_status_code": 422, "message": "The request is well-formed but cannot be processed due to business rules.", "response_code": "UNPROCESSABLE_ENTITY", "success": false } } }, "x-error-codes": [ { "number": 9, "code": "UNPROCESSABLE_ENTITY", "message": "The request is well-formed but cannot be processed due to business rules." } ], "description": "The request is well-formed but cannot be processed due to business rules." }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 11, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Unable to complete the request with the payment provider. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "response_code": { "enum": [ "PROVIDER_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message" ], "type": "object" }, "examples": { "Error_PROVIDER_ERROR": { "$ref": "#/components/examples/Error_PROVIDER_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "response_code": "PROVIDER_ERROR", "success": false } } }, "x-error-codes": [ { "number": 10, "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." } ] } } } }, "/api/public/v1/accounts/balances": { "get": { "summary": "List balances for accessible accounts", "description": "Returns paginated account balances (`account`, `amounts`, `as_of`). This endpoint checks\nthe current balance in real time and may respond more slowly than `GET /accounts`.\nFor account attributes without amounts, use `GET /accounts`.\n\nOptional filters use the public account identification standard: `type` + `value`\n(identifier scheme + value). `type` is not the internal account classification.\n", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "$ref": "#/components/parameters/AccountIdentifierTypeOptional" }, { "$ref": "#/components/parameters/AccountIdentifierValueOptional" } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "items": { "items": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "amounts": { "properties": { "available": { "type": "string" }, "inbound_in_transit": { "type": "string" }, "outbound_in_transit": { "type": "string" }, "posted": { "type": "string" } }, "required": [ "available", "posted", "inbound_in_transit", "outbound_in_transit" ], "type": "object" }, "as_of": { "type": "string" } }, "required": [ "account", "amounts", "as_of" ], "type": "object" }, "type": "array" }, "pagination": { "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "limit", "offset", "total" ], "type": "object" } }, "required": [ "items", "pagination" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 6, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_NOT_FOUND": { "$ref": "#/components/examples/Error_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "http_status_code": 404, "message": "The requested resource was not found.", "payload": null, "response_code": "NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "NOT_FOUND", "message": "The requested resource was not found." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 8, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Dependency error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorResponse" } } } }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/accounts": { "get": { "summary": "List accessible accounts without balances", "description": "Returns paginated accessible accounts without querying current balances.\nEach item is account attributes only (`account.type`, `account.value`, `account.currency`).\n`amounts` and `as_of` are not included; use `GET /accounts/balances` or `POST /accounts/balance`.\n\nOptional filters use the public account identification standard: `type` + `value`\n(identifier scheme + value). `type` is not the internal account classification.\n", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "$ref": "#/components/parameters/AccountIdentifierTypeOptional" }, { "$ref": "#/components/parameters/AccountIdentifierValueOptional" } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "items": { "items": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" } }, "required": [ "account" ], "type": "object" }, "type": "array" }, "pagination": { "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "limit", "offset", "total" ], "type": "object" } }, "required": [ "items", "pagination" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ] }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_NOT_FOUND": { "$ref": "#/components/examples/Error_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "http_status_code": 404, "message": "The requested resource was not found.", "payload": null, "response_code": "NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "NOT_FOUND", "message": "The requested resource was not found." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Dependency error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorResponse" } } } }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/accounts/balance": { "post": { "summary": "Get account balance", "description": "Returns a single account snapshot with `amounts` and `as_of`.\nFor account attributes without balances, use `GET /accounts`.\n", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAccountBalanceRequest" } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "account": { "properties": { "currency": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "amounts": { "properties": { "available": { "type": "string" }, "inbound_in_transit": { "type": "string" }, "outbound_in_transit": { "type": "string" }, "posted": { "type": "string" } }, "required": [ "available", "posted", "inbound_in_transit", "outbound_in_transit" ], "type": "object" }, "as_of": { "type": "string" } }, "required": [ "account", "amounts", "as_of" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 5, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "404": { "description": "Account not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "ACCOUNT_NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_ACCOUNT_NOT_FOUND": { "$ref": "#/components/examples/Error_ACCOUNT_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_NOT_FOUND", "message": "Account not found." }, "http_status_code": 404, "message": "Account not found.", "payload": null, "response_code": "ACCOUNT_NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "ACCOUNT_NOT_FOUND", "message": "Account not found." } ] }, "422": { "content": { "application/json": { "examples": { "Error_ACCOUNT_NOT_CONFIGURED": { "$ref": "#/components/examples/Error_ACCOUNT_NOT_CONFIGURED" }, "Error_UNPROCESSABLE_ENTITY": { "$ref": "#/components/examples/Error_UNPROCESSABLE_ENTITY" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "ACCOUNT_NOT_CONFIGURED", "UNPROCESSABLE_ENTITY" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_NOT_CONFIGURED", "message": "This account is not mapped in the system. Please contact support to configure it correctly." }, "http_status_code": 422, "message": "This account is not mapped in the system. Please contact support to configure it correctly.", "payload": null, "response_code": "ACCOUNT_NOT_CONFIGURED", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "ACCOUNT_NOT_CONFIGURED", "message": "This account is not mapped in the system. Please contact support to configure it correctly." }, { "number": 8, "code": "UNPROCESSABLE_ENTITY", "message": "The request is well-formed but cannot be processed due to business rules." } ], "description": "This account is not mapped in the system. Please contact support to configure it correctly." }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 11, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Unable to complete the request with the payment provider. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "PROVIDER_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_PROVIDER_ERROR": { "$ref": "#/components/examples/Error_PROVIDER_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "payload": null, "response_code": "PROVIDER_ERROR", "success": false } } }, "x-error-codes": [ { "number": 9, "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 10, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/accounts/statements": { "post": { "summary": "Request account statement generation", "description": "Creates an asynchronous account statement request for a date range (max 60 days).\nIdentify the account with `account.type` + `account.value` (identifier scheme + value,\ne.g. IBAN). This follows the public account identification standard.\n`account.type` is not the internal account classification.\nReturns `{request_id, status: PENDING}` immediately.\nPoll `GET /accounts/statements/{request_id}` for status; when `DONE`, the response includes a signed `download_url`.\n", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountStatementRequest" } } } }, "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "request_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "request_id", "status" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "202": { "description": "Statement request accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountStatementResponse" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN", "ACCOUNT_ACCESS_DENIED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" }, "Error_ACCOUNT_ACCESS_DENIED": { "$ref": "#/components/examples/Error_ACCOUNT_ACCESS_DENIED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, { "number": 5, "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." } ] }, "404": { "content": { "application/json": { "examples": { "Error_NOT_FOUND": { "$ref": "#/components/examples/Error_NOT_FOUND" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "http_status_code": 404, "message": "The requested resource was not found.", "payload": null, "response_code": "NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 7, "code": "NOT_FOUND", "message": "The requested resource was not found." } ], "description": "The requested resource was not found." }, "409": { "content": { "application/json": { "examples": { "Error_IDEMPOTENCY_CONFLICT": { "$ref": "#/components/examples/Error_IDEMPOTENCY_CONFLICT" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "IDEMPOTENCY_CONFLICT" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress." }, "http_status_code": 409, "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress.", "payload": null, "response_code": "IDEMPOTENCY_CONFLICT", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress." } ], "description": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress." }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 9, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Dependency error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorResponse" } } } }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 8, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/accounts/statements/{request_id}": { "get": { "summary": "Get account statement request status", "description": "Returns request status. When `DONE`, includes a GCS signed `download_url` (48h from generation) and `expires_at`.\nWhen `ERROR`, includes a generic `message` without internal details.\nUnknown or unauthorized `request_id` returns 404.\n", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "download_url": { "type": "string" }, "expires_at": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "request_id", "status" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ] }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_NOT_FOUND": { "$ref": "#/components/examples/Error_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "http_status_code": 404, "message": "The requested resource was not found.", "payload": null, "response_code": "NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "NOT_FOUND", "message": "The requested resource was not found." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/webhook/destination": { "post": { "summary": "Create webhook destination", "description": "Valid fields depend on `destination_kind` and `scope_kind`. Send only the fields that apply to your combination; other scope fields must be omitted (not null placeholders).\n\n**Event payloads**\nInspect outbound contracts with\n`GET /api/public/v1/webhook/event-contracts/{event_type}`\n(`payin.posted`, `payment.succeeded`, `payment.failed`, `payment.reversed`).\n\n**destination_kind**\n- `EXTERNAL_WEBHOOK` (only kind available on the public API): requires `webhook_url` (must start with `https://`) and `secret_ref`. Optional delivery tuning (`timeout_ms`, `max_attempts`). Payloads are always encrypted with `AES_GCM` using `secret_ref`; the HTTP body is `{\"data\":\"\"}`.\n- `INTERNAL` is reserved for platform administration and cannot be created through this endpoint.\n\n**scope_kind**\n- `TENANT`: omit `scope_account_id`, `scope_owner_type`, and `scope_owner_id`.\n- `ACCOUNT`: require `scope_account_id`; omit owner fields.\n- `OWNER`: require `scope_owner_type` and `scope_owner_id`; omit `scope_account_id`. `scope_owner_type` is one of `tenant`, `partner`, `user`, `platform`, `customer` (lowercase in payload).\n\n## Webhook encryption (EXTERNAL_WEBHOOK)\n\nDeliveries always send `Content-Type: application/json` and `Accept: application/json`.\n\nThe HTTP body is always `{\"data\": \"\"}`. The base64-decoded bytes are:\n\n```\nnonce (12 bytes, random) || AES-256-GCM ciphertext || 16-byte auth tag\n```\n\n```\nkey = SHA256(secret_ref) # 32 bytes → AES-256\nwire = base64_decode(data)\nnonce, sealed = wire[:12], wire[12:] # sealed = ciphertext || tag\nplaintext = AES-GCM-Open(key, nonce, sealed, additional_data = none)\n```\n\nNo additional authenticated data (AAD) is used. `plaintext` is the same JSON\nenvelope documented per event type in\n`GET /webhook/event-contracts/{event_type}` — decrypt first, then apply that\ncontract. Authenticity is provided by the GCM auth tag (decryption fails if the\nbody was tampered with).\n\nDeduplicate retries using `event.event_id` in the payload envelope — delivery\nretries can redeliver the same event with the same `event_id`.\n", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWebhookDestinationRequest" }, "examples": { "external_webhook_tenant": { "summary": "HTTPS callback for all events in scope tenant", "value": { "feature_id": "11111111-1111-1111-1111-111111111111", "destination_kind": "EXTERNAL_WEBHOOK", "scope_kind": "TENANT" } } } } } }, "responses": { "201": { "description": "The resource was created successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "created_at": { "type": "string" }, "destination_kind": { "type": "string" }, "destination_ref": { "type": "string" }, "feature_id": { "type": "string" }, "id": { "type": "string" }, "is_enabled": { "type": "boolean" }, "max_attempts": { "type": "integer" }, "replay_window_sec": { "type": "integer" }, "scope_account_id": { "type": "string" }, "scope_kind": { "type": "string" }, "scope_owner_id": { "type": "string" }, "scope_owner_type": { "type": "string" }, "secret_ref": { "type": "string" }, "signature_algo": { "type": "string" }, "timeout_ms": { "type": "integer" }, "updated_at": { "type": "string" }, "webhook_url": { "type": "string" } }, "required": [ "id", "feature_id", "is_enabled", "destination_kind", "signature_algo", "replay_window_sec", "scope_kind" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "CREATED" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "400": { "description": "Invalid request. Check the required fields and try again.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INVALID_REQUEST" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INVALID_REQUEST": { "$ref": "#/components/examples/Error_INVALID_REQUEST" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." } ] }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/webhook/features": { "get": { "summary": "List webhook features by payment method", "description": "Returns feature IDs and the `event_types` each feature can emit.\nTenant scope is taken from the access token; clients must not send `tenant_id`.\n\n**Naming:** `event_types` use `payment.*` for resource-level outcomes\n(`payment.succeeded`, `payment.failed`, `payment.reversed`) and `payin.posted` for the inbound\ndirection only (funds received). There is no `payout.posted` and no\n`transaction.*` events. The delivered JSON object is always `payment`.\n\nInspect payload shapes with `GET /api/public/v1/webhook/event-contracts/{event_type}`\n(`payin.posted`, `payment.succeeded`, `payment.failed`, `payment.reversed`).\n", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "webhook_enabled", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "items": { "items": { "properties": { "event_types": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" } }, "required": [ "id", "event_types" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/webhook/event-contracts/{event_type}": { "get": { "summary": "Webhook event contract", "description": "Returns the outbound webhook payload contract for one public event type\n(`schema_version` 1.0.0). The envelope object is always `payment` (never\n`payin`, `payout`, or `transaction`).\n\n**When to use each name**\n- **payment** — resource and envelope. Outcome events: `payment.succeeded`,\n `payment.failed`, `payment.reversed` (both PAYIN and PAYOUT). Correlate with REST\n `/transactions/payments`.\n- **payin / payout** — direction (`PAYIN` inbound, `PAYOUT` outbound).\n `payin.posted` is inbound-only (ledger posted / funds received).\n There is no public `payout.posted`.\n- **transaction** — REST path prefix only. Not used in webhook `event_type`\n or payload objects.\n\nSupported `event_type` values:\n- `payin.posted` — inbound (PAYIN) payment reached public status `posted`.\n Envelope field is `payment`. `payment.local_payment` is a JSON boolean\n (`true`/`false`), not a string.\n- `payment.succeeded` — the provider confirmed success for a payment (PAYIN or\n PAYOUT; PIN or SINPE Móvil). Resource-level outcome, not direction-specific.\n- `payment.failed` — processing ended in a definitive failure (public `status=failed`),\n with structured `payment.error` (`domain` / `platform`). When the provider rejected\n the payment, the envelope also includes `rejection`. Not used for later reversals.\n- `payment.reversed` — subsequent reversal of a payment that already progressed\n (typically `status=posted` or `confirmed`). REST `result=reversed` and\n `has_reversal=true`. Processing `status` is unchanged. Not a `payment.failed`.\n\nUnknown `event_type` values (including internal-only `payment.status_changed`)\nreturn `404`.\n\n## SINPE rejection codes (`rejection`, only on `payment.failed`)\n\nWhen `event_type = payment.failed` and the provider rejected the payment, the\nenvelope includes `rejection` (same object and catalog as `data.rejection` on\n`POST /accounts/validate`). `rejection.code` is one of a fixed set of normalized\nsemantics (see the `WebhookRejection.code` schema enum). **Most rows in the table\nbelow do NOT get a distinct `code`** — only a subset of `reason_code` values has a\ndedicated semantic; every other `reason_code`, even one listed below with a specific\n`message`, returns `code = SINPE_REJECTED` (e.g. `reason_code = 21` \"fondos\ninsuficientes\" still returns `SINPE_REJECTED`). A `reason_code` not listed here at\nall still produces a response — `message` falls back to a generic text and `code`\nfalls back to `SINPE_REJECTED`.\n\n**Cuenta / perfil / límites**\n\n| Code | Message |\n|---|---|\n| 21 | Cuenta Cliente con fondos insuficientes |\n| 22 | Cuenta Cliente no admite créditos |\n| 23 | Cuenta Cliente cerrada |\n| 24 | Cuenta Cliente inactiva |\n| 25 | Cuenta Cliente no admite débitos |\n| 26 | Cuenta Cliente no es de fondos |\n| 27 | Moneda de la Cuenta Cliente no corresponde |\n| 28 | Cuenta cliente no existe |\n| 29 | Cuenta Cliente no registrada en el SINPE |\n| 30 | Cuenta Cliente no habilitada para el servicio |\n| 31 | Cuenta Cliente bloqueada |\n| 32 | Id cliente destino no coincide con registrado en la entidad |\n| 33 | Nombre del cliente destino no coincide con el registrado en la entidad |\n| 34 | Cuenta Cliente en proceso de cierre |\n| 35 | Cuenta Cliente embargada |\n| 36 | Cuenta Cliente con retención judicial |\n| 37 | Cuenta de expediente simplificado no permite el monto indicado |\n| 38 | Límite transaccional de la Cuenta Cliente excedido |\n| 39 | Cuenta Cliente incorrecta |\n| 40 | IBAN de la cuenta destino inválido |\n| 41 | IBAN de la cuenta origen inválido |\n| 42 | Tipo de cuenta no permite la transacción |\n| 43 | Cuenta Cliente no pertenece a la entidad indicada |\n| 44 | Producto de la cuenta no admite el servicio |\n| 45 | Cuenta Cliente en estado de cancelación |\n| 46 | Cuenta Cliente restringida por política de la entidad |\n| 47 | Cuenta Cliente no permite pagos inmediatos |\n| 48 | Cuenta Cliente no permite SINPE Móvil |\n| 49 | Titular de la cuenta destino fallecido |\n| 50 | Cuenta Cliente consolidada o migrada |\n| 51 | Identificación del cliente origen no coincide |\n| 52 | Identificación del cliente destino inválida |\n| 53 | Cliente destino no autorizado para recibir el pago |\n| 54 | Cliente origen no autorizado para enviar el pago |\n| 55 | Perfil del cliente origen no permite la transacción |\n| 56 | Monto inferior al mínimo permitido |\n| 57 | Monto superior al máximo permitido |\n| 58 | Cantidad de transacciones diarias excedida |\n| 59 | Cantidad de transacciones mensuales excedida |\n| 60 | Límite acumulado diario excedido |\n| 61 | Límite acumulado mensual excedido |\n| 62 | Comisión no pudo ser aplicada |\n| 63 | Tipo de cambio no disponible |\n| 64 | Transacción rechazada por control de lavado de dinero |\n| 65 | Transacción rechazada por listas de control |\n| 66 | Transacción en revisión de cumplimiento |\n| 67 | Documento de respaldo requerido no presente |\n| 68 | Firma o autenticación inválida |\n| 69 | Token o segundo factor inválido |\n| 70 | Sesión de usuario expirada |\n| 71 | Usuario no autorizado para el canal |\n| 72 | Dispositivo no registrado |\n| 73 | Geolocalización no permitida |\n| 74 | Operación no soportada en la moneda indicada |\n| 75 | Operación no soportada para el tipo de cliente |\n| 76 | Problemas de comunicación |\n| 77 | Tiempo de espera agotado en la entidad origen |\n| 78 | Tiempo de espera agotado en el SINPE |\n| 79 | Error interno de la entidad origen |\n| 80 | Error interno de la entidad destino |\n| 81 | Entidad origen no disponible |\n| 82 | Entidad destino no encontrada |\n| 83 | Problemas en la respuesta del destino |\n| 84 | Respuesta de la entidad origen incorrecta |\n| 85 | Mensaje con formato electrónico inválido |\n| 86 | Versión del estándar electrónico no soportada |\n| 87 | Campo obligatorio no informado |\n| 88 | Campo con valor fuera de catálogo |\n| 89 | Checksum o integridad del mensaje inválida |\n| 90 | Referencia SINPE duplicada |\n| 91 | Moneda no corresponde |\n| 92 | Transacción no autorizada por entidad destino |\n| 93 | Transacción no autorizada por cliente destino |\n| 94 | Transacción no autorizada por entidad origen |\n| 95 | Transacción no autorizada por cliente origen |\n| 96 | Reverso no permitido para el estado de la transacción |\n| 97 | Reverso ya aplicado |\n| 98 | Confirmación no permitida para el estado de la transacción |\n| 99 | Liquidación no permitida para el estado de la transacción |\n| 100 | Entidad Destino no disponible para procesar en tiempo real |\n| 101 | Entidad origen no disponible para procesar en tiempo real |\n| 102 | Servicio PIN no habilitado para la entidad destino |\n| 103 | Servicio PIN no habilitado para la entidad origen |\n| 104 | Código de entidad destino inválido |\n| 105 | Código de entidad origen inválido |\n| 106 | Código de país de la entidad destino inválido |\n| 107 | Código de país de la entidad origen inválido |\n| 108 | Número de referencia interna inválido |\n| 109 | Número de referencia SINPE inválido |\n| 110 | Transacción no se encuentra en un estado que permita la consulta |\n\n**Compensación con entidad destino**\n\n| Code | Message |\n|---|---|\n| 201 | Tiempo respuesta excedido por la entidad destino |\n| 202 | Respuesta de la entidad destino incorrecta según el estándar electrónico |\n| 203 | Se recibió una excepción de la entidad destino |\n| 204 | Error de comunicación con la entidad destino |\n| 205 | Falló procesamiento en el SINPE |\n| 206 | Transacción no autorizada por cliente destino |\n| 207 | Perfil transaccional del cliente destino no permite recibir el pago |\n| 208 | Falló la acreditación en la cuenta destino |\n| 209 | Falló el débito en la cuenta origen |\n| 210 | Conciliación de la transacción no fue posible |\n\n**Identificación**\n\n| Code | Message |\n|---|---|\n| 801 | Identificación inválida |\n| 802 | Identificación del cliente origen no encontrada |\n| 803 | Identificación del cliente destino no encontrada |\n| 804 | Identificación no vigente |\n| 805 | Identificación vencida |\n| 806 | Identificación no corresponde al tipo indicado |\n| 807 | Tipo de identificación inválido |\n| 808 | País de la identificación no soportado |\n| 809 | Identificación de menor de edad no permitida |\n| 810 | Identificación de persona jurídica no permitida para el servicio |\n\n**Validación de formato / Core Bancario**\n\n| Code | Message |\n|---|---|\n| 1001 | Cuenta cliente activa |\n| 1002 | El Id de cliente destino no cumple con el formato esperado por el SINPE |\n| 1003 | El Id de cliente origen no fue informado |\n| 1004 | El Id de cliente origen no cumple con el formato esperado por el SINPE |\n| 1005 | Monto con formato inválido |\n| 1006 | Moneda con formato inválido |\n| 1007 | Problemas de comunicación con el Core Bancario |\n| 1008 | Core Bancario no disponible |\n| 1009 | El valor para el campo no puede ser nulo o infringir su longitud mínima o máxima |\n| 1010 | El valor para el campo no corresponde al tipo de dato esperado |\n| 1011 | El valor para el campo no corresponde al catálogo permitido |\n| 1012 | Fecha con formato inválido |\n| 1013 | Hora con formato inválido |\n| 1014 | Número de referencia con formato inválido |\n| 1015 | IBAN con formato inválido |\n\n**Canal / tipo de identificación**\n\n| Code | Message |\n|---|---|\n| 1040 | Canal no informado |\n| 1041 | Canal inválido |\n| 1042 | Canal no corresponde |\n| 1043 | Canal no habilitado para la entidad |\n| 1044 | Canal no habilitado para el servicio |\n| 1045 | El formato de la identificación es inválido |\n| 1046 | Tipo de identificación no informado |\n| 1080 | Tipo de identificación no corresponde al cliente origen |\n| 1081 | Tipo de identificación no corresponde al cliente destino |\n| 1082 | Tipo de identificación no vigente |\n| 1083 | Tipo de identificación no soportado por el servicio |\n| 1084 | Tipo de identificación inválido |\n| 1085 | Tipo de identificación no soportado por la entidad |\n\n**SINPE Móvil (monedero)**\n\n| Code | Message |\n|---|---|\n| 15300 | El número de teléfono origen indicado es inválido |\n| 15301 | El número de teléfono origen no tiene activo el Servicio Monedero |\n| 15302 | El número de teléfono destino indicado es inválido |\n| 15303 | El número de teléfono destino no está registrado en el padrón móvil del BCCR |\n| 15304 | No es posible inactivar el monedero indicado pues no existe |\n| 15305 | El número de teléfono indicado ya se encuentra activo como monedero en el padrón local |\n\n⚠️ This catalog is under review — some entries (notably `208` and `209`)\nare known to be pending verification against the official SINPE source and\nmay be corrected in a future revision without notice.\n\nDelivery body is JSON. `EXTERNAL_WEBHOOK` HTTP body is always `{\"data\":\"\"}`\n(AES-256-GCM, key = SHA256(secret_ref)). Decrypt to obtain the event envelope documented\nper `GET /webhook/event-contracts/{event_type}`.\nand the decrypted plaintext matches this contract.\n", "operationId": "getPublicWebhookEventContract", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "payin.posted", "payment.succeeded", "payment.failed", "payment.reversed" ] }, "examples": { "payinPosted": { "value": "payin.posted" }, "paymentSucceeded": { "value": "payment.succeeded" }, "paymentFailed": { "value": "payment.failed" }, "paymentReversed": { "value": "payment.reversed" } } } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "description": { "type": "string" }, "event_type": { "type": "string" }, "example": { "additionalProperties": true, "type": "object" }, "schema_version": { "type": "string" } }, "required": [ "event_type", "schema_version", "description", "example" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ] }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "NOT_FOUND" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_NOT_FOUND": { "$ref": "#/components/examples/Error_NOT_FOUND" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "http_status_code": 404, "message": "The requested resource was not found.", "payload": null, "response_code": "NOT_FOUND", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "NOT_FOUND", "message": "The requested resource was not found." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 6, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } }, "/api/public/v1/catalogs/customer-identification-types": { "get": { "summary": "List customer identification person types", "description": "Returns the distinct customer person types (`individual`, `business`, `both`) available\nfor the authenticated tenant, optionally filtered by country. This is a person-type\nclassification, not the payment identification-document catalog (`cedula`, `juridica`,\n`dimex`, ...) used by `identification.type` on `POST /payments`.\n", "tags": [ "Catalogs" ], "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "name": "country_code", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "description": "Optional ISO-2 country code used to filter results. A legacy `country` query\nparameter is also accepted as an alias when `country_code` is omitted; prefer\n`country_code`.\n" } ], "responses": { "200": { "description": "The request was processed successfully.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "data": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "OK" ], "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" } } } }, "401": { "description": "Unauthorized. Verify your session or credentials.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "UNAUTHORIZED" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_UNAUTHORIZED": { "$ref": "#/components/examples/Error_UNAUTHORIZED" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } } }, "x-error-codes": [ { "number": 1, "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." } ] }, "403": { "description": "You do not have permission to perform this action.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "FORBIDDEN" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_FORBIDDEN": { "$ref": "#/components/examples/Error_FORBIDDEN" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } } }, "x-error-codes": [ { "number": 2, "code": "FORBIDDEN", "message": "You do not have permission to perform this action." } ] }, "429": { "content": { "application/json": { "examples": { "Error_TOO_MANY_REQUESTS": { "$ref": "#/components/examples/Error_TOO_MANY_REQUESTS" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "TOO_MANY_REQUESTS" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } } }, "x-error-codes": [ { "number": 3, "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." } ], "description": "Too many requests. Please retry after a short delay." }, "500": { "description": "An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "INTERNAL_ERROR" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "examples": { "Error_INTERNAL_ERROR": { "$ref": "#/components/examples/Error_INTERNAL_ERROR" } }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } }, "x-error-codes": [ { "number": 5, "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." } ] }, "502": { "description": "Dependency error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorResponse" } } } }, "503": { "content": { "application/json": { "examples": { "Error_SERVICE_UNAVAILABLE": { "$ref": "#/components/examples/Error_SERVICE_UNAVAILABLE" } }, "schema": { "properties": { "correlation_id": { "type": "string" }, "errors": { "additionalProperties": true, "description": "Detalle del error; additionalProperties: true indica que el objeto puede incluir campos arbitrarios (p. ej. code, message, detail).", "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "response_code": { "enum": [ "SERVICE_UNAVAILABLE" ], "type": "string" }, "success": { "enum": [ false ], "type": "boolean" } }, "required": [ "success", "http_status_code", "response_code", "message", "payload" ], "type": "object" }, "example": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } } }, "x-error-codes": [ { "number": 4, "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." } ], "description": "A required service is temporarily unavailable. Please try again later." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "parameters": { "CorrelationIdHeader": { "name": "X-Correlation-Id", "in": "header", "required": false, "description": "Optional client-supplied correlation id for end-to-end tracing.\nEchoed back as `correlation_id` in the response envelope. If omitted,\nthe API generates one and still returns it.\n", "schema": { "type": "string" }, "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "AccountIdentifierType": { "name": "type", "in": "query", "required": true, "description": "Account **identifier scheme** (e.g. `IBAN`).\nThis is **not** the internal account classification\n(e.g. operational).\n", "schema": { "type": "string", "enum": [ "IBAN" ] }, "example": "IBAN" }, "AccountIdentifierValue": { "name": "value", "in": "query", "required": true, "description": "Account identifier value (IBAN). Spaces are ignored.", "schema": { "type": "string" }, "example": "CR12036900101019858991" }, "AccountIdentifierTypeOptional": { "name": "type", "in": "query", "required": false, "description": "Optional filter by account **identifier scheme** (e.g. `IBAN`).\nNot the internal account classification.\n", "schema": { "type": "string" }, "example": "IBAN" }, "AccountIdentifierValueOptional": { "name": "value", "in": "query", "required": false, "description": "Optional filter by account identifier value (partial match supported for list endpoints).", "schema": { "type": "string" }, "example": "CR12036900101019858991" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "public-api ok" }, "service": { "type": "string", "example": "public-api" } } }, "ResponseCode": { "type": "string", "description": "Canonical `response_code` emitted by the public-api response envelope.\nIncludes both generic envelope codes (OK, CREATED, ...) and specific\nbusiness error codes (PAYMENT_DUPLICATE, ACCOUNT_ACCESS_DENIED, ...)\nreturned by individual endpoints. See each endpoint's error responses\nfor which of these codes it can actually produce.\n", "enum": [ "OK", "CREATED", "NO_CONTENT", "UNAUTHORIZED", "FORBIDDEN", "TOO_MANY_REQUESTS", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR", "INVALID_REQUEST", "ACCOUNT_ACCESS_DENIED", "PROVIDER_ERROR", "INVALID_CREDENTIALS", "NOT_FOUND", "ACCOUNT_NOT_FOUND", "ACCOUNT_NOT_CONFIGURED", "UNPROCESSABLE_ENTITY", "PAYMENT_NOT_FOUND", "INVALID_ACCOUNT_TYPE", "INVALID_ACCOUNT_FORMAT", "INVALID_PAYMENT_METHOD", "PAYMENT_INVALID_PAYLOAD", "ACCOUNT_INVALID", "ACCOUNT_HOLDER_MISMATCH", "IDEMPOTENCY_CONFLICT", "PAYMENT_DUPLICATE", "CONFLICT", "INSUFFICIENT_FUNDS", "LIMIT_EXCEEDED" ], "example": "OK" }, "GenericSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "http_status_code": { "type": "integer", "example": 200 }, "response_code": { "$ref": "#/components/schemas/ResponseCode" }, "message": { "type": "string", "description": "Standard success message from the API envelope.\n- 200: The request was processed successfully.\n- 201: The resource was created successfully.\n", "example": "The request was processed successfully." }, "correlation_id": { "type": "string" }, "payload": { "description": "Echo of the JSON request body. Omitted for login, token exchange, and account validation.", "nullable": true }, "data": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "GenericErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "http_status_code": { "type": "integer", "example": 401 }, "response_code": { "allOf": [ { "$ref": "#/components/schemas/ResponseCode" } ], "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Unauthorized. Verify your session or credentials." }, "correlation_id": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "payload": { "description": "Echo of the JSON request body. Omitted for login, token exchange, and account validation.", "nullable": true }, "errors": { "type": "object", "nullable": true, "additionalProperties": true } }, "additionalProperties": true }, "Rfc3339DateTime": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$", "example": "2026-01-15T12:00:00Z", "description": "RFC 3339 timestamp in UTC with second precision and a `Z` suffix.\nFractional seconds are never emitted. Example: `2026-01-15T12:00:00Z`.\n" }, "Rfc3339DateTimeInput": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z", "description": "RFC 3339 timestamp accepted on requests. UTC `Z` or a numeric offset is allowed.\nOptional fractional seconds are accepted and truncated to seconds.\n" }, "WebhookFeatureSummary": { "type": "object", "required": [ "id", "event_types" ], "properties": { "id": { "type": "string", "format": "uuid" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "payin.posted", "payment.succeeded", "payment.failed", "payment.reversed" ] }, "description": "Public event types this feature can emit. `payment.*` = resource-level\noutcomes (any direction). `payin.posted` = inbound direction only\n(funds received). There is no `payout.posted` and no `transaction.*`.\nInspect payload shapes with `GET /api/public/v1/webhook/event-contracts/{event_type}`.\n" } } }, "WebhookEventContract": { "type": "object", "required": [ "event_type", "schema_version", "description", "example" ], "properties": { "event_type": { "type": "string", "enum": [ "payin.posted", "payment.succeeded", "payment.failed", "payment.reversed" ] }, "schema_version": { "type": "string", "example": "1.0.0" }, "description": { "type": "string" }, "example": { "type": "object", "additionalProperties": true } } }, "WebhookEventContractPayinPosted": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventContract" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "payin.posted" ] }, "example": { "$ref": "#/components/schemas/WebhookPayloadPayinPosted" } } } ] }, "WebhookEventContractPaymentSucceeded": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventContract" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "payment.succeeded" ] }, "example": { "$ref": "#/components/schemas/WebhookPayloadPaymentSucceeded" } } } ] }, "WebhookEventContractPaymentFailed": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventContract" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "payment.failed" ] }, "example": { "$ref": "#/components/schemas/WebhookPayloadPaymentFailed" } } } ] }, "WebhookEventContractPaymentReversed": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventContract" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "payment.reversed" ] }, "example": { "$ref": "#/components/schemas/WebhookPayloadPaymentReversed" } } } ] }, "WebhookPayloadPayinPosted": { "type": "object", "description": "Envelope delivered for `payin.posted` (decrypt AES_GCM `data` field first).", "required": [ "schema_version", "event", "context", "payment", "provider" ], "properties": { "schema_version": { "type": "string", "example": "1.0.0" }, "event": { "type": "object", "required": [ "event_id", "event_type", "occurred_at", "correlation_id" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "payin.posted" ] }, "occurred_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "correlation_id": { "type": "string" } } }, "context": { "$ref": "#/components/schemas/WebhookContext" }, "payment": { "$ref": "#/components/schemas/WebhookPaymentPayinPosted" }, "provider": { "$ref": "#/components/schemas/WebhookProvider" } } }, "WebhookPayloadPaymentSucceeded": { "type": "object", "description": "Envelope delivered for `payment.succeeded` (decrypt AES_GCM `data` field first).", "required": [ "schema_version", "event", "context", "payment", "provider" ], "properties": { "schema_version": { "type": "string", "example": "1.0.0" }, "event": { "type": "object", "required": [ "event_id", "event_type", "occurred_at", "correlation_id" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "payment.succeeded" ] }, "occurred_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "correlation_id": { "type": "string" } } }, "context": { "$ref": "#/components/schemas/WebhookContext" }, "payment": { "$ref": "#/components/schemas/WebhookPaymentSucceeded" }, "provider": { "$ref": "#/components/schemas/WebhookProvider" } } }, "WebhookContext": { "type": "object", "required": [ "country_code", "payment_method_code" ], "properties": { "country_code": { "type": "string", "example": "CR" }, "payment_method_code": { "type": "string", "description": "Public payment method catalog. Same values as REST (`PIN`, `SINPE_MOVIL`). Internal codes such as `PM_PIN` are never exposed.", "enum": [ "PIN", "SINPE_MOVIL" ], "example": "PIN" } } }, "WebhookProvider": { "$ref": "#/components/schemas/PublicPaymentProvider" }, "WebhookRejection": { "type": "object", "description": "Rail-agnostic provider rejection. Shared by `POST /accounts/validate`\n(`data.rejection`) and the `payment.failed` webhook (`rejection`).\nObject only when the provider rejected the operation; omitted/`null` otherwise.\n", "required": [ "code", "reason_code", "message" ], "properties": { "code": { "type": "string", "description": "Normalized platform semantic derived from `reason_code`. Only a subset of\n`reason_code` values (see the catalog in the description of `POST /accounts/validate`\nand of the `payment.failed` webhook contract endpoint) has a distinct entry here —\nfor any other numeric `reason_code`, `code` is `SINPE_REJECTED` even when `message`\nis specific (e.g. `reason_code = 21` \"fondos insuficientes\" still returns\n`code = SINPE_REJECTED`, it has no dedicated semantic). `PHONE_NOT_REGISTERED` is\nthe fallback when `reason_code` is non-numeric (SINPE_MOVIL wallet flow).\n", "enum": [ "ACCOUNT_CLOSED", "ACCOUNT_NOT_FOUND", "ACCOUNT_BLOCKED", "INVALID_ACCOUNT", "IDENT_MISMATCH", "IDENT_TYPE_INVALID", "INVALID_ID_FORMAT", "VALIDATION_ERROR", "CURRENCY_MISMATCH", "NOT_AUTHORIZED_BY_RECIPIENT", "PROFILE_NOT_ALLOWED", "CHANNEL_NOT_RECOGNIZED", "COMMUNICATION_ERROR", "RETRY_LATER", "WALLET_PHONE_ORIGIN_INVALID", "WALLET_PHONE_ORIGIN_NOT_ENABLED", "WALLET_PHONE_DEST_INVALID", "WALLET_PHONE_NOT_REGISTERED_BCCR", "WALLET_NOT_FOUND", "WALLET_PHONE_ALREADY_ACTIVE", "PHONE_NOT_REGISTERED", "SINPE_REJECTED" ], "example": "ACCOUNT_BLOCKED" }, "reason_code": { "type": "string", "description": "Raw Motivo/code returned by SINPE. See the endpoint description of\n`POST /accounts/validate` for the full code catalog (shared by this object\nwherever it appears, including the `payment.failed` webhook). A code not\nlisted there still produces a response — `message` falls back to a generic\ntext and `code` falls back to `SINPE_REJECTED`.\n", "example": "31" }, "message": { "type": "string", "description": "Descriptive Motivo text; prefers provider `Detalle` when present.", "example": "Cuenta bloqueada" } } }, "WebhookPaymentPayinPosted": { "type": "object", "required": [ "payment_id", "public_id", "status", "amount", "posted_at", "account", "reference" ], "properties": { "payment_id": { "type": "string", "format": "uuid" }, "public_id": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/PublicPaymentStatus" }, "amount": { "$ref": "#/components/schemas/PaymentAmount" }, "posted_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "account": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "example": "PHONE" }, "value": { "type": "string", "example": "88887777" } } }, "reference": { "type": "object", "required": [ "client_reference", "external_reference" ], "properties": { "client_reference": { "type": "string", "description": "Partner reference sent at payment creation (`client_reference`), not `detail_reference`." }, "external_reference": { "type": "string" } } }, "destination_phone_number": { "type": "string" }, "local_payment": { "type": "boolean", "description": "JSON boolean (`true`/`false`), not the strings `\"true\"`/`\"false\"`.", "example": true }, "origin_client_name": { "type": "string" } } }, "WebhookPaymentSucceededBase": { "type": "object", "required": [ "payment_id", "public_id", "status", "amount", "client_reference", "external_reference", "fee_total", "tax_total", "net_amount" ], "properties": { "payment_id": { "type": "string", "format": "uuid" }, "public_id": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/PublicPaymentStatus" }, "amount": { "$ref": "#/components/schemas/PaymentAmount" }, "client_reference": { "type": "string", "description": "Partner reference sent at payment creation (`client_reference`), not `detail_reference`." }, "external_reference": { "type": "string" }, "fee_total": { "type": "string", "description": "Fee total as decimal string (same currency as amount.currency)" }, "tax_total": { "type": "string", "description": "Tax total as decimal string (same currency as amount.currency)" }, "net_amount": { "type": "string", "description": "Net cash impact on the merchant account.\nPAYIN: amount - fee_total - tax_total (what the merchant receives).\nPAYOUT: amount + fee_total + tax_total (total debit; fee is charged\nseparately and is not deducted from the transferred amount).\n" } } }, "WebhookPaymentSucceeded": { "allOf": [ { "$ref": "#/components/schemas/WebhookPaymentSucceededBase" }, { "type": "object", "required": [ "succeeded_at" ], "properties": { "succeeded_at": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339DateTime" } ], "description": "Timestamp when the provider confirmed the payment succeeded." } } } ] }, "WebhookPayloadPaymentFailed": { "type": "object", "description": "Envelope delivered for `payment.failed` (decrypt AES_GCM `data` field first).", "required": [ "schema_version", "event", "context", "payment", "provider" ], "properties": { "schema_version": { "type": "string", "example": "1.0.0" }, "event": { "type": "object", "required": [ "event_id", "event_type", "occurred_at", "correlation_id" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "payment.failed" ] }, "occurred_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "correlation_id": { "type": "string" } } }, "context": { "$ref": "#/components/schemas/WebhookContext" }, "payment": { "$ref": "#/components/schemas/WebhookPaymentFailed" }, "provider": { "$ref": "#/components/schemas/WebhookProvider" }, "rejection": { "$ref": "#/components/schemas/WebhookRejection" } } }, "WebhookPaymentFailed": { "type": "object", "required": [ "payment_id", "public_id", "status", "amount", "error" ], "properties": { "payment_id": { "type": "string", "format": "uuid" }, "public_id": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/PublicPaymentStatus" }, "amount": { "$ref": "#/components/schemas/PaymentAmount" }, "client_reference": { "type": "string", "description": "Partner reference sent at payment creation (`client_reference`), not `detail_reference`." }, "external_reference": { "type": "string" }, "error": { "$ref": "#/components/schemas/WebhookPaymentFailedError" } } }, "WebhookPaymentFailedError": { "type": "object", "required": [ "domain", "platform" ], "properties": { "domain": { "type": "string", "enum": [ "provider_rejection", "platform_validation", "platform_posting", "platform_infra", "platform_reversal", "sinpe_rejection" ] }, "platform": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "PAYMENT_SINPE_REJECTED", "PAYMENT_FEE_INVALID", "PAYMENT_TAX_INVALID", "PAYMENT_VALIDATION_FAILED", "PAYMENT_ASSET_MISMATCH", "PAYMENT_LEDGER_NOT_FOUND", "PAYMENT_POSTING_FAILED", "PAYMENT_FORMANCE_POSTING_FAILED", "PAYMENT_INFRASTRUCTURE_FAILED", "PAYMENT_REVERSED" ] }, "message": { "type": "string", "description": "Actionable failure message. For provider rejections this is the\nprovider `Detalle` when present (e.g. \"Cuenta bloqueada\").\n" } } } } }, "WebhookPayloadPaymentReversed": { "type": "object", "description": "Envelope delivered for `payment.reversed`. Subsequent reversal of a payment\nthat already progressed. Processing `payment.status` stays `posted` or `confirmed`.\nNot a processing failure (`payment.failed`).\n", "required": [ "schema_version", "event", "context", "payment", "provider" ], "properties": { "schema_version": { "type": "string", "example": "1.0.0" }, "event": { "type": "object", "required": [ "event_id", "event_type", "occurred_at", "correlation_id" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "payment.reversed" ] }, "occurred_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "correlation_id": { "type": "string" } } }, "context": { "$ref": "#/components/schemas/WebhookContext" }, "payment": { "$ref": "#/components/schemas/WebhookPaymentReversed" }, "provider": { "$ref": "#/components/schemas/WebhookProvider" } } }, "WebhookPaymentReversed": { "type": "object", "required": [ "payment_id", "public_id", "status", "result", "has_reversal", "amount", "reversed_at" ], "properties": { "payment_id": { "type": "string", "format": "uuid" }, "public_id": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/PublicPaymentStatus", "description": "Processing catalog. Remains `posted` or `confirmed`; not `failed`." }, "result": { "type": "string", "enum": [ "reversed" ] }, "has_reversal": { "type": "boolean", "enum": [ true ] }, "amount": { "$ref": "#/components/schemas/PaymentAmount" }, "client_reference": { "type": "string" }, "external_reference": { "type": "string" }, "reversed_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "reason": { "type": "object", "properties": { "code": { "type": "string", "example": "PAYMENT_REVERSED" }, "message": { "type": "string" } } } } }, "AddWebhookDestinationResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "feature_id": { "type": "string", "format": "uuid" }, "is_enabled": { "type": "boolean" }, "destination_kind": { "type": "string" }, "destination_ref": { "type": "string" }, "webhook_url": { "type": "string" }, "secret_ref": { "type": "string" }, "signature_algo": { "type": "string" }, "replay_window_sec": { "type": "integer" }, "timeout_ms": { "type": "integer" }, "max_attempts": { "type": "integer" }, "scope_kind": { "type": "string" }, "scope_account_id": { "type": "string", "format": "uuid" }, "scope_owner_type": { "type": "string" }, "scope_owner_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "CustomerIdentificationType": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "individual", "business", "both" ], "example": "individual" } } }, "ListCustomerIdentificationTypesResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerIdentificationType" } } } } } } ] }, "CustomerLoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } }, "CustomerLoginAssignment": { "type": "object", "description": "Assignment context available for selection before token exchange.", "required": [ "assignment_id", "owner_type", "owner_id", "tenant_id", "tenant_code", "country_code", "role", "roles", "status" ], "properties": { "assignment_id": { "type": "string", "format": "uuid", "description": "Identifier used in POST /api/public/v1/auth/token/exchange", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "owner_type": { "type": "string", "example": "customer" }, "owner_id": { "type": "string", "format": "uuid", "description": "Customer identifier for this assignment context", "example": "2a1b3c4d-5e6f-7081-92a3-b4c5d6e7f809" }, "tenant_id": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" }, "tenant_code": { "type": "string", "example": "0001" }, "country_code": { "type": "string", "example": "CR" }, "role": { "type": "string", "description": "Primary role code for this assignment", "example": "owner" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Role codes for this assignment", "example": [ "owner" ] }, "status": { "type": "string", "example": "active" } } }, "CustomerLoginResponseData": { "type": "object", "required": [ "gidp_id_token", "assignments" ], "properties": { "gidp_id_token": { "type": "string", "description": "GIDP ID token required for POST /api/public/v1/auth/token/exchange" }, "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerLoginAssignment" } } } }, "CustomerExchangeRequest": { "type": "object", "required": [ "gidp_id_token", "assignment_id" ], "properties": { "gidp_id_token": { "type": "string" }, "assignment_id": { "type": "string" } } }, "CustomerExchangeClaims": { "type": "object", "description": "Decoded claims embedded in the returned access token.", "properties": { "owner_type": { "type": "string", "example": "customer" }, "owner_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "roles": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "channel": { "type": "string" }, "country_code": { "type": "string" }, "locale": { "type": "string" }, "idp": { "type": "string" }, "idp_sub": { "type": "string" }, "sub": { "type": "string" }, "subject_kind": { "type": "string" }, "user_type": { "type": "string" }, "idempotency_key": { "type": "string" } } }, "CustomerExchangeResponseData": { "type": "object", "required": [ "token", "expires_in", "claims" ], "properties": { "token": { "type": "string", "description": "Access token (JWT). Send as `Authorization: Bearer ` on all other endpoints." }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds.", "example": 3600 }, "claims": { "$ref": "#/components/schemas/CustomerExchangeClaims" } } }, "CustomerPasswordResetRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "PaymentAmount": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } } }, "PaymentIdentification": { "type": "object", "description": "Counterparty identification for payment create.\n`type` uses platform identification-catalog keys (e.g. `cedula`, `juridica`, `dimex`).\nSame vocabulary as `holder.id_type` from `POST /accounts/validate`.\n`number` is the public identification (digits, no SINPE hyphens). The platform\nmay reformat it internally for GX/SINPE; that internal form is not echoed on\npublic payment reads for payments created after public identification persistence.\nFor SINPE_MOVIL, account validate may return `unknown` because the wallet\noperation does not expose identification type; do not assume a confirmed type.\n", "properties": { "type": { "type": "string", "description": "Identification catalog key (lowercase), e.g. `cedula`, `juridica`.\nMay be copied from `holder.id_type` after account validate.\nFor SINPE_MOVIL that value may be `unknown` (expected limitation, not an error).\n", "example": "cedula" }, "number": { "type": "string", "description": "Public identification number as submitted by the partner.\nDigits only; do not send SINPE hyphenation (e.g. `01-1234-3005`)\nor treat this field as the internal GX/SINPE display form.\nSupported types include `cedula`, `juridica`, `dimex`, `gobierno`,\n`institucion_autonoma`, `didi`, and `pasaporte`.\n", "example": "0101010101" } } }, "PaymentAccount": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "Account **identifier scheme** (e.g. `IBAN`, `PHONE`).\nNot the internal account classification (e.g. operational).\n", "enum": [ "IBAN", "PHONE" ], "example": "IBAN" }, "value": { "type": "string" }, "currency": { "type": "string", "description": "Optional account currency in response payloads." } } }, "DestinationAccount": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "Counterparty account **identifier scheme** (`IBAN` for PIN, `PHONE` for SINPE_MOVIL).\nNot the internal account classification.\n", "enum": [ "IBAN", "PHONE" ], "example": "IBAN" }, "value": { "type": "string" } } }, "IBANAccount": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "Account **identifier scheme**. Only `IBAN` is supported here.\nThis is not the internal account classification\n(e.g. operational).\n", "enum": [ "IBAN" ], "example": "IBAN" }, "value": { "type": "string", "description": "IBAN (spaces allowed; normalized server-side)" } } }, "DestinationPaymentSide": { "type": "object", "required": [ "account", "name", "identification" ], "properties": { "account": { "$ref": "#/components/schemas/DestinationAccount" }, "name": { "type": "string", "description": "Counterparty name" }, "identification": { "$ref": "#/components/schemas/PaymentIdentification", "description": "Counterparty identification (e.g. cedula)" } } }, "SourcePaymentSide": { "type": "object", "required": [ "account", "name", "identification" ], "properties": { "account": { "$ref": "#/components/schemas/IBANAccount", "description": "Internal account identified by IBAN" }, "name": { "type": "string", "description": "Account holder name" }, "identification": { "$ref": "#/components/schemas/PaymentIdentification", "description": "Account holder identification (e.g. cedula)" } } }, "PaymentRequest": { "type": "object", "required": [ "payment_method_code", "direction", "amount", "source", "destination", "detail_reference" ], "properties": { "payment_method_code": { "type": "string", "description": "Public payment method catalog (`PIN`, `SINPE_MOVIL`).", "enum": [ "PIN", "SINPE_MOVIL" ], "example": "PIN" }, "direction": { "type": "string", "enum": [ "OUT", "IN" ], "description": "Operation direction (OUT = payout from internal source)", "example": "OUT" }, "country_code": { "type": "string", "description": "Operational country when multi-country applies", "example": "CR" }, "amount": { "$ref": "#/components/schemas/PaymentAmount" }, "source": { "$ref": "#/components/schemas/SourcePaymentSide" }, "destination": { "$ref": "#/components/schemas/DestinationPaymentSide" }, "detail_reference": { "type": "string", "description": "Operational / transactional description stored on the payment", "example": "Pago factura 1001" }, "client_reference": { "type": "string", "description": "Partner functional reference. Unique per tenant among in-flight and completed payments; a failed attempt can be retried with the same value.", "example": "INV-1001" }, "channel_reference": { "type": "string", "example": "MOBILE_APP" }, "originator": { "$ref": "#/components/schemas/PaymentOriginator" } }, "example": { "payment_method_code": "PIN", "direction": "OUT", "country_code": "CR", "amount": { "amount": "1000.00", "currency": "CRC" }, "source": { "account": { "type": "IBAN", "value": "CR26036900101010588061" }, "name": "María González", "identification": { "type": "cedula", "number": "0205620043" } }, "destination": { "account": { "type": "IBAN", "value": "CR16010400000000000031" }, "name": "Juan Perez", "identification": { "type": "cedula", "number": "0101010101" } }, "detail_reference": "Pago factura 1001", "client_reference": "INV-1001", "channel_reference": "MOBILE_APP" } }, "PaymentOriginator": { "type": "object", "nullable": true, "description": "Optional Ultimate Debtor / Travel Rule originator information.\nInformational only in this release; no validation is applied.\nStored under payment metadata when provided.\n", "properties": { "company": { "$ref": "#/components/schemas/PaymentOriginatorCompany" }, "customer": { "$ref": "#/components/schemas/PaymentOriginatorCustomer" } } }, "PaymentOriginatorCompany": { "type": "object", "nullable": true, "properties": { "legal_name": { "type": "string", "example": "Acme Holdings S.A." }, "id_type": { "type": "string", "example": "juridica" }, "id_number": { "type": "string", "example": "3101123456" } } }, "PaymentOriginatorCustomer": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "Juan Perez" }, "id_type": { "type": "string", "example": "cedula" }, "id_number": { "type": "string", "example": "0101010101" } } }, "GetAccountBalanceRequest": { "type": "object", "required": [ "account" ], "properties": { "account": { "$ref": "#/components/schemas/IBANAccount" } }, "example": { "account": { "type": "IBAN", "value": "CR12036900101019858991" } } }, "PublicPaymentStatus": { "type": "string", "description": "Public payment status catalog. Always lowercase. Same values on REST\n(create, list, get) and webhooks (`payment.status`).\n\nInternal lifecycle states are collapsed:\n- `pending`: initiated, validated, accepted\n- `processing`: processing, pending_processing, posting\n- `confirmed`: confirmed by the rail, not yet ledger-posted\n- `posted`: ledger posted (stays `posted` after a later reversal)\n- `failed`: failed, rejected, posting_failed, cancelled, expired\n\nA reversal is **not** a status. Use REST `result=reversed` / `has_reversal=true`\nand webhook `payment.reversed`.\n\nOperational detail remains in `status_detail` (uppercase internal name)\non REST create/list/get. Webhook `payment.failed` uses `error.platform.code`\nto distinguish posting failures from provider rejections.\n", "enum": [ "pending", "processing", "confirmed", "posted", "failed" ], "example": "posted" }, "PublicPaymentAmount": { "type": "object", "required": [ "amount", "currency" ], "description": "Same monetary shape as payment create (`PaymentAmount`).", "properties": { "amount": { "type": "string", "example": "1000.00" }, "currency": { "type": "string", "example": "CRC" } } }, "PublicPaymentSide": { "type": "object", "required": [ "account", "name", "identification" ], "description": "Payment party on read APIs. Nested fields are always present:\n`null` when the value is unknown. `account` is a public identifier\n(`IBAN` or `PHONE`); ledger/account UUIDs are never returned.\n", "properties": { "account": { "allOf": [ { "$ref": "#/components/schemas/PaymentAccount" } ], "nullable": true, "description": "Public account identifier (`type` + `value`). `null` when the IBAN or\nphone cannot be resolved. Never a ledger UUID or `ACCOUNT_ID`.\n" }, "name": { "type": "string", "nullable": true, "description": "Party name from processing metadata when available; otherwise `null`." }, "identification": { "allOf": [ { "$ref": "#/components/schemas/PublicPaymentIdentification" } ], "nullable": true, "description": "Party identification (`type` catalog key + `number`). Object only when\nat least one field is known; otherwise `null`. Does not expose internal\nSINPE type codes (`0`–`9`); unmapped types are omitted (`type: null`).\n`number` is the partner-submitted public value for payments created after\npublic identification persistence (digits, no SINPE hyphens). Historical\npayments may still return the hyphenated SINPE display form.\n" } } }, "PublicPaymentProvider": { "type": "object", "description": "Shared provider snapshot on REST payment reads and webhook envelopes.\nRail reference is only on `payment.external_reference`, not duplicated here.\n`provider_status_*` match webhook `rejection.reason_code` / `message` / `code`\nwhen the provider rejected the operation. `null` when there is no rejection.\n", "required": [ "correlation_id", "occurred_at", "provider_status_code", "provider_status_desc", "provider_status_semantic" ], "properties": { "correlation_id": { "type": "string", "nullable": true, "description": "Transaction correlation UUID (`execution.correlation_id` /\n`metadata.tx.correlationId`). Sent to GX/SINPE as `correlationId`.\nNot `channel_reference` (e.g. `MOBILE_APP`). Distinct from webhook\n`event.correlation_id` (HTTP request id for this delivery). `null` when unknown.\n" }, "occurred_at": { "$ref": "#/components/schemas/Rfc3339DateTime", "nullable": true, "description": "When this provider-facing event was recorded (RFC 3339 UTC, second precision,\n`Z`). Webhooks use `event.occurred_at`; REST uses `succeeded_at` when present,\notherwise `updated_at`. `null` when unknown.\n" }, "provider_status_code": { "type": "string", "nullable": true, "description": "Raw provider Motivo/code (e.g. `31`). Same meaning as webhook\n`rejection.reason_code`. `null` when there is no provider rejection.\n", "example": "31" }, "provider_status_desc": { "type": "string", "nullable": true, "description": "Provider Motivo text (prefers Detalle). Same meaning as webhook\n`rejection.message`. `null` when there is no provider rejection.\n", "example": "Cuenta bloqueada" }, "provider_status_semantic": { "type": "string", "nullable": true, "description": "Normalized platform semantic (e.g. `ACCOUNT_BLOCKED`). Same meaning as\nwebhook `rejection.code`. `null` when there is no provider rejection.\n", "example": "ACCOUNT_BLOCKED" } } }, "PublicPaymentIdentification": { "type": "object", "description": "Party identification on payment read APIs. Present only when `type` and/or\n`number` is known. Catalog keys match create (`cedula`, `juridica`, `dimex`, …).\nRaw SINPE numeric type codes are not exposed.\n\nFor payments created after public identification persistence, `number` is the\nsame public value submitted on `POST /transactions/payments` (digits, no SINPE\nhyphens such as `01-1234-3005`). It is not taken from the GX resend snapshot.\n\nPayments created before that change have no public snapshot. Reads then keep\nthe previous behavior: `number` may be the hyphenated SINPE form stored for\nGX/SINPE communication. Those historical values are not rewritten.\nSee `docs/PAYMENT-IDENTIFICATION.md`.\n", "properties": { "type": { "type": "string", "nullable": true, "description": "Identification catalog key (e.g. `cedula`, `juridica`). `null` when unknown.", "example": "cedula" }, "number": { "type": "string", "nullable": true, "description": "Public identification number. New PIN payments return the partner-submitted\nvalue (digits, no SINPE hyphens). Historical payments may still return\nthe SINPE display form (hyphenated, possibly padded).\n", "example": "0101010101" } } }, "PublicPaymentError": { "type": "object", "description": "Same shape as webhook `payment.failed` `payment.error` (`domain` / `platform`).\nPresent only when `result` is `failed` or `reversed` and taxonomy is known.\nEmpty objects are not used; the parent `error` field is `null` instead.\n", "required": [ "domain", "platform" ], "properties": { "domain": { "type": "string", "description": "Same catalog as webhook `payment.error.domain`.", "enum": [ "provider_rejection", "platform_validation", "platform_posting", "platform_infra", "platform_reversal" ], "example": "provider_rejection" }, "platform": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable platform public code (same as webhook `payment.error.platform.code`).", "example": "PAYMENT_SINPE_REJECTED" }, "message": { "type": "string", "description": "Actionable message (prefers provider Detalle). Same as webhook `payment.error.platform.message`.", "example": "Cuenta bloqueada" } } } } }, "PublicPayment": { "type": "object", "required": [ "schema_version", "payment_id", "type", "payment_method_code", "status", "result", "has_reversal", "error" ], "properties": { "schema_version": { "type": "string", "description": "Payment-read contract version. Same value as webhook envelope\n`schema_version` (`1.0.0`) for `payment.succeeded` / `payment.failed`.\n", "example": "1.0.0" }, "payment_id": { "type": "string", "format": "uuid", "description": "Payment UUID returned by create. Partner-facing payment key for\n`GET /transactions/payments/{payment_id}` and search. Not a ledger\nor internal account id.\n" }, "public_id": { "type": "string", "nullable": true, "description": "Numeric public payment identifier returned by create. `null` if not\nyet assigned. Not a ledger/account UUID.\n" }, "type": { "type": "string", "description": "Payment type derived from direction (`PAYIN` / `PAYOUT`)." }, "payment_method_code": { "type": "string", "description": "Public payment method catalog (`PIN`, `SINPE_MOVIL`). Same values as webhooks.", "enum": [ "PIN", "SINPE_MOVIL" ], "example": "PIN" }, "status": { "$ref": "#/components/schemas/PublicPaymentStatus" }, "status_detail": { "type": "string", "description": "Operational (internal) status in uppercase, e.g. `VALIDATED`,\n`POSTED`, `POSTING_FAILED`. Companion to the public `status` catalog.\nIndependent of `result` (`posted` is the debit/posting milestone, not provider success).\n" }, "result": { "type": "string", "enum": [ "succeeded", "failed", "reversed", "pending" ], "description": "Consolidated business outcome for reconciliation (backup to webhooks).\nIndependent of processing `status`. Derived as: `reversed` when\n`has_reversal` is true (highest priority); `succeeded` when `succeeded_at`\nis set and there is no reversal; `failed` when processing status is\n`failed` or `posting_failed`; otherwise `pending`.\nA posted payment that was later reversed has `status=posted` and `result=reversed`.\n" }, "succeeded_at": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339DateTime" } ], "nullable": true, "description": "Provider success confirmation timestamp (RFC 3339 UTC, second precision, `Z`).\nNull while the payment may already be `posted` internally but the provider has not confirmed success.\n" }, "has_reversal": { "type": "boolean", "description": "True when a reversal was applied. Independent of `status`. Correlates with webhook `payment.reversed`." }, "reversed_at": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339DateTime" } ], "nullable": true, "description": "When the reversal was applied. Null when `has_reversal` is false." }, "created_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "updated_at": { "$ref": "#/components/schemas/Rfc3339DateTime" }, "amount": { "$ref": "#/components/schemas/PublicPaymentAmount" }, "source": { "$ref": "#/components/schemas/PublicPaymentSide" }, "destination": { "$ref": "#/components/schemas/PublicPaymentSide" }, "client_reference": { "type": "string", "description": "Partner reference sent at payment creation (stable after processing). Same field as webhook `payment.client_reference`." }, "external_reference": { "type": "string", "nullable": true, "description": "Rail/SINPE transaction id. Same field, location, and meaning as webhook\n`payment.external_reference` on `payment.succeeded` / `payment.failed`\n(`metadata.sinpe_reference`, else `external_provider_tx_id`). Sibling of\n`client_reference`. `null` if none.\n" }, "provider": { "$ref": "#/components/schemas/PublicPaymentProvider" }, "error": { "allOf": [ { "$ref": "#/components/schemas/PublicPaymentError" } ], "nullable": true, "description": "Always present. `null` when there is no failure information\n(`succeeded`, `pending`, or failed/reversed without taxonomy).\nObject uses the same `domain` / `platform` shape as webhook `payment.failed`.\n" } } }, "GetPaymentByIDResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicPayment" } } } ] }, "SearchPaymentRequest": { "type": "object", "description": "The customer account and exactly one of `payment_id`, `public_id`, or `client_reference` must be provided.\n", "properties": { "account": { "$ref": "#/components/schemas/PaymentAccount" }, "payment_id": { "type": "string", "format": "uuid", "description": "Internal payment UUID." }, "public_id": { "type": "string", "description": "Numeric public payment identifier.", "example": "134729" }, "client_reference": { "type": "string", "description": "Partner reference sent at payment creation.", "example": "INV-01082" } }, "required": [ "account" ] }, "CreatePaymentResponseData": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid", "description": "Internal payment UUID" }, "public_id": { "type": "string", "description": "Public numeric payment identifier" }, "status": { "$ref": "#/components/schemas/PublicPaymentStatus" }, "status_detail": { "type": "string", "description": "Operational status detail (e.g. PROCESSING)" }, "payment_method_code": { "type": "string", "description": "Public payment method catalog (`PIN`, `SINPE_MOVIL`).", "enum": [ "PIN", "SINPE_MOVIL" ], "example": "PIN" }, "created_at": { "$ref": "#/components/schemas/Rfc3339DateTime" } } }, "CreatePaymentResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "http_status_code": { "type": "integer", "example": 201 }, "response_code": { "allOf": [ { "$ref": "#/components/schemas/ResponseCode" } ], "example": "CREATED" }, "message": { "type": "string", "example": "The resource was created successfully." }, "data": { "$ref": "#/components/schemas/CreatePaymentResponseData" } } } ] }, "ListPaymentsResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "schema_version", "items" ], "properties": { "schema_version": { "type": "string", "description": "Same value as webhook envelope `schema_version` (`1.0.0`).", "example": "1.0.0" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPayment" } }, "pagination": { "$ref": "#/components/schemas/ListPaymentsPagination" } } } } } ] }, "ListPaymentsPagination": { "type": "object", "description": "Cursor pagination. Pass next_cursor as cursor on the next request.", "properties": { "next_cursor": { "type": "string", "description": "Opaque cursor for the next page; omitted or empty when there is no next page" }, "limit": { "type": "integer", "description": "Page size applied to this response" } } }, "AccountValidateRequest": { "type": "object", "required": [ "payment_method_code", "account" ], "properties": { "payment_method_code": { "type": "string", "description": "Payment method used to route validation (PIN for external IBAN, SINPE_MOVIL for phone wallet).", "enum": [ "PIN", "SINPE_MOVIL" ], "example": "PIN" }, "account": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "IBAN", "PHONE" ], "example": "IBAN" }, "value": { "type": "string" } } } }, "example": { "payment_method_code": "PIN", "account": { "type": "IBAN", "value": "CR16010400000000000031" } } }, "AccountValidateResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "is_valid": { "type": "boolean" }, "account": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "currency": { "type": "string" }, "product_name": { "type": "string" } } }, "holder": { "type": "object", "nullable": true, "description": "Account holder when validation succeeds.\n`id_type` matches `PaymentIdentification.type` (same catalog as POST /payments).\nFor SINPE_MOVIL, `id_type` may be `unknown` because the wallet\noperation does not return an identification type. That is expected\nand stable; do not treat it as a bug.\n", "properties": { "name": { "type": "string" }, "id_type": { "type": "string", "description": "Identification catalog key (lowercase), e.g. `cedula`, `juridica`, `dimex`.\nSame vocabulary as `identification.type` on payment create.\n\nPIN: mapped from the provider's `CodTipoIdDestino` (confirmed by the provider).\nSINPE_MOVIL: `ObtenerInfoMonedero` does not return an identification\ntype, so this field **may be `unknown`**. That is expected, stable\nbehavior due to available provider data — not a mapping bug or a\ntransient error. Do not assume a confirmed type is always present.\n", "enum": [ "cedula", "dimex", "gobierno", "juridica", "institucion_autonoma", "didi", "pasaporte", "unknown" ], "example": "cedula" }, "id_number": { "type": "string" } } }, "financial_institution": { "type": "object", "nullable": true, "description": "Counterparty institution when validation succeeds.\n\nPIN fills `entity_name` from `InformacionCuenta.Entidad`.\nSINPE_MOVIL only receives an entity **code** from `ObtenerInfoMonedero`;\nthe operation does not return the institution name, so `entity_name`\n**may be `\"\"`**. That is expected, stable behavior — not a transient\nerror. Do not assume `entity_name` is always populated.\n", "properties": { "country_code": { "type": "string" }, "entity_code": { "type": "string" }, "entity_name": { "type": "string", "description": "Human-readable institution name.\nPIN: populated from the provider account-info operation.\nSINPE_MOVIL: may be `\"\"` because `ObtenerInfoMonedero` does not\nexpose the name. Expected limitation, not an error.\n", "example": "Banco Davivienda (Costa Rica) S.A." } } }, "rejection": { "allOf": [ { "$ref": "#/components/schemas/WebhookRejection" } ], "nullable": true, "description": "Present when `is_valid` is `false` and the provider rejected the account. `null` when `is_valid` is `true`." }, "provider": { "type": "object", "properties": { "operation": { "type": "string" }, "correlation_id": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } ] }, "BalanceAmounts": { "type": "object", "description": "Ledger balances as decimal strings with 2 fraction digits\n(same display scale as public payment amounts). Prefer string over JSON number\nfor financial amounts.\n", "properties": { "available": { "type": "string", "example": "991900.00" }, "posted": { "type": "string", "example": "991900.00" }, "inbound_in_transit": { "type": "string", "example": "0.00" }, "outbound_in_transit": { "type": "string", "example": "0.00" } } }, "AccountBalance": { "type": "object", "required": [ "account", "amounts", "as_of" ], "description": "Balance snapshot. `amounts` and `as_of` are only returned on\n`GET /accounts/balances` and `POST /accounts/balance`.\n", "properties": { "account": { "$ref": "#/components/schemas/PaymentAccount", "description": "Same shape as balance request (type + value); IBAN when available" }, "amounts": { "$ref": "#/components/schemas/BalanceAmounts" }, "as_of": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339DateTime" } ], "nullable": true, "description": "Ledger timestamp when known (RFC 3339 UTC, second precision, `Z`); `null` when not available." } } }, "PublicAccount": { "type": "object", "required": [ "account" ], "description": "Account attributes only. Used by `GET /accounts`. Does not include\n`amounts` or `as_of`.\n", "properties": { "account": { "$ref": "#/components/schemas/PaymentAccount" } } }, "AccountsPagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } }, "GetAccountBalanceResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountBalance" } } } ] }, "CreateAccountStatementRequest": { "type": "object", "required": [ "account", "date_from", "date_to" ], "properties": { "account": { "$ref": "#/components/schemas/IBANAccount", "description": "Account identified by identifier scheme + value (`type` + `value`).\nSame public standard as balance and payments. Not the internal\naccount classification.\n" }, "date_from": { "$ref": "#/components/schemas/Rfc3339DateTimeInput" }, "date_to": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339DateTimeInput" } ], "description": "RFC 3339 (max 60 days after date_from)" }, "notify_email": { "type": "boolean", "default": false } }, "example": { "account": { "type": "IBAN", "value": "CR12036900101019858991" }, "date_from": "2026-01-01T00:00:00Z", "date_to": "2026-01-31T23:59:59Z", "notify_email": false } }, "AccountStatementCreated": { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "DONE", "ERROR" ] } } }, "CreateAccountStatementResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/CreateAccountStatementRequest" }, "data": { "$ref": "#/components/schemas/AccountStatementCreated" } } } ] }, "AccountStatementStatus": { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "DONE", "ERROR" ] }, "download_url": { "type": "string", "format": "uri", "description": "Signed GCS download URL (present when status is DONE and the link has not expired)" }, "expires_at": { "allOf": [ { "$ref": "#/components/schemas/Rfc3339DateTime" } ], "description": "Expiration of download_url (48h from generation)" }, "message": { "type": "string", "description": "Generic error message when status is ERROR" } } }, "GetAccountStatementStatusResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccountStatementStatus" } } } ] }, "ListAccountsResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAccount" } }, "pagination": { "$ref": "#/components/schemas/AccountsPagination" } } } } } ] }, "ListAccountBalancesResponse": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalance" } }, "pagination": { "$ref": "#/components/schemas/AccountsPagination" } } } } } ] }, "AddWebhookDestinationRequest": { "type": "object", "description": "Single object shape; **which fields are required or forbidden** is determined by `destination_kind` and `scope_kind` (see operation description). Values are case-insensitive where the server normalizes to uppercase for kinds.\n", "required": [ "feature_id", "destination_kind", "scope_kind" ], "properties": { "feature_id": { "type": "string", "format": "uuid", "description": "Feature to subscribe (from `GET /api/public/v1/webhook/features`). Must exist or create fails." }, "is_enabled": { "type": "boolean", "description": "Defaults to true if omitted." }, "destination_kind": { "type": "string", "description": "Public API accepts only `EXTERNAL_WEBHOOK` (HTTPS callback with shared secret). `INTERNAL` destinations are managed administratively.\n", "enum": [ "EXTERNAL_WEBHOOK" ] }, "destination_ref": { "type": "string", "nullable": true, "description": "Not used on the public API. Reserved for internal destinations." }, "webhook_url": { "type": "string", "format": "uri", "nullable": true, "description": "Required (must use `https://`)." }, "secret_ref": { "type": "string", "nullable": true, "description": "Required shared secret used to decrypt AES_GCM payloads (`key = SHA256(secret_ref)`).\nSee \"Webhook encryption\" in this operation's description.\n" }, "signature_algo": { "type": "string", "nullable": true, "enum": [ "AES_GCM" ], "description": "Fixed to `AES_GCM` for `EXTERNAL_WEBHOOK`. Omitted on create; stored as `AES_GCM`.\n`HMAC_SHA256` is no longer supported.\n" }, "replay_window_sec": { "type": "integer", "nullable": true, "description": "Reserved for legacy destinations. Not used for `EXTERNAL_WEBHOOK` AES_GCM deliveries.\n" }, "timeout_ms": { "type": "integer", "nullable": true, "description": "HTTP timeout for delivery attempts (`EXTERNAL_WEBHOOK`)." }, "max_attempts": { "type": "integer", "nullable": true, "description": "Max delivery attempts (`EXTERNAL_WEBHOOK`)." }, "backoff_policy": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Optional free-form JSON retry/backoff override, stored as-is and not\ncurrently validated or documented by the platform. Omit to use the\nplatform's default backoff policy.\n" }, "scope_kind": { "type": "string", "description": "- `TENANT`: no scope id fields.\n- `ACCOUNT`: set `scope_account_id` only.\n- `OWNER`: set `scope_owner_type` and `scope_owner_id` only.\n", "enum": [ "TENANT", "ACCOUNT", "OWNER" ] }, "scope_account_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Required when `scope_kind` is `ACCOUNT`. Must be omitted for `TENANT` and `OWNER`." }, "scope_owner_type": { "type": "string", "nullable": true, "description": "Required when `scope_kind` is `OWNER`. Allowed values (lowercase) `tenant`, `partner`, `user`, `platform`, `customer`. Omit for `TENANT` and `ACCOUNT`." }, "scope_owner_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Required when `scope_kind` is `OWNER`. Omit for `TENANT` and `ACCOUNT`." } } } }, "examples": { "Error_UNAUTHORIZED": { "summary": "UNAUTHORIZED: Unauthorized. Verify your session or credentials.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNAUTHORIZED", "message": "Unauthorized. Verify your session or credentials." }, "http_status_code": 401, "message": "Unauthorized. Verify your session or credentials.", "payload": null, "response_code": "UNAUTHORIZED", "success": false } }, "Error_FORBIDDEN": { "summary": "FORBIDDEN: You do not have permission to perform this action.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "FORBIDDEN", "message": "You do not have permission to perform this action." }, "http_status_code": 403, "message": "You do not have permission to perform this action.", "payload": null, "response_code": "FORBIDDEN", "success": false } }, "Error_INVALID_REQUEST": { "summary": "INVALID_REQUEST: Invalid request. Check the required fields and try again.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_REQUEST", "message": "Invalid request. Check the required fields and try again." }, "http_status_code": 400, "message": "Invalid request. Check the required fields and try again.", "payload": null, "response_code": "INVALID_REQUEST", "success": false } }, "Error_INVALID_CREDENTIALS": { "summary": "INVALID_CREDENTIALS: Invalid email or password.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_CREDENTIALS", "message": "Invalid email or password." }, "http_status_code": 401, "message": "Invalid email or password.", "payload": null, "response_code": "INVALID_CREDENTIALS", "success": false } }, "Error_NOT_FOUND": { "summary": "NOT_FOUND: The requested resource was not found.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "http_status_code": 404, "message": "The requested resource was not found.", "payload": null, "response_code": "NOT_FOUND", "success": false } }, "Error_CONFLICT": { "summary": "CONFLICT: The request conflicts with the current state.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "CONFLICT", "message": "The request conflicts with the current state." }, "http_status_code": 409, "message": "The request conflicts with the current state.", "payload": null, "response_code": "CONFLICT", "success": false } }, "Error_UNPROCESSABLE_ENTITY": { "summary": "UNPROCESSABLE_ENTITY: The request is well-formed but cannot be processed due to business rules.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "UNPROCESSABLE_ENTITY", "message": "The request is well-formed but cannot be processed due to business rules." }, "http_status_code": 422, "message": "The request is well-formed but cannot be processed due to business rules.", "payload": null, "response_code": "UNPROCESSABLE_ENTITY", "success": false } }, "Error_TOO_MANY_REQUESTS": { "summary": "TOO_MANY_REQUESTS: Too many requests. Please retry after a short delay.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Please retry after a short delay." }, "http_status_code": 429, "message": "Too many requests. Please retry after a short delay.", "payload": null, "response_code": "TOO_MANY_REQUESTS", "success": false } }, "Error_ACCOUNT_ACCESS_DENIED": { "summary": "ACCOUNT_ACCESS_DENIED: The actor does not have access to the requested account.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_ACCESS_DENIED", "message": "The actor does not have access to the requested account." }, "http_status_code": 403, "message": "The actor does not have access to the requested account.", "payload": null, "response_code": "ACCOUNT_ACCESS_DENIED", "success": false } }, "Error_ACCOUNT_INVALID": { "summary": "ACCOUNT_INVALID: The account is invalid or not enabled for the service.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_INVALID", "message": "The account is invalid or not enabled for the service." }, "http_status_code": 400, "message": "The account is invalid or not enabled for the service.", "payload": null, "response_code": "ACCOUNT_INVALID", "success": false } }, "Error_ACCOUNT_HOLDER_MISMATCH": { "summary": "ACCOUNT_HOLDER_MISMATCH: Account holder does not match the provided identification or name.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_HOLDER_MISMATCH", "message": "Account holder does not match the provided identification or name." }, "http_status_code": 400, "message": "Account holder does not match the provided identification or name.", "payload": null, "response_code": "ACCOUNT_HOLDER_MISMATCH", "success": false } }, "Error_ACCOUNT_NOT_FOUND": { "summary": "ACCOUNT_NOT_FOUND: Account not found.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_NOT_FOUND", "message": "Account not found." }, "http_status_code": 404, "message": "Account not found.", "payload": null, "response_code": "ACCOUNT_NOT_FOUND", "success": false } }, "Error_ACCOUNT_NOT_CONFIGURED": { "summary": "ACCOUNT_NOT_CONFIGURED: This account is not mapped in the system. Please contact support to configure it correctly.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "ACCOUNT_NOT_CONFIGURED", "message": "This account is not mapped in the system. Please contact support to configure it correctly." }, "http_status_code": 422, "message": "This account is not mapped in the system. Please contact support to configure it correctly.", "payload": null, "response_code": "ACCOUNT_NOT_CONFIGURED", "success": false } }, "Error_PAYMENT_NOT_FOUND": { "summary": "PAYMENT_NOT_FOUND: Payment not found.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PAYMENT_NOT_FOUND", "message": "Payment not found." }, "http_status_code": 404, "message": "Payment not found.", "payload": null, "response_code": "PAYMENT_NOT_FOUND", "success": false } }, "Error_PAYMENT_INVALID_PAYLOAD": { "summary": "PAYMENT_INVALID_PAYLOAD: Invalid payment request payload.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PAYMENT_INVALID_PAYLOAD", "message": "Invalid payment request payload." }, "http_status_code": 400, "message": "Invalid payment request payload.", "payload": null, "response_code": "PAYMENT_INVALID_PAYLOAD", "success": false } }, "Error_INVALID_ACCOUNT_FORMAT": { "summary": "INVALID_ACCOUNT_FORMAT: Invalid account format.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_ACCOUNT_FORMAT", "message": "Invalid account format." }, "http_status_code": 400, "message": "Invalid account format.", "payload": null, "response_code": "INVALID_ACCOUNT_FORMAT", "success": false } }, "Error_INVALID_ACCOUNT_TYPE": { "summary": "INVALID_ACCOUNT_TYPE: Unsupported or invalid account type.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_ACCOUNT_TYPE", "message": "Unsupported or invalid account type." }, "http_status_code": 400, "message": "Unsupported or invalid account type.", "payload": null, "response_code": "INVALID_ACCOUNT_TYPE", "success": false } }, "Error_INVALID_PAYMENT_METHOD": { "summary": "INVALID_PAYMENT_METHOD: Invalid or unsupported payment method.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INVALID_PAYMENT_METHOD", "message": "Invalid or unsupported payment method." }, "http_status_code": 400, "message": "Invalid or unsupported payment method.", "payload": null, "response_code": "INVALID_PAYMENT_METHOD", "success": false } }, "Error_IDEMPOTENCY_CONFLICT": { "summary": "IDEMPOTENCY_CONFLICT: Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress." }, "http_status_code": 409, "message": "Idempotency conflict: the same Idempotency-Key was reused with a different request body, or a previous request is still in progress.", "payload": null, "response_code": "IDEMPOTENCY_CONFLICT", "success": false } }, "Error_PAYMENT_DUPLICATE": { "summary": "PAYMENT_DUPLICATE: An in-flight or completed payment with this client_reference already exists.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PAYMENT_DUPLICATE", "message": "An in-flight or completed payment with this client_reference already exists." }, "http_status_code": 409, "message": "An in-flight or completed payment with this client_reference already exists.", "payload": null, "response_code": "PAYMENT_DUPLICATE", "success": false } }, "Error_INSUFFICIENT_FUNDS": { "summary": "INSUFFICIENT_FUNDS: Insufficient funds to complete the payment.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INSUFFICIENT_FUNDS", "message": "Insufficient funds to complete the payment." }, "http_status_code": 422, "message": "Insufficient funds to complete the payment.", "payload": null, "response_code": "INSUFFICIENT_FUNDS", "success": false } }, "Error_LIMIT_EXCEEDED": { "summary": "LIMIT_EXCEEDED: A transaction or accumulation limit was exceeded.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "LIMIT_EXCEEDED", "message": "A transaction or accumulation limit was exceeded." }, "http_status_code": 422, "message": "A transaction or accumulation limit was exceeded.", "payload": null, "response_code": "LIMIT_EXCEEDED", "success": false } }, "Error_PROVIDER_ERROR": { "summary": "PROVIDER_ERROR: Unable to complete the request with the payment provider. Please try again later.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "PROVIDER_ERROR", "message": "Unable to complete the request with the payment provider. Please try again later." }, "http_status_code": 502, "message": "Unable to complete the request with the payment provider. Please try again later.", "payload": null, "response_code": "PROVIDER_ERROR", "success": false } }, "Error_SERVICE_UNAVAILABLE": { "summary": "SERVICE_UNAVAILABLE: A required service is temporarily unavailable. Please try again later.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "SERVICE_UNAVAILABLE", "message": "A required service is temporarily unavailable. Please try again later." }, "http_status_code": 503, "message": "A required service is temporarily unavailable. Please try again later.", "payload": null, "response_code": "SERVICE_UNAVAILABLE", "success": false } }, "Error_INTERNAL_ERROR": { "summary": "INTERNAL_ERROR: An unexpected error occurred. Please try again later.", "value": { "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "errors": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred. Please try again later." }, "http_status_code": 500, "message": "An unexpected error occurred. Please try again later.", "payload": null, "response_code": "INTERNAL_ERROR", "success": false } } } }, "x-public-api-error-codes-source": "redis:public_api_openapi_cache+in-code:EndpointMatrix", "x-public-api-error-codes-generated-at": "2026-09-03T01:37:01Z" }