{ "openapi": "3.0.0", "info": { "title": "Migo API", "version": "1.0", "description": "REST API for the Migo Payments platform. Orchestrates payments across 25+ processors, manages clients, transactions, cards, subscriptions, plans and suspensions.", "contact": {} }, "servers": [ { "url": "https://mw.migopayments.com", "description": "Production" }, { "url": "https://sb-mw.migopayments.com", "description": "Sandbox" }, { "url": "http://localhost:3000", "description": "Local" } ], "tags": [ { "name": "Verifications", "description": "Pre-transaction verification endpoints (BIN eligibility, user checks, etc)." }, { "name": "Suspensions", "description": "Per-client blacklist, whitelist and suspension rule management." }, { "name": "Subscriptions", "description": "Subscription lifecycle, payment methods, charges and billing history." }, { "name": "Plans", "description": "Subscription plan catalog and plan-level configuration." }, { "name": "Transactions", "description": "Transaction creation, lookup, search and export." }, { "name": "Payments", "description": "Payment processing operations: charge, revert, refund and capture against existing transactions." }, { "name": "Cards", "description": "Card tokenization and management (including merchant cards)." }, { "name": "Auth", "description": "OTP, session tokens and authorizers." }, { "name": "Config", "description": "Webview, processor, user and redirect configuration." }, { "name": "Alternative Payments", "description": "Alternative payment methods (PIX, Nequi, PSE, QR, cash references). Multi-step async flows: create transaction → process payment via redirect/QR/intent → dismiss when expired." }, { "name": "Webhooks", "description": "Inbound processor callbacks (`/hook/{processor}`, `/capture-hook`, `/cancel-hook`) and outbound merchant notifications. Routed dynamically via `processorCfg.methods.hook.functionName`." } ], "paths": { "/middleware-cards": { "post": { "summary": "Tokenise card", "description": "Tokenises a card against the selected processor and links the resulting token to the supplied transaction. Dispatched via `tokenizeMethods` (`fac`, `fac-2`, `visa-cybersource`, `visa-epay`, `mercadoPago`, `azul`, `serfinsa`, `t1pagos`, `paymentez`, `globalPay`, `push-payment-gateway`). Behaviour varies per processor — some perform AVS / 3DS pre-checks, others store metadata in `transaction.additionalData` only.", "tags": [ "Cards" ], "operationId": "MiddlewareCardsController_tokenize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizeCardBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Card tokenised. Response carries the Migo card summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizeCardResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters). ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Processor explicitly forbids tokenisation (e.g. `globalPay`, `paymentez`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Client or processor configuration not found. ownCode in {5004, 5001}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Tokenisation upstream failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] }, "get": { "summary": "List user cards", "description": "Returns the list of tokenised cards stored for the authenticated user. Cards are stored per merchant client; the JWT carries the user identifier the lookup uses.", "tags": [ "Cards" ], "operationId": "MiddlewareCardsController_getCards", "responses": { "200": { "description": "List of stored cards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCardsResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] }, "put": { "summary": "Update card metadata", "description": "Updates editable fields on a stored card (alias, default-flag). Card data itself is immutable — to swap PAN or expiry the integrator must re-tokenise.", "tags": [ "Cards" ], "operationId": "MiddlewareCardsController_updateCard", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Card updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardsGenericResponseDto" } } } }, "400": { "description": "Missing `cardId` or invalid update payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Card not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] }, "delete": { "summary": "Delete stored card", "description": "Removes a tokenised card from the user. The processor-side token may or may not be revoked depending on processor capabilities.", "tags": [ "Cards" ], "operationId": "MiddlewareCardsController_deleteCard", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCardBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Card deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardsGenericResponseDto" } } } }, "400": { "description": "Missing `cardId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Card not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] } }, "/middleware-cards/luhn": { "post": { "summary": "Validate PAN with Luhn checksum", "description": "Public utility endpoint (no JWT required). Returns whether the supplied `cardNumber` passes the Luhn checksum. Useful for client-side pre-flight validation before calling tokenisation.", "operationId": "MiddlewareCardsController_luhnAlgorithm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LuhnBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Luhn check result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LuhnResponseDto" } } } }, "400": { "description": "Missing or non-numeric `cardNumber`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [], "tags": [ "Cards" ] } }, "/middleware-cards/merchantCard": { "post": { "summary": "Tokenise merchant card", "description": "Same dispatch as `POST /` but stores the resulting token on the merchant client (not on a specific user). Used for merchant-of-record card storage and recurring billing-on-file scenarios.", "operationId": "MiddlewareCardsController_tokenizeMerchant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizeMerchantCardBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Merchant card tokenised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizeCardResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters). ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Client or processor configuration not found. ownCode in {5004, 5001}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Tokenisation upstream failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Cards" ] }, "get": { "summary": "List merchant cards", "description": "Returns the tokenised cards stored at the merchant level for the authenticated client.", "operationId": "MiddlewareCardsController_getListMerchantCards", "responses": { "200": { "description": "List of merchant cards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMerchantCardsResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Cards" ] } }, "/mw-cfg/webview": { "post": { "summary": "Get webview config", "description": "Resolves the hosted webview config for a Migo transaction. Loads `clientConfig` + `userConfig` + transaction state, applies redirect templates (Handlebars), and returns the rendered config + transaction snapshot the webview consumes. Requires `?trxUid=` as query parameter.", "operationId": "MiddlewareMwConfigsController_getWebview", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebviewConfigBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Hydrated webview config + transaction snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebviewConfigResponseDto" } } } }, "400": { "description": "Missing `trxUid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-cfg/processor": { "get": { "summary": "Get processor config", "description": "Returns the processor configuration document for the indicated `processor` query parameter. Used by the webview to render method-specific UI (challenges, accepted card brands).", "operationId": "MiddlewareMwConfigsController_getProcessor", "responses": { "200": { "description": "Processor config.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessorConfigResponseDto" } } } }, "400": { "description": "Missing or unknown `processor`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-cfg/redirect/{trxUid}": { "get": { "summary": "Get redirect channel for transaction", "description": "Computes the merchant redirect URL for the indicated transaction by compiling the configured channel template with the live transaction context. Used by webview close-flows.", "operationId": "MiddlewareMwConfigsController_getRedirectChannel", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Compiled redirect URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectChannelResponseDto" } } } }, "400": { "description": "Missing `trxUid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-cfg/processors/{slug}": { "put": { "summary": "Update processor for method", "description": "Updates the processor assigned to a given payment `method` for the merchant client identified by `{slug}`. Used by operations to swap providers without redeploying.", "operationId": "MiddlewareMwConfigsController_updateMethodPlatform", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMethodPlatformBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Processor updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MwConfigsGenericResponseDto" } } } }, "400": { "description": "Missing parameters or invalid platform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Client not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-cfg/user": { "post": { "summary": "Update user config", "description": "Persists user-level preferences (language, default currency, notifications) for the indicated user. Created on first call, merged on subsequent calls.", "operationId": "MiddlewareMwConfigsController_updateUserConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserConfigBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Preferences persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MwConfigsGenericResponseDto" } } } }, "400": { "description": "Missing parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-cfg/user/data": { "post": { "summary": "Capture user data on transaction", "description": "Persists arbitrary key/value data captured during checkout (billing, shipping, custom merchant fields) on the transaction `additionalData`. Used by the webview when extra fields are required by the merchant.", "operationId": "MiddlewareMwConfigsController_updateUserData", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDataBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Data captured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MwConfigsGenericResponseDto" } } } }, "400": { "description": "Missing `trxUid` or empty payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-cfg/user/data/{trxUid}": { "get": { "summary": "Get user data for transaction", "description": "Returns the user data previously captured for the indicated transaction. Mirror of `POST /user/data`.", "operationId": "MiddlewareMwConfigsController_getUserData", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Captured user data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserDataResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Config" ] } }, "/mw-default/auth/otp/generate": { "post": { "summary": "Generate OTP", "description": "Issues a one-time password to the end user via the configured `channel` (typically WhatsApp, SMS or email). The OTP is required by certain processors before charging — primarily as a soft-auth gate before captures or recurring charges.", "tags": [ "Auth" ], "operationId": "MiddlewareMwDefaultController_getOTP", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpGenerateBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "OTP issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpGenerateResponseDto" } } } }, "400": { "description": "Missing parameters. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Upstream OTP delivery failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/auth/otp/validate": { "post": { "summary": "Validate OTP", "description": "Verifies the OTP supplied by the end user against the value issued via `/auth/otp/generate`. On success returns a short-lived session token used to gate the subsequent payment call.", "tags": [ "Auth" ], "operationId": "MiddlewareMwDefaultController_validateOTP", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpValidateBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "OTP validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpValidateResponseDto" } } } }, "400": { "description": "Invalid OTP or expired window. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/processors/{clientSlug}": { "get": { "summary": "List processors enabled for client", "description": "Returns the catalogue of payment processors enabled for the given `clientSlug`, with display labels and per-processor metadata. Used by the webview to render the method picker.", "tags": [ "Config" ], "operationId": "MiddlewareMwDefaultController_getProcessors", "parameters": [ { "name": "clientSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of enabled processors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProcessorsResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Client config not found. ownCode `5004`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/lambda/execute": { "post": { "summary": "Execute internal Lambda", "description": "Cross-invokes an internal Lambda by logical name. The allow-list is resolved server-side from `clientCfg.lambdas` — clients cannot invoke arbitrary functions. Used for administrative/reporting workflows.", "tags": [ "Config" ], "operationId": "MiddlewareMwDefaultController_executeLambda", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteLambdaBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Target Lambda response forwarded verbatim.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteLambdaResponseDto" } } } }, "400": { "description": "Missing or unauthorised function name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Target Lambda invocation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/support/reprocess": { "post": { "summary": "Reprocess transaction", "description": "Re-runs the dispatch chain (`processTransaction`) for a transaction stuck in a non-terminal state. Used by support to recover transactions when the original processor request did not reach a final status.", "tags": [ "Transactions" ], "operationId": "MiddlewareMwDefaultController_reProcess", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReprocessBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Transaction re-processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MwDefaultGenericResponseDto" } } } }, "400": { "description": "Missing `trxUid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/application": { "post": { "summary": "Register merchant application", "description": "Creates a merchant application and returns the `publicKey`/`privateKey` credentials used for Payment Link authentication. The private key is delivered ONCE — store it securely.", "tags": [ "Auth" ], "operationId": "MiddlewareMwDefaultController_createApplication", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplicationBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Application created. Credentials returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplicationResponseDto" } } } }, "400": { "description": "Missing required fields. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Client config not found. ownCode `5004`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/preauthorize": { "post": { "summary": "Pre-authorise payment", "description": "Pre-authorises a transaction without immediate capture. Reuses the `paymentHandler.makePayment` runtime as `middleware-pay`’s `POST /` — body shape is identical. The downstream capture is performed via `POST /capture/{trxUid}` (token-authenticated) or `PATCH /capture-hook/{trxUid}` (processor webhook).", "tags": [ "Payments" ], "operationId": "MiddlewareMwDefaultController_preAuthorize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreauthorizeBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Authorisation captured (status `AUTHORIZED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MwDefaultGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, processor not allowed). ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction not eligible or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Schema validation failed (CHECK_PARAMETERS). ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/notifications/payments/{trxUid}": { "post": { "summary": "Outbound merchant notification webhook", "description": "Inbound endpoint that fans-out a payment notification for the indicated `trxUid` to the merchant’s registered callback URL. Payload is forwarded verbatim — Migo signs the outbound delivery with the merchant’s configured signing key.", "tags": [ "Webhooks" ], "operationId": "MiddlewareMwDefaultController_notificationsHook", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsHookBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Notification dispatched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MwDefaultGenericResponseDto" } } } }, "400": { "description": "Missing payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } } } }, "/mw-default/transactions-hook": { "post": { "summary": "Create Payment Link", "description": "Creates a Migo transaction from the merchant backend and returns the hosted webview URL that the merchant delivers to the end customer. Authentication is performed inside the handler using the privateKey and publicKey credentials of the registered merchant application.", "operationId": "MiddlewareMwDefaultController_createTransactionHook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionHookBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Transaction created and payment link issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionHookResponseDto" } } } }, "400": { "description": "Invalid amount, processorAmount or end-user blocked. ownCode in {2002, 2003, 2004, 2005, 2006}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Invalid privateKey/publicKey credentials. ownCode 2007.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Missing required parameters or client config not found. ownCode in {5000, 5004}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [], "tags": [ "Transactions" ] } }, "/mw-suspensions/delete": { "post": { "summary": "Delete Suspension", "description": "Removes a standing block or suspension for a user on a client. Excluded users cannot be unblocked through this endpoint.", "operationId": "MiddlewareMwSuspensionsController_deleteSuspension", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSuspensionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Suspension state after the delete attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSuspensionResponseDto" } } } }, "400": { "description": "Error while deleting the suspension", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Suspensions" ] } }, "/mw-suspensions/verify": { "get": { "summary": "Verify Suspension", "description": "Checks whether a user is currently suspended, blocked or excluded for a given client.", "operationId": "MiddlewareMwSuspensionsController_verifySuspension", "responses": { "200": { "description": "Current suspension state for the user/client pair", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifySuspensionResponseDto" } } } }, "400": { "description": "Error while verifying the suspension", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Suspensions" ] } }, "/mw-suspensions/blacklist": { "post": { "summary": "Add Users To Blacklist", "description": "Blocks one or more users for a given client. When forceBlock is true, users already in the whitelist are removed from it before being blocked.", "operationId": "MiddlewareMwSuspensionsController_addUserToBlacklist", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToBlacklistBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Users successfully added to the blacklist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToBlacklistResponseDto" } } } }, "400": { "description": "Error while adding users to the blacklist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Missing required params or no users blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToBlacklistResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Suspensions" ] } }, "/mw-suspensions/whitelist": { "post": { "summary": "Add Users To Whitelist", "description": "Adds one or more users to the whitelist for a given client, optionally creating the suspension rule structure when it does not yet exist.", "operationId": "MiddlewareMwSuspensionsController_addUserToWhitelist", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToWhitelistBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Users successfully added to the whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToWhitelistResponseDto" } } } }, "400": { "description": "Error while adding users to the whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Missing required params or no users added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserToWhitelistResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Suspensions" ] } }, "/mw-transactions": { "get": { "summary": "Get transaction by uid", "description": "Returns the stable summary for the indicated transaction. Requires `?uid=` (or equivalent identifier) as a query parameter.", "tags": [ "Transactions" ], "operationId": "MiddlewareMwTransactionsController_getTransactio", "responses": { "200": { "description": "Transaction summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTransactionResponseDto" } } } }, "400": { "description": "Missing identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "summary": "Create transaction", "description": "Creates a Migo transaction without issuing a Payment Link. Used by integrations that drive their own checkout UI rather than the hosted webview.", "tags": [ "Transactions" ], "operationId": "MiddlewareMwTransactionsController_createTransaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Transaction created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionResponseDto" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Client config not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] } }, "/mw-transactions/search": { "post": { "summary": "Search transactions", "description": "Paginated search across the merchant client transactions. Supports status, date range, user and free-form filter combinations. Returns total count + the requested page.", "operationId": "MiddlewareMwTransactionsController_searchTransactions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTransactionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTransactionResponseDto" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Transactions" ] }, "get": { "summary": "Search transactions (GET)", "description": "GET variant of `POST /search`. Filters are passed via query string. Returns a flat list (no pagination wrapper) — use the POST variant for paginated workflows.", "operationId": "MiddlewareMwTransactionsController_searchTransactionsGet", "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTransactionsGetResponseDto" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Transactions" ] } }, "/mw-transactions/searchs": { "post": { "summary": "Search transactions (legacy alias)", "description": "Legacy alias of `POST /search`. Kept for backwards compatibility with integrations that hit the misspelled path; new integrations should use `POST /search`.", "operationId": "MiddlewareMwTransactionsController_searchsTransactions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTransactionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTransactionResponseDto" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Transactions" ] } }, "/mw-transactions/download": { "post": { "summary": "Generate CSV transaction report", "description": "Queues a CSV export covering transactions in the requested window. The CSV is generated asynchronously and delivered to the supplied recipients via SES. Returns the queued job id.", "operationId": "MiddlewareMwTransactionsController_downloadCsvTrx", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadCsvBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "CSV job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadCsvResponseDto" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Transactions" ] } }, "/mw-transactions/details": { "get": { "summary": "Get transaction details with step history", "description": "Returns the transaction summary plus the MongoDB step history and processor metadata snapshot. Used by support / dashboard tooling to debug specific charges.", "operationId": "MiddlewareMwTransactionsController_getTransactionDetails", "responses": { "200": { "description": "Transaction details + steps + metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTransactionDetailsResponseDto" } } } }, "400": { "description": "Missing identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Transactions" ] } }, "/mw-transactions/createdby": { "get": { "summary": "List transactions by user / creator", "description": "Lists transactions filtered by `userId` and/or `createdBy`. Useful for support/operator views that need a per-user activity log.", "operationId": "MiddlewareMwTransactionsController_getTransactionsByUserIdCreatedBy", "responses": { "200": { "description": "Filtered transaction list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTransactionsByUserIdCreatedByResponseDto" } } } }, "400": { "description": "Missing query filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Transactions" ] } }, "/middleware-pay": { "post": { "summary": "Process card payment", "description": "Charges a previously-created transaction against the selected processor. The handler validates the transaction status (`CREATED`/`USED`/`CHALLENGE`-only), ensures the user is not blocked, dispatches to the processor library via `makePaymentMethods[processor]`, and persists the final `APPROVED`/`DENIED`/`AUTHORIZED`/`PENDING` state. Card data may be supplied either inline via `cardInfo` or as an encrypted token via the `additionalData.encrypt` query parameter.", "tags": [ "Payments" ], "operationId": "MiddlewarePayController_makePayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MakePaymentBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Payment processed. Response carries the resolved transaction summary (status + processor payload).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MakePaymentResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "409": { "description": "Schema validation failed (e.g. CHECK_PARAMETERS). ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] }, "get": { "summary": "Get payment status", "description": "Returns the current status and processor payload for a Migo transaction. Used by webview pollers and merchant backends to reconcile asynchronous flows when the inbound webhook is not yet trusted.", "tags": [ "Payments" ], "operationId": "MiddlewarePayController_paymentStatus", "parameters": [ { "in": "query", "name": "trxUid", "description": "Migo transaction uid.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Missing `trxUid`. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] } }, "/middleware-pay/challenge": { "post": { "summary": "Submit 3DS challenge response", "description": "Second step in the 3DS flow for processors that require an interim challenge before finalising the charge. Currently dispatched for `visa-cybersource` and `visa-epay` via `paymentSecondStepMethods`. The merchant collects the `paRes`/`accessToken` from the issuer redirect and forwards it here.", "operationId": "MiddlewarePayController_paymentSecondStep", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Challenge accepted; transaction advances to confirm step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/confirm": { "post": { "summary": "Confirm 3DS authentication", "description": "Final 3DS step. Receives the issuer-signed authentication artifacts (`paRes`/`md`/`cres` depending on processor and 3DS version) and resolves the transaction to its terminal status. Dispatched via `payment3DSConfirmMethods` (`visa-epay`, `visa-cybersource`, `serfinsa`).", "operationId": "MiddlewarePayController_payment3DSConfirm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment3DSConfirmBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "3DS confirmed. Returns the final transaction summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/revert": { "post": { "summary": "Revert (void) transaction", "description": "Reverses a transaction prior to settlement. Dispatched via `paymentRevertMethods` — only the processors that expose a void path support it (full list in `paymentHandler.methods.ts`). For partial reverts include `amount`; otherwise the full transaction is voided.", "operationId": "MiddlewarePayController_paymentRevert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRevertBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Transaction reverted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Processor does not support voids/reverts. ownCode `2008`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/refund": { "post": { "summary": "Refund settled transaction", "description": "Issues a refund against a settled transaction. Dispatched via `paymentRefundMethods`. Supports partial refunds when `amount` is supplied; otherwise the remaining balance is refunded. Refund attempts respect `clientCfg.suspensionRules.revert` thresholds.", "operationId": "MiddlewarePayController_paymentRefund", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRefundBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Refund issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Processor does not support refunds or transaction is not refundable. ownCode `2008`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/hook/{processor}": { "post": { "summary": "Inbound processor webhook", "description": "Routes an inbound webhook from the upstream processor identified by the `{processor}` path parameter. Migo reads `processorCfg.methods.hook.functionName` from MongoDB and invokes the processor-specific Lambda with the payload — the schema is processor-defined. Used today by `wompi`, `paymentez`, `mercadoPago`, `azul`, etc. — see the `paymentHandler.methods.ts` dispatch maps for the canonical list.", "operationId": "MiddlewarePayController_paymentHook", "parameters": [ { "name": "processor", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentHookBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Webhook acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Invalid payload for the indicated processor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Processor configuration missing for `{processor}`. ownCode `2009`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [], "tags": [ "Webhooks" ] } }, "/middleware-pay/capture-hook/{trxUid}": { "patch": { "summary": "Inbound capture hook", "description": "Webhook variant of capture. Triggered by the processor when an authorisation is settled — Migo updates the local transaction to `CAPTURED`. Dispatched via `capturePaymentMethods`.", "operationId": "MiddlewarePayController_capturePayment", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureHookBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Capture acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [], "tags": [ "Webhooks" ] } }, "/middleware-pay/cancel-hook/{trxUid}": { "patch": { "summary": "Inbound cancel-capture hook", "description": "Webhook variant of cancel-capture. Triggered by the processor when an authorisation is cancelled before settlement. Dispatched via `cancelCaptureMethods`.", "operationId": "MiddlewarePayController_cancelCapturePayment", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureHookBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Cancel-capture acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [], "tags": [ "Webhooks" ] } }, "/middleware-pay/capture/{trxUid}": { "post": { "summary": "Capture authorised payment", "description": "Token-authenticated capture for two-step (authorise → capture) flows. Same dispatch as `/capture-hook/{trxUid}` but called by the merchant backend with a JWT instead of by the processor. Supports partial captures via `amount`.", "operationId": "MiddlewarePayController_capturePaymentToken", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapturePaymentTokenBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Captured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Processor does not allow captures. ownCode `2008`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/cancel/{trxUid}": { "post": { "summary": "Cancel authorised payment", "description": "Token-authenticated cancel-capture. Voids an outstanding authorisation prior to settlement. Dispatched via `cancelCapturePaymentTokenMethods`.", "operationId": "MiddlewarePayController_cancelCapturePaymentToken", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelCapturePaymentTokenBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Authorisation cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] }, "delete": { "summary": "Cancel pending payment request", "description": "Cancels an in-flight payment request (used by Zigi via `cancelPaymentRequestMethods`). Distinct from `POST /cancel/{trxUid}` which voids settled authorisations.", "operationId": "MiddlewarePayController_cancelPaymentRequest", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pending payment cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/verify": { "patch": { "summary": "Verify processor-side status", "description": "Re-queries the upstream processor for the canonical status of a transaction. Currently used for `paymentez` via `verifyPaymentMethods`. Useful when the inbound webhook is delayed or lost.", "operationId": "MiddlewarePayController_verifyPayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPaymentBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Latest processor-side status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/{trxUid}/checks": { "get": { "summary": "Validate cash payment reference", "description": "Checks whether a cash payment reference (Pronet) is still valid and confirmable. Returns processor-specific metadata (limit date, voucher reference).", "operationId": "MiddlewarePayController_paymentCashValidation", "parameters": [ { "name": "trxUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cash reference validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCashValidationResponseDto" } } } }, "400": { "description": "Missing `trxUid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/confirmations": { "post": { "summary": "Confirm cash payment", "description": "Marks a cash transaction as paid once the customer presents the voucher at the convenience store. Dispatched via `paymentCashMethods` (currently `pronet`).", "operationId": "MiddlewarePayController_paymentCashConfirm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCashConfirmBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Cash payment confirmed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/middleware-pay/verifyExternalPayments": { "post": { "summary": "Verify external (Davivienda) payment", "description": "Validates a payment processed outside the Migo flow (currently `davivienda`) using customer document data. Returns the upstream processor result for reconciliation.", "operationId": "MiddlewarePayController_verifyExternalPayments", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyExternalPaymentsBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "External payment verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayGenericResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters, schema mismatch, processor not allowed for client). ownCode in {5000, 2003}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authorizer rejected the JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Transaction in non-eligible state or end-user blocked. ownCode in {2004, 2005, 2006, 2007}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Payments" ] } }, "/api/v1/integrations/transactions/{transactionId}/dismiss": { "post": { "summary": "Dismiss alternative transaction", "description": "Cancels an alternative-payment transaction. Idempotent for `CREATED`/`USED` states (sets `DISMISSED`); for `IN_PROGRESS` it triggers the processor-side cancel hook (when supported) and resolves to `CANCELLED`.", "operationId": "MiddlewareTransactionsController_dismissTransaction", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissTransactionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Transaction dismissed (returns `OK` plain text for state transitions to `DISMISSED`, or a structured payload when a processor cancel hook ran).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissTransactionResponseDto" } } } }, "400": { "description": "Missing `trxUid` path parameter. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Transaction not found. ownCode `2001`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Processor does not allow dismissing transactions. ownCode `2008`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor configuration missing or upstream cancel call failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Alternative Payments" ] } }, "/api/v1/integrations/transactions": { "post": { "summary": "Create alternative payment transaction", "description": "Creates a transaction for asynchronous (non-card) payment methods. Validates the `client` against `clientConfig`, ensures the `amount` is within the merchant min/max and returns the list of allowed alternative payment methods plus the seconds remaining until the transaction expires.", "tags": [ "Alternative Payments" ], "operationId": "MiddlewareTransactionsController_createTransaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlternativeTransactionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Transaction created and ready to be paid via one of the returned `paymentMethods`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlternativeTransactionResponseDto" } } } }, "400": { "description": "Validation failed (missing parameters or amount out of range). ownCode `5000`/`2003`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Client config missing or transaction could not be persisted. ownCode `5004`/`2002`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/v1/integrations/transactions/{transactionId}/payments": { "post": { "summary": "Process alternative payment", "description": "Initiates the alternative payment flow against the selected `processor` (which must be present in the `paymentMethods` array returned at creation time). The response shape varies per processor: redirect URLs (Zigi, BAM Payment Button), HTML forms (PSE), QR strings (BBVA QR, Banco Industrial), JSON references (Pronet) or pay-button payloads (Nequi).", "operationId": "MiddlewareTransactionsController_payments", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativePaymentBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Payment initiated. The `data.type` field indicates how the merchant should consume `data.data` (`url`, `qr`, `html`, `json`, `payButton`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativePaymentResponseDto" } } } }, "400": { "description": "Missing parameters, processor not allowed for this client, or required processor payload incomplete. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Authentication failed for processors that require user-side validation (e.g. Ridivi). ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Processor not currently available (e.g. Banco Industrial returned an unavailability reason).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Processor request could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Alternative Payments" ] } }, "/api/v1/integrations/transactions/{transactionId}/payment-intents": { "post": { "summary": "Get alternative payment intent metadata", "description": "Returns processor-specific metadata required to render a payment intent UI before the user commits to a method. Used today by `globalPay-PSE` (returns banks, account types, FIS types, user types), `nequi` (returns required phone fixture) and `fri` (returns user fixture).", "operationId": "MiddlewareTransactionsController_paymentIntents", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentsBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Intent metadata for the requested processor. Shape depends on the processor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentsResponseDto" } } } }, "400": { "description": "Missing `trxUid` or processor not enabled for this client. ownCode `5000`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Upstream processor lookup failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Alternative Payments" ] } }, "/middleware-verifications/bin": { "post": { "summary": "Verify BIN Against Coppel", "description": "Calls the Coppel service to check whether a card BIN is linked to a phone number, used for credit pre-authorization. CORS-only — does not require an authentication token.", "operationId": "MiddlewareVerificationsController_verifyBIN", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyBinBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Successful Coppel response for the requested BIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyBinResponseDto" } } } }, "500": { "description": "Internal error while calling Coppel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [], "tags": [ "Verifications" ] } }, "/v1/plans": { "post": { "summary": "Create Plan", "description": "Creates a subscription plan for a client. The plan is persisted in MongoDB (ClientConfig.plans) and MySQL (Plan).", "operationId": "SubscriptionsPlanController_createPlan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Plans" ] }, "put": { "summary": "Update Plan", "description": "Updates an existing plan for a client (name, amount, frequency, etc.).", "operationId": "SubscriptionsPlanController_updatePlan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Plan updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/plans/list": { "get": { "summary": "List Plans For Client", "description": "Returns every plan configured for the given client.", "operationId": "SubscriptionsPlanController_getPlans", "responses": { "200": { "description": "Plans for the client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPlansResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Plans" ] } }, "/v1/plans/{planId}/client/{client}/detail": { "get": { "summary": "Get Plan Detail", "description": "Returns plan details plus the next scheduled payment date (timezone-aware).", "operationId": "SubscriptionsPlanController_getPlanById", "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Plan detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPlanByIdResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Plans" ] } }, "/v1/subscriptions": { "get": { "summary": "List Subscriptions By User", "description": "Returns every active subscription a user has with the given client, including a webview deep link per subscription.", "operationId": "SubscriptionsSubscriptionController_subscriptionsByUser", "responses": { "200": { "description": "Subscriptions found for the user/client pair", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSubscriptionsResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] }, "put": { "summary": "Update Subscription", "description": "Updates subscription-level details such as the notification email.", "operationId": "SubscriptionsSubscriptionController_updateSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMessageDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/{subUid}": { "delete": { "summary": "Cancel Subscription", "description": "Cancels an active subscription and triggers the cancellation notification.", "operationId": "SubscriptionsSubscriptionController_cancelSubscription", "parameters": [ { "name": "subUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/detail/{subUid}": { "get": { "summary": "Get Subscription Detail", "description": "Returns the subscription plus its plan, cards, webview config and current balance.", "operationId": "SubscriptionsSubscriptionController_getSubscription", "parameters": [ { "name": "subUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetailResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/payment-methods": { "post": { "summary": "Add Payment Method", "description": "Persists a tokenized card as a payment method for a user/client and sends a confirmation email.", "operationId": "SubscriptionsSubscriptionController_addPaymentMethod", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPaymentMethodBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "201": { "description": "Payment method created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPaymentMethodResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] }, "delete": { "summary": "Delete Payment Method", "description": "Removes a non-default card from a subscription. The default payment method cannot be deleted.", "operationId": "SubscriptionsSubscriptionController_deletePaymentMethod", "responses": { "200": { "description": "Payment method deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePaymentMethodResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/verify-card": { "post": { "summary": "Verify Card", "description": "Tokenizes and pre-authorizes a card for a subscription. Supports 3DS challenge flows and optionally creates the subscription inline when shouldCreateSubscription is true.", "operationId": "SubscriptionsSubscriptionController_verifyCard", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCardBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Verification completed or challenge returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCardResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/payment-methods/set-default": { "put": { "summary": "Set Default Payment Method", "description": "Replaces a subscription's default payment method with an already-registered card.", "operationId": "SubscriptionsSubscriptionController_setPaymentMethod", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPaymentMethodBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "200": { "description": "Default payment method updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPaymentMethodResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/payment-history": { "get": { "summary": "Get Payment History", "description": "Returns the payment history for a subscription, enriched with card details per charge.", "operationId": "SubscriptionsSubscriptionController_paymentHistory", "responses": { "200": { "description": "Payment history for the subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentHistoryResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/charges": { "post": { "summary": "Intake Subscription Charges", "description": "Accepts a batch of up to 5000 charge items for a client. Idempotent by SHA256 of the payload.", "operationId": "SubscriptionsSubscriptionController_intakeSubscriptionCharges", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscriptionChargesBodyDto" } } }, "description": "Body required in the request", "required": true }, "responses": { "202": { "description": "Batch accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeSubscriptionChargesResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } }, "/v1/subscriptions/charges/upload-csv": { "post": { "summary": "Upload Charge Submissions CSV", "description": "Uploads a CSV file of charge submissions (multipart/form-data).", "operationId": "SubscriptionsSubscriptionController_uploadChargeSubmissionsCsv", "responses": { "200": { "description": "CSV accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadChargeCsvResponseDto" } } } }, "400": { "description": "Validation or business-rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Subscriptions" ] } } }, "components": { "schemas": { "MigoErrorDetailsDto": { "properties": { "code": { "description": "HTTP status code associated with the error.", "type": "number", "example": 404 }, "ownCode": { "description": "Internal Migo error code (from the MigoErrors table).", "type": "string", "example": "2000" }, "message": { "description": "Human-readable error description.", "type": "string", "example": "Transaction not found" } }, "additionalProperties": false, "title": "MigoErrorDetailsDto", "type": "object" }, "ErrorResponseDto": { "properties": { "message": { "description": "High-level error message.", "type": "string", "example": "Internal Server Error" }, "error": { "$ref": "#/components/schemas/MigoErrorDetailsDto" } }, "additionalProperties": false, "title": "ErrorResponseDto", "type": "object" }, "MwCardSummaryDto": { "properties": { "cardId": { "description": "Card identifier (Migo-side or processor token, depending on dispatch).", "type": "string", "example": "card_8f3c2b1d9e7a" }, "brand": { "description": "Card brand inferred from the BIN.", "type": "string", "example": "VISA" }, "last4": { "description": "Last 4 digits of the PAN.", "type": "string", "example": "4242" }, "expirationDate": { "description": "Card expiration in `MM/YY` format.", "type": "string", "example": "12/29" }, "alias": { "description": "Optional alias the merchant attached to the card.", "type": "string", "example": "Personal Visa" }, "processor": { "description": "Processor that owns the underlying token.", "type": "string", "example": "fac-2" } }, "additionalProperties": false, "title": "MwCardSummaryDto", "description": "DTOs for the `middleware-cards` stack (7 endpoints).\n\nThe runtime handlers in `cardHandler.ts` accept processor-specific card\npayloads under `body.card` / `body.cardInfo`. The DTOs below model the\nstable envelope (transaction reference, processor name, common card fields)\nand treat processor-specific extras as `Record` so the\nOpenAPI surface stays accurate without overpromising shape.", "type": "object" }, "TokenizeCardBodyDto": { "properties": { "processor": { "description": "Processor key. Must be present in the `tokenizeMethods` dispatch\n(`fac`, `fac-2`, `visa-cybersource`, `visa-epay`, `mercadoPago`, `azul`,\n`serfinsa`, `t1pagos`, `paymentez`, `globalPay`, `push-payment-gateway`).", "type": "string", "example": "fac-2" }, "uid": { "description": "Migo transaction uid. Either `uid` or `transactionUid` is accepted —\nthe handler normalises them.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "transactionUid": { "description": "Alias of `uid` (kept for backwards compatibility with older integrations).", "type": "string" }, "card": { "description": "Card data (PAN, holder, expiration, CVV). Required keys depend on the\nprocessor; the handler forwards the payload to `tokenizeMethods[processor]`." }, "billTo": { "description": "Optional billing address required by AVS-enabled processors." }, "customKeys": { "description": "Free-form extras forwarded to the processor token endpoint." } }, "required": [ "processor" ], "additionalProperties": false, "title": "TokenizeCardBodyDto", "type": "object" }, "TokenizeCardResponseDto": { "properties": { "success": { "description": "Whether the tokenisation succeeded.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "Card tokenised" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/MwCardSummaryDto" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "TokenizeCardResponseDto", "type": "object" }, "GetCardsResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "OK" }, "data": { "items": { "$ref": "#/components/schemas/MwCardSummaryDto" }, "type": "array" } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetCardsResponseDto", "type": "object" }, "UpdateCardBodyDto": { "properties": { "cardId": { "description": "Card identifier to update.", "type": "string", "example": "card_8f3c2b1d9e7a" }, "alias": { "description": "Optional new alias.", "type": "string", "example": "Work Mastercard" }, "isDefault": { "description": "Optional flag to mark this card as the user's default for charges.", "type": "boolean", "example": true } }, "required": [ "cardId" ], "additionalProperties": false, "title": "UpdateCardBodyDto", "type": "object" }, "DeleteCardBodyDto": { "properties": { "cardId": { "description": "Card identifier to remove.", "type": "string", "example": "card_8f3c2b1d9e7a" } }, "required": [ "cardId" ], "additionalProperties": false, "title": "DeleteCardBodyDto", "type": "object" }, "LuhnBodyDto": { "properties": { "cardNumber": { "description": "Primary account number to validate. Returns `valid: true` if the PAN\npasses the Luhn checksum.", "type": "string", "example": "4111111111111111" } }, "required": [ "cardNumber" ], "additionalProperties": false, "title": "LuhnBodyDto", "type": "object" }, "LuhnResponseDto": { "properties": { "valid": { "description": "Whether the PAN passed the Luhn checksum.", "type": "boolean", "example": true } }, "required": [ "valid" ], "additionalProperties": false, "title": "LuhnResponseDto", "type": "object" }, "TokenizeMerchantCardBodyDto": { "properties": { "processor": { "description": "Processor key. Must be present in `tokenizeMethods`.", "type": "string", "example": "fac-2" }, "client": { "description": "Merchant client slug under which the card is stored.", "type": "string", "example": "cobasy" }, "card": { "description": "Card payload (same schema as `tokenize`)." }, "customKeys": { "description": "Free-form metadata persisted alongside the merchant card." } }, "required": [ "processor", "client" ], "additionalProperties": false, "title": "TokenizeMerchantCardBodyDto", "type": "object" }, "GetMerchantCardsResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean" }, "message": { "description": "Human-readable status message.", "type": "string" }, "data": { "items": { "$ref": "#/components/schemas/MwCardSummaryDto" }, "type": "array" } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetMerchantCardsResponseDto", "type": "object" }, "CardsGenericResponseDto": { "properties": { "success": { "description": "Whether the operation completed successfully.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "OK" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/MwCardSummaryDto" }, { "items": { "$ref": "#/components/schemas/MwCardSummaryDto" }, "type": "array" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "CardsGenericResponseDto", "type": "object" }, "WebviewConfigBodyDto": { "properties": { "device": { "description": "Optional device fingerprint forwarded by the webview client. Persisted on\nthe transaction `additionalData` for fraud / fingerprinting use." } }, "additionalProperties": false, "title": "WebviewConfigBodyDto", "description": "DTOs for the `mw-cfg` (`middleware-mwConfigs`) stack — 7 endpoints that\npower the hosted webview lifecycle and the merchant-facing user/processor\nconfiguration helpers.\n\nThe DTOs model the stable envelope the handlers consume; processor- and\nclient-specific shapes (webview redirect maps, processor `extras`) are\nsurfaced as `Record` so the OpenAPI contract stays accurate\nwithout freezing internal config schemas.", "type": "object" }, "WebviewConfigResponseDto": { "properties": { "success": { "description": "Whether the webview config could be assembled.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "properties": { "config": { "description": "Hydrated webview config: redirects, processors, branding, feature flags.\nShape is client-driven (resolved from MongoDB `clientConfig`)." }, "transaction": { "description": "Resolved transaction snapshot (status, amount, processor metadata)." } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "WebviewConfigResponseDto", "type": "object" }, "ProcessorConfigResponseDto": { "properties": { "success": { "description": "Whether the processor config could be resolved.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "properties": { "name": { "description": "Processor key.", "type": "string", "example": "fac-2" }, "extras": { "description": "Free-form processor configuration (request templates, secrets-by-ref,\nfallback methods)." } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "ProcessorConfigResponseDto", "type": "object" }, "RedirectChannelResponseDto": { "properties": { "success": { "description": "Whether the redirect channel could be resolved.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "properties": { "channel": { "description": "Channel slug routed back to the merchant.", "type": "string", "example": "wa" }, "redirect": { "description": "Compiled redirect URL with template tokens replaced by transaction data.", "type": "string", "example": "https://merchant.example.com/return?uid=trx_8f3c" } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "RedirectChannelResponseDto", "type": "object" }, "UpdateMethodPlatformBodyDto": { "properties": { "method": { "description": "Method key being updated (`pay`, `tokenize`, `refund`, etc.).", "type": "string", "example": "pay" }, "platform": { "description": "Platform/processor identifier replacing the current one.", "type": "string", "example": "fac-2" }, "extras": { "description": "Optional extras forwarded to the persistence layer (fee splits, currency\noverrides). Schema is client-defined." } }, "required": [ "method", "platform" ], "additionalProperties": false, "title": "UpdateMethodPlatformBodyDto", "type": "object" }, "UserConfigBodyDto": { "properties": { "userId": { "description": "End-user identifier the config belongs to.", "type": "string", "example": "+50212345678" }, "client": { "description": "Merchant client slug.", "type": "string", "example": "cobasy" }, "preferences": { "description": "Free-form preferences merged into the user config document. Common keys:\n`language`, `defaultCurrency`, `notifications`." } }, "required": [ "userId", "client" ], "additionalProperties": false, "title": "UserConfigBodyDto", "type": "object" }, "UserDataBodyDto": { "properties": { "trxUid": { "description": "Migo transaction uid the user data is captured during.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "data": { "description": "Free-form key/value bag captured by the webview during checkout (billing\ninfo, shipping info, custom fields). Persisted on the transaction\n`additionalData`." } }, "required": [ "trxUid", "data" ], "additionalProperties": false, "title": "UserDataBodyDto", "type": "object" }, "GetUserDataResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean" }, "message": { "description": "Status message.", "type": "string" }, "data": { "description": "Stored user data captured during checkout. Shape is merchant-defined.", "nullable": true } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetUserDataResponseDto", "type": "object" }, "MwConfigsGenericResponseDto": { "properties": { "success": { "description": "Whether the operation completed successfully.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string" }, "data": { "nullable": true } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "MwConfigsGenericResponseDto", "type": "object" }, "CreateTransactionHookBodyDto": { "properties": { "amount": { "description": "Transaction subtotal in the smallest currency unit allowed by the client (typically integer).", "type": "number", "example": 1 }, "userId": { "description": "Identifier of the end customer in the merchant's domain (phone, email, internal id).", "type": "string", "example": "50224865444" }, "channel": { "description": "Communication channel used to deliver the payment link to the end customer (e.g. wa, app, sms, email, web).", "type": "string", "example": "app" }, "client": { "description": "Client slug registered in Migo configuration.", "type": "string", "example": "your-client-slug" }, "privateKey": { "description": "Private credential of the merchant application. Combined with publicKey to authenticate the request.", "type": "string", "example": "your-private-key" }, "publicKey": { "description": "Public credential of the merchant application. Combined with privateKey to authenticate the request.", "type": "string", "example": "your-public-key" }, "currency": { "description": "Optional currency ISO 4217 code. If omitted, or if not in the list of currencies allowed for the client, the first allowed currency for the client is used.", "type": "string", "example": "GTQ" }, "processorAmount": { "description": "Optional per-processor amount overrides. Each value must be less than or equal to amount." }, "customKeys": { "description": "Custom merchant data preserved verbatim and made available to webview templates and callbacks." }, "externalId": { "description": "Optional external identifier used by the merchant to correlate the Migo transaction with their own record.", "type": "string", "example": "ORDER-12345" }, "createdBy": { "description": "Optional identifier of the operator that created the transaction (surfaced in Migo dashboards).", "type": "string", "example": "operator@example.com" }, "customerId": { "description": "Optional internal identifier used to associate the transaction with a customer record.", "type": "string", "example": "CUSTOMER-001" }, "subscriptionData": { "description": "Optional subscription metadata." } }, "required": [ "amount", "userId", "channel", "client", "privateKey", "publicKey" ], "additionalProperties": false, "title": "CreateTransactionHookBodyDto", "description": "Body of a Payment Link creation request authenticated with the merchant\napplication's privateKey + publicKey credentials.", "type": "object" }, "CreateTransactionHookResponseDto": { "properties": { "uid": { "description": "Unique transaction identifier in Migo.", "type": "string", "example": "7JV3UKvc2XEretWV2Rb57" }, "URL": { "description": "Hosted webview URL the merchant delivers to the end customer to complete payment.\nNote: the property name is uppercase as emitted by the handler.", "type": "string", "example": "https://sandbox.migopayments.com/?orderId=7JV3UKvc2XEretWV2Rb57" } }, "required": [ "uid", "URL" ], "additionalProperties": false, "title": "CreateTransactionHookResponseDto", "description": "Response of a successful Payment Link creation: the unique transaction\nidentifier and the hosted webview URL the merchant delivers to the end\ncustomer.", "type": "object" }, "OtpGenerateBodyDto": { "properties": { "userId": { "description": "End-user identifier the OTP is delivered to (phone or email).", "type": "string", "example": "+50212345678" }, "client": { "description": "Merchant client slug.", "type": "string", "example": "cobasy" }, "channel": { "description": "Communication channel that triggered the OTP request (`wa`, `web`, `sms`, `email`).", "type": "string", "example": "wa" }, "trxUid": { "description": "Optional Migo transaction uid to associate the OTP with a specific charge.", "type": "string", "example": "trx_8f3c2b1d9e7a" } }, "required": [ "userId", "client" ], "additionalProperties": false, "title": "OtpGenerateBodyDto", "type": "object" }, "OtpGenerateResponseDto": { "properties": { "success": { "description": "Whether the OTP was issued.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string", "example": "OTP sent" }, "data": { "anyOf": [ { "properties": { "expiresIn": { "description": "Seconds until the OTP expires.", "type": "number", "example": 300 }, "deliveredVia": { "description": "Channel the OTP was actually delivered through.", "type": "string", "example": "wa" } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "OtpGenerateResponseDto", "type": "object" }, "OtpValidateBodyDto": { "properties": { "userId": { "description": "End-user identifier (must match the one used for generation).", "type": "string", "example": "+50212345678" }, "client": { "description": "Merchant client slug.", "type": "string", "example": "cobasy" }, "otp": { "description": "One-time password supplied by the end user.", "type": "string", "example": "493210" }, "trxUid": { "description": "Optional Migo transaction uid the OTP is associated with.", "type": "string" } }, "required": [ "userId", "client", "otp" ], "additionalProperties": false, "title": "OtpValidateBodyDto", "type": "object" }, "OtpValidateResponseDto": { "properties": { "success": { "description": "Whether the OTP matched and is still within the validity window.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string", "example": "OTP validated" }, "data": { "anyOf": [ { "properties": { "sessionToken": { "description": "Short-lived session token granted upon successful validation.", "type": "string", "example": "sess_abcd1234" } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "OtpValidateResponseDto", "type": "object" }, "GetProcessorsResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "items": { "properties": { "name": { "description": "Processor key (e.g. `fac-2`, `wompi-pse`).", "type": "string", "example": "fac-2" }, "label": { "description": "Display label.", "type": "string", "example": "First Atlantic" }, "enabled": { "description": "Whether this processor is currently enabled for the client.", "type": "boolean", "example": true }, "extras": { "description": "Free-form processor metadata (allowed methods, currencies, etc.)." } }, "required": [ "name" ], "additionalProperties": false, "type": "object" }, "type": "array" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetProcessorsResponseDto", "type": "object" }, "ExecuteLambdaBodyDto": { "properties": { "functionName": { "description": "Lambda function name (logical) to execute. Must be present in the allow-list\nresolved server-side from `clientCfg`.", "type": "string", "example": "report-daily-balances" }, "payload": { "description": "Free-form payload forwarded to the target Lambda. Schema is owned by the\ntarget Lambda — Migo does not validate beyond the allow-list check." } }, "required": [ "functionName" ], "additionalProperties": false, "title": "ExecuteLambdaBodyDto", "type": "object" }, "ExecuteLambdaResponseDto": { "properties": { "success": { "description": "Whether the cross-Lambda invocation succeeded.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "description": "Whatever the target Lambda returned. Shape is target-defined." } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "ExecuteLambdaResponseDto", "type": "object" }, "ReprocessBodyDto": { "properties": { "trxUid": { "description": "Migo transaction uid to re-process. The handler re-runs the dispatch chain\nfrom `processTransaction()` against the recorded processor.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "reason": { "description": "Optional reason captured for audit/observability.", "type": "string", "example": "support_ticket_4912" } }, "required": [ "trxUid" ], "additionalProperties": false, "title": "ReprocessBodyDto", "type": "object" }, "CreateApplicationBodyDto": { "properties": { "client": { "description": "Merchant client slug the application is registered under.", "type": "string", "example": "cobasy" }, "name": { "description": "Free-form merchant-side label used in dashboards.", "type": "string", "example": "Cobasy iOS app" }, "email": { "description": "Optional contact email associated with the application credentials.", "type": "string", "example": "ops@cobasy.com" }, "metadata": { "description": "Free-form metadata persisted with the application record." } }, "required": [ "client" ], "additionalProperties": false, "title": "CreateApplicationBodyDto", "type": "object" }, "CreateApplicationResponseDto": { "properties": { "success": { "description": "Whether the application was created.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "properties": { "publicKey": { "description": "Public credential to be paired with `privateKey` for Payment Link auth.", "type": "string", "example": "pub_abcd1234" }, "privateKey": { "description": "Private credential — DELIVERED ONCE. Treat as a secret.", "type": "string", "example": "priv_efgh5678" } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "CreateApplicationResponseDto", "type": "object" }, "PreauthorizeBodyDto": { "properties": { "transactionUid": { "description": "Migo transaction uid created previously via `POST /transactions-hook`.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "processor": { "description": "Processor key.", "type": "string", "example": "fac-2" }, "installments": { "description": "Number of installments.", "type": "number", "example": 1 }, "cardInfo": { "description": "Card data (PAN, holder, expiration, CVV) — required when `additionalData.encrypt`\nis not used." }, "billTo": { "description": "Optional billing address." }, "customKeys": { "description": "Free-form metadata." } }, "required": [ "transactionUid", "processor", "installments" ], "additionalProperties": false, "title": "PreauthorizeBodyDto", "description": "Pre-authorize uses the same handler as `middleware-pay`'s `POST /` (makePayment)\nbut is a separate deployment for the `/preauthorize` path. The request shape is\nidentical to `MakePaymentBodyDto` — see the `middleware-pay` stack for the full\nmodel.", "type": "object" }, "NotificationsHookBodyDto": { "additionalProperties": {}, "title": "NotificationsHookBodyDto", "type": "object" }, "MwDefaultGenericResponseDto": { "properties": { "success": { "description": "Whether the operation completed successfully.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string" }, "data": { "nullable": true } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "MwDefaultGenericResponseDto", "type": "object" }, "SuspensionResult": { "enum": [ "noblocked", "blocked", "suspended", "excluded" ], "title": "SuspensionResult", "type": "string" }, "SuspensionRulesDto": { "properties": { "max": { "description": "Maximum allowed denied transactions in the time window.", "type": "number", "example": 3 }, "time": { "description": "Time window in hours.", "type": "number", "example": 24 }, "rules": { "properties": { "approved": { "description": "Behaviour when the threshold is reached on approved transactions.", "type": "string", "example": "suspend" }, "denied": { "description": "Behaviour when the threshold is reached on denied transactions.", "type": "string", "example": "block" } }, "required": [ "approved", "denied" ], "additionalProperties": false, "type": "object" } }, "required": [ "max", "time", "rules" ], "additionalProperties": false, "title": "SuspensionRulesDto", "type": "object" }, "DeleteSuspensionBodyDto": { "properties": { "userId": { "description": "External user identifier (phone, email or any client-issued id).", "type": "string", "example": "+50212345678" }, "clientName": { "description": "Client slug whose suspension is being removed.", "type": "string", "example": "cobasy" } }, "required": [ "userId", "clientName" ], "additionalProperties": false, "title": "DeleteSuspensionBodyDto", "type": "object" }, "DeleteSuspensionResponseDto": { "properties": { "result": { "anyOf": [ { "$ref": "#/components/schemas/SuspensionResult" }, { "type": "string" } ], "description": "Outcome returned by the suspension service.", "example": "noblocked" }, "message": { "description": "Optional detail message when the user was not suspended or blocked.", "type": "string", "example": "User is not suspended or blocked" }, "status": { "type": "boolean" } }, "required": [ "result" ], "additionalProperties": false, "title": "DeleteSuspensionResponseDto", "type": "object" }, "VerifySuspensionQueryDto": { "properties": { "userId": { "description": "External user identifier.", "type": "string", "example": "+50212345678" }, "clientName": { "description": "Client slug whose suspension status is being checked.", "type": "string", "example": "cobasy" }, "origin": { "description": "Origin channel that triggered the check.", "type": "string", "example": "wa" } }, "required": [ "userId", "clientName" ], "additionalProperties": false, "title": "VerifySuspensionQueryDto", "type": "object" }, "VerifySuspensionResponseDto": { "properties": { "status": { "description": "True when the user is currently suspended or blocked.", "type": "boolean", "example": false }, "message": { "description": "Human-readable explanation of the current state.", "type": "string", "example": "User is not suspended or blocked" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/SuspensionResult" }, { "type": "string" } ], "description": "Categorical state returned by the suspension service.", "example": "noblocked" } }, "required": [ "status", "message", "result" ], "additionalProperties": false, "title": "VerifySuspensionResponseDto", "type": "object" }, "AddUserToBlacklistBodyDto": { "properties": { "users": { "items": { "type": "string" }, "description": "External identifiers of the users to block.", "type": "array", "example": [ "+50212345678", "+50287654321" ] }, "clientName": { "description": "Client slug the block applies to.", "type": "string", "example": "cobasy" }, "forceBlock": { "description": "When true, remove the users from the whitelist before blocking.", "type": "boolean", "example": false } }, "required": [ "users", "clientName" ], "additionalProperties": false, "title": "AddUserToBlacklistBodyDto", "type": "object" }, "AddUserToBlacklistResponseDto": { "properties": { "blocked": { "description": "True when at least one user was successfully blocked.", "type": "boolean", "example": true }, "message": { "description": "Optional summary message.", "type": "string", "example": "Users added to blacklist" }, "usersWhiteList": { "items": { "type": "string" }, "description": "Users that were skipped because they were in the whitelist.", "type": "array", "example": [] } }, "required": [ "blocked" ], "additionalProperties": false, "title": "AddUserToBlacklistResponseDto", "type": "object" }, "AddUserToWhitelistBodyDto": { "properties": { "users": { "items": { "type": "string" }, "description": "External identifiers of the users to whitelist.", "type": "array", "example": [ "+50212345678" ] }, "clientName": { "description": "Client slug the whitelist applies to.", "type": "string", "example": "cobasy" }, "suspensions": { "$ref": "#/components/schemas/SuspensionRulesDto" } }, "required": [ "users", "clientName" ], "additionalProperties": false, "title": "AddUserToWhitelistBodyDto", "type": "object" }, "AddUserToWhitelistResponseDto": { "properties": { "added": { "description": "True when the whitelist entry was persisted.", "type": "boolean", "example": true }, "message": { "description": "Optional summary message.", "type": "string", "example": "Users added to whitelist" } }, "required": [ "added" ], "additionalProperties": false, "title": "AddUserToWhitelistResponseDto", "type": "object" }, "TransactionRecordDto": { "properties": { "uid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "client": { "description": "Merchant client slug.", "type": "string", "example": "cobasy" }, "reference": { "description": "Merchant-side reference (idempotency token / order id).", "type": "string", "example": "ORD-2026-0429-001" }, "channel": { "description": "Channel that originated the transaction.", "type": "string", "example": "web" }, "status": { "description": "Final transaction status.", "type": "string", "example": "APPROVED" }, "total": { "description": "Total transaction amount.", "type": "number", "example": 125.5 }, "currency": { "description": "ISO 4217 currency code.", "type": "string", "example": "GTQ" }, "processor": { "description": "Processor key that handled the transaction.", "type": "string", "example": "fac-2" }, "createdAt": { "description": "Transaction creation timestamp (ISO 8601 UTC).", "type": "string", "example": "2026-04-29T14:32:01.000Z" }, "updatedAt": { "description": "Last status update timestamp (ISO 8601 UTC).", "type": "string", "example": "2026-04-29T14:32:14.000Z" } }, "required": [ "uid" ], "additionalProperties": false, "title": "TransactionRecordDto", "description": "DTOs for the `mw-transactions` (`middleware-mwTransactions`) stack — 8\nendpoints that expose CRUD-style transaction queries: lookup, search,\ndetail, CSV export.\n\nSearch payloads accept arbitrary filter combinations server-side; the DTOs\nmodel the documented stable fields. Internal flags consumed by support\ntooling are intentionally omitted from the public surface.", "type": "object" }, "GetTransactionResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/TransactionRecordDto" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetTransactionResponseDto", "type": "object" }, "CreateTransactionBodyDto": { "properties": { "amount": { "description": "Transaction amount.", "type": "number", "example": 125.5 }, "client": { "description": "Merchant client slug.", "type": "string", "example": "cobasy" }, "userId": { "description": "End-user identifier.", "type": "string", "example": "+50212345678" }, "channel": { "description": "Channel that originated the transaction.", "type": "string", "example": "web" }, "currency": { "description": "Optional ISO 4217 currency. Defaults to the first currency allowed for the\nclient.", "type": "string", "example": "GTQ" }, "reference": { "description": "Optional merchant-side reference for idempotency.", "type": "string", "example": "ORD-2026-0429-001" }, "customKeys": { "description": "Free-form metadata persisted alongside the transaction." } }, "required": [ "amount", "client", "userId", "channel" ], "additionalProperties": false, "title": "CreateTransactionBodyDto", "type": "object" }, "CreateTransactionResponseDto": { "properties": { "success": { "description": "Whether the transaction was created.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/TransactionRecordDto" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "CreateTransactionResponseDto", "type": "object" }, "SearchTransactionBodyDto": { "properties": { "client": { "description": "Merchant client slug. Required for tenant isolation.", "type": "string", "example": "cobasy" }, "status": { "items": { "type": "string" }, "description": "Optional list of transaction status values to filter by.", "type": "array", "example": [ "APPROVED", "PENDING" ] }, "from": { "description": "Inclusive lower bound for `createdAt` (ISO 8601 UTC).", "type": "string", "example": "2026-04-01T00:00:00.000Z" }, "to": { "description": "Inclusive upper bound for `createdAt` (ISO 8601 UTC).", "type": "string", "example": "2026-04-30T23:59:59.999Z" }, "userId": { "description": "Optional end-user filter.", "type": "string", "example": "+50212345678" }, "page": { "description": "Pagination — page index (1-based).", "type": "number", "example": 1 }, "limit": { "description": "Pagination — items per page.", "type": "number", "example": 50 }, "filters": { "description": "Free-form filter bag forwarded to the search engine. Schema is search-defined." } }, "required": [ "client" ], "additionalProperties": false, "title": "SearchTransactionBodyDto", "type": "object" }, "SearchTransactionResponseDto": { "properties": { "success": { "description": "Whether the search succeeded.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "properties": { "total": { "description": "Total matching records (across all pages).", "type": "number", "example": 412 }, "items": { "items": { "$ref": "#/components/schemas/TransactionRecordDto" }, "description": "Page of results.", "type": "array" } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "SearchTransactionResponseDto", "type": "object" }, "SearchTransactionsGetResponseDto": { "properties": { "success": { "description": "Whether the search succeeded.", "type": "boolean" }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TransactionRecordDto" }, "type": "array" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "SearchTransactionsGetResponseDto", "type": "object" }, "DownloadCsvBodyDto": { "properties": { "client": { "description": "Merchant client slug.", "type": "string", "example": "cobasy" }, "from": { "description": "Inclusive lower bound for `createdAt`.", "type": "string", "example": "2026-04-01T00:00:00.000Z" }, "to": { "description": "Inclusive upper bound for `createdAt`.", "type": "string", "example": "2026-04-30T23:59:59.999Z" }, "recipients": { "items": { "type": "string" }, "description": "Email recipient(s) for the CSV report. CSV is generated asynchronously and\ndelivered via SES.", "type": "array", "example": [ "ops@cobasy.com" ] }, "filters": { "description": "Free-form filters applied to the CSV export." } }, "required": [ "client", "from", "to" ], "additionalProperties": false, "title": "DownloadCsvBodyDto", "type": "object" }, "DownloadCsvResponseDto": { "properties": { "success": { "description": "Whether the CSV job was queued.", "type": "boolean", "example": true }, "message": { "description": "Status message.", "type": "string", "example": "CSV job queued" }, "data": { "anyOf": [ { "properties": { "jobId": { "description": "Identifier of the queued CSV job.", "type": "string", "example": "csv_8f3c2b1d" } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "DownloadCsvResponseDto", "type": "object" }, "GetTransactionDetailsResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean" }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "properties": { "transaction": { "$ref": "#/components/schemas/TransactionRecordDto" }, "steps": { "items": {}, "description": "Step history (MongoDB transaction steps).", "type": "array" }, "metadata": { "description": "Processor + client metadata snapshot at the time of the request." } }, "additionalProperties": false, "type": "object" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetTransactionDetailsResponseDto", "type": "object" }, "GetTransactionsByUserIdCreatedByResponseDto": { "properties": { "success": { "description": "Whether the lookup succeeded.", "type": "boolean" }, "message": { "description": "Status message.", "type": "string" }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TransactionRecordDto" }, "type": "array" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "GetTransactionsByUserIdCreatedByResponseDto", "type": "object" }, "MwTransactionsGenericResponseDto": { "properties": { "success": { "description": "Whether the operation completed successfully.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string" }, "data": { "nullable": true } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "MwTransactionsGenericResponseDto", "type": "object" }, "CardInfoDto": { "properties": { "cardNumber": { "description": "Card number (PAN). Required only when the request did not present a\ntokenized card via `additionalData.encrypt`.", "type": "string", "example": "4111111111111111" }, "cardHolder": { "description": "Cardholder full name as embossed on the card.", "type": "string", "example": "JANE DOE" }, "expirationDate": { "description": "Card expiration in `MM/YY` or `MM/YYYY` format depending on processor.", "type": "string", "example": "12/29" }, "cvv": { "description": "Card verification value (3 or 4 digits).", "type": "string", "example": "123" } }, "additionalProperties": false, "title": "CardInfoDto", "description": "DTOs for the `middleware-pay` stack (16 endpoints).\n\nThe runtime handlers in `paymentHandler.ts` are highly dynamic — they branch on\nprocessor type and accept processor-specific payloads under `body.data` /\n`body.cardInfo`. The DTOs below model the **stable** envelope (transaction\nidentifier, processor name, common fields) and treat processor-specific blocks\nas `Record` so the OpenAPI surface stays accurate without\npretending to be exhaustive.\n\nCross-references:\n- `libs/common-utis/src/lib/schemas/models/payment.model.ts` — runtime models.\n- `paymentHandler.methods.ts` — dispatch maps that decide which processor\n library handles each `processor` value.", "type": "object" }, "BillingAddressDto": { "properties": { "address": { "description": "Billing address — street + number.", "type": "string", "example": "Calle Falsa 123" }, "city": { "description": "City of the billing address.", "type": "string", "example": "Guatemala" }, "state": { "description": "State / department / province.", "type": "string", "example": "Guatemala" }, "country": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string", "example": "GT" }, "postalCode": { "description": "Postal/ZIP code.", "type": "string", "example": "01001" } }, "additionalProperties": false, "title": "BillingAddressDto", "type": "object" }, "TransactionSummaryDto": { "properties": { "uid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "reference": { "description": "Merchant-side reference (idempotency token / order id).", "type": "string", "example": "ORD-2026-0429-001" }, "status": { "description": "Final transaction status.", "type": "string", "example": "APPROVED" }, "channel": { "description": "Channel that originated the transaction.", "type": "string", "example": "web" }, "createdAt": { "description": "Transaction creation timestamp (ISO 8601 UTC).", "type": "string", "example": "2026-04-29T14:32:01.000Z" }, "currency": { "description": "ISO 4217 currency code.", "type": "string", "example": "GTQ" }, "total": { "description": "Total transaction amount.", "type": "number", "example": 125.5 }, "totalCapture": { "description": "Captured amount when the processor performs partial captures.", "type": "number", "example": 125.5 }, "totalRefund": { "description": "Refunded amount when the processor performs partial refunds.", "type": "number", "example": 0 }, "paymentData": { "description": "Processor-specific payload (links, references, additional data)." } }, "required": [ "uid", "status" ], "additionalProperties": false, "title": "TransactionSummaryDto", "type": "object" }, "MakePaymentBodyDto": { "properties": { "transactionUid": { "description": "Migo transaction uid created previously via `POST /transactions-hook`.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "processor": { "description": "Processor key (must be present in `clientConfig.processors` and in the\n`makePaymentMethods` dispatch map).", "type": "string", "example": "fac-2" }, "installments": { "description": "Number of installments (1 = single-payment).", "type": "number", "example": 1 }, "cardInfo": { "$ref": "#/components/schemas/CardInfoDto" }, "billTo": { "$ref": "#/components/schemas/BillingAddressDto" }, "customKeys": { "description": "Free-form key/value bag forwarded to the processor and persisted on the\ntransaction. Used by some processors to embed deep-link / wallet metadata." } }, "required": [ "transactionUid", "processor", "installments" ], "additionalProperties": false, "title": "MakePaymentBodyDto", "type": "object" }, "MakePaymentResponseDto": { "properties": { "success": { "description": "`true` for terminal states (APPROVED / DENIED with structured payload).", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/TransactionSummaryDto" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "MakePaymentResponseDto", "type": "object" }, "PaymentChallengeBodyDto": { "properties": { "transactionUid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "processor": { "description": "Processor key. Must be one of the keys in `paymentSecondStepMethods`\n(`visa-epay`, `visa-cybersource`).", "type": "string", "example": "visa-cybersource" }, "data": { "description": "Processor-specific challenge payload. For `visa-cybersource` this carries\n`referenceId`, `accessToken`, etc." } }, "required": [ "transactionUid", "processor" ], "additionalProperties": false, "title": "PaymentChallengeBodyDto", "type": "object" }, "Payment3DSConfirmBodyDto": { "properties": { "transactionUid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "processor": { "description": "Processor key. Must be one of the keys in `payment3DSConfirmMethods`\n(`visa-epay`, `visa-cybersource`, `serfinsa`).", "type": "string", "example": "visa-cybersource" }, "data": { "description": "3DS authentication artifacts (`paRes`/`md`/`cres`/`xid`, depending on\nthe processor and 3DS version)." } }, "required": [ "transactionUid", "processor" ], "additionalProperties": false, "title": "Payment3DSConfirmBodyDto", "type": "object" }, "PaymentStatusQueryDto": { "properties": { "trxUid": { "description": "Migo transaction uid (passed as `?trxUid=...`).", "type": "string", "example": "trx_8f3c2b1d9e7a" } }, "required": [ "trxUid" ], "additionalProperties": false, "title": "PaymentStatusQueryDto", "type": "object" }, "PaymentRevertBodyDto": { "properties": { "trxUid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "amount": { "description": "Optional partial revert amount. If omitted, the full transaction is\nreverted.", "type": "number", "example": 50 }, "metadata": { "description": "Audit metadata. Free-form. Persisted alongside the revert step." } }, "required": [ "trxUid" ], "additionalProperties": false, "title": "PaymentRevertBodyDto", "type": "object" }, "PaymentRefundBodyDto": { "properties": { "trxUid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "amount": { "description": "Optional partial refund amount. If omitted, the full transaction is\nrefunded.", "type": "number", "example": 25 }, "reason": { "description": "Optional reason recorded on the refund step.", "type": "string", "example": "customer_request" } }, "required": [ "trxUid" ], "additionalProperties": false, "title": "PaymentRefundBodyDto", "type": "object" }, "PaymentHookBodyDto": { "additionalProperties": {}, "title": "PaymentHookBodyDto", "type": "object" }, "CaptureHookBodyDto": { "properties": { "amount": { "description": "Capture amount (when partial). Optional — defaults to the original\nauthorization amount.", "type": "number", "example": 125.5 }, "metadata": { "description": "Processor-specific extras (reason codes, idempotency keys)." } }, "additionalProperties": false, "title": "CaptureHookBodyDto", "type": "object" }, "CapturePaymentTokenBodyDto": { "properties": { "amount": { "description": "Capture amount when supported by the processor; otherwise full\nauthorization is captured.", "type": "number", "example": 125.5 } }, "additionalProperties": false, "title": "CapturePaymentTokenBodyDto", "type": "object" }, "CancelCapturePaymentTokenBodyDto": { "properties": { "reason": { "description": "Optional reason recorded on the cancel-capture step.", "type": "string", "example": "operator_cancel" } }, "additionalProperties": false, "title": "CancelCapturePaymentTokenBodyDto", "type": "object" }, "CancelPaymentRequestQueryDto": { "properties": { "reason": { "description": "Optional reason persisted on the cancel step.", "type": "string", "example": "user_cancelled" } }, "additionalProperties": false, "title": "CancelPaymentRequestQueryDto", "type": "object" }, "VerifyPaymentBodyDto": { "properties": { "trxUid": { "description": "Migo transaction uid to verify upstream.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "processor": { "description": "Processor key. Must be one of the keys in `verifyPaymentMethods`\n(currently `paymentez`).", "type": "string", "example": "paymentez" } }, "required": [ "trxUid", "processor" ], "additionalProperties": false, "title": "VerifyPaymentBodyDto", "type": "object" }, "PaymentCashValidationResponseDto": { "properties": { "success": { "description": "Whether the cash payment reference can still be confirmed.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "Cash reference still valid" }, "data": { "nullable": true } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "PaymentCashValidationResponseDto", "type": "object" }, "PaymentCashConfirmBodyDto": { "properties": { "trxUid": { "description": "Migo transaction uid for the cash transaction.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "reference": { "description": "Reference printed on the cash voucher / payment slip.", "type": "string", "example": "CASH-REF-9912" }, "processor": { "description": "Processor key handling cash confirmations. Currently `pronet`.", "type": "string", "example": "pronet" } }, "required": [ "trxUid" ], "additionalProperties": false, "title": "PaymentCashConfirmBodyDto", "type": "object" }, "VerifyExternalPaymentsBodyDto": { "properties": { "transactionUid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "processor": { "description": "External processor key. Currently `davivienda`.", "type": "string", "example": "davivienda" }, "documetType": { "description": "Customer document type used by the external processor.", "type": "string", "example": "CC" }, "IdClienteOrigen": { "description": "Customer document id.", "type": "string", "example": "1020304050" } }, "required": [ "transactionUid", "processor" ], "additionalProperties": false, "title": "VerifyExternalPaymentsBodyDto", "type": "object" }, "PayGenericResponseDto": { "properties": { "success": { "description": "Whether the operation completed successfully.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/TransactionSummaryDto" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "PayGenericResponseDto", "type": "object" }, "CreateAlternativeTransactionBodyDto": { "properties": { "amount": { "description": "Amount to be charged. Up to 4 decimal places. Must satisfy the merchant\n`min`/`max` thresholds resolved from the client config.", "type": "number", "example": 125.5 }, "channel": { "description": "Channel that originated the transaction (free-form merchant tag).\nCommon values: `wa`, `web`, `pos`, `mobile`.", "type": "string", "example": "wa" }, "client": { "description": "Slug of the merchant client this transaction belongs to.", "type": "string", "example": "cobasy" }, "userId": { "description": "External user identifier supplied by the merchant (phone, email or any\nclient-issued id).", "type": "string", "example": "+50212345678" }, "customKeys": { "description": "Free-form key/value bag carried alongside the transaction. Used by some\nprocessors to embed deep-link or wallet-specific metadata.", "example": { "orderId": "ABC-123", "channel": "kushki" } } }, "required": [ "amount", "channel", "client", "userId" ], "additionalProperties": false, "title": "CreateAlternativeTransactionBodyDto", "description": "DTOs for the `mw-trxs` (alternative payments) stack.\n\nMirror of the runtime models defined in\n`libs/common-utis/src/lib/schemas/models/transaction.model.ts`, augmented with JSDoc\ndescriptions and `@example` tags so that `serverless-auto-swagger` can derive an\naccurate OpenAPI representation.\n\nThe shapes here MUST remain assignable to the runtime models — keep additions\noptional and avoid renaming fields.", "type": "object" }, "CreateAlternativeTransactionResponseDataDto": { "properties": { "uid": { "description": "Migo unique identifier (uid) for the newly created transaction.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "paymentMethods": { "items": { "type": "string" }, "description": "List of alternative payment methods enabled for this client/transaction.\nResolved from the intersection of `clientConfig.processors` and the global\n`ALTERNATIVE_PAYMENT_METHODS` configuration.", "type": "array", "example": [ "nequi", "quickPayQR", "bbvaQR" ] }, "expireAt": { "description": "Seconds remaining until the transaction expires and can no longer be paid.", "type": "number", "example": 900 } }, "required": [ "uid", "paymentMethods", "expireAt" ], "additionalProperties": false, "title": "CreateAlternativeTransactionResponseDataDto", "type": "object" }, "CreateAlternativeTransactionResponseDto": { "properties": { "success": { "description": "Always `true` for 201 responses.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "Transaction created" }, "data": { "$ref": "#/components/schemas/CreateAlternativeTransactionResponseDataDto" } }, "required": [ "success", "message", "data" ], "additionalProperties": false, "title": "CreateAlternativeTransactionResponseDto", "type": "object" }, "AlternativePaymentKeyValueDto": { "properties": { "key": { "description": "Identifier returned by the corresponding `/payment-intents` lookup.", "type": "string", "example": "1022" } }, "additionalProperties": false, "title": "AlternativePaymentKeyValueDto", "description": "Optional sub-shape used by GlobalPay PSE for bank, FIS-type and user-type\npickers. Each carries the `key` returned by the `/payment-intents` lookup.", "type": "object" }, "AlternativePaymentBillDto": { "properties": { "id": { "description": "Bill id from `GetServicesBills`.", "type": "string" }, "number": { "description": "Bill number from `GetServicesBills`.", "type": "string" }, "documentNumber": { "description": "Customer document number.", "type": "string" }, "documentType": { "description": "Customer document type (e.g. `RUC`, `DNI`).", "type": "string" }, "maturityDate": { "description": "Bill maturity date (`YYYY-MM-DD`).", "type": "string" } }, "additionalProperties": false, "title": "AlternativePaymentBillDto", "description": "Sub-shape used by BBVA QR for the bill returned by `GetServicesBills`.", "type": "object" }, "AlternativePaymentPartnerDto": { "properties": { "id": { "description": "Partner id from `getServiceInfo`.", "type": "string" }, "email": { "description": "Customer email.", "type": "string" }, "phoneNumber": { "description": "Customer phone number.", "type": "string" } }, "additionalProperties": false, "title": "AlternativePaymentPartnerDto", "description": "Sub-shape used by BBVA QR for the partner / payer block.", "type": "object" }, "AlternativePaymentAdditionalDataDto": { "properties": { "additionalPaymentField": { "properties": { "id": { "type": "string" } }, "additionalProperties": false, "type": "object" }, "value": { "type": "string" } }, "additionalProperties": false, "title": "AlternativePaymentAdditionalDataDto", "description": "Sub-shape used by BBVA QR for the `additionalData[*]` array.", "type": "object" }, "AlternativePaymentDataDto": { "properties": { "phoneNumber": { "description": "Customer phone number (Nequi push-payment).", "type": "string", "example": "30058059" }, "coupon": { "description": "Cash voucher coupon (Oky).", "type": "string", "example": "51631XAU6Z" }, "bank": { "$ref": "#/components/schemas/AlternativePaymentKeyValueDto" }, "fisType": { "$ref": "#/components/schemas/AlternativePaymentKeyValueDto" }, "fiscalNumber": { "description": "Tax identification number (GlobalPay PSE).", "type": "string", "example": "2345678421" }, "userType": { "$ref": "#/components/schemas/AlternativePaymentKeyValueDto" }, "userName": { "description": "Customer full name (GlobalPay PSE).", "type": "string", "example": "John Doe" }, "email": { "description": "Customer email (GlobalPay PSE).", "type": "string", "example": "customer@example.com" }, "installments": { "description": "Number of installments (GlobalPay PSE, `bamPaymentButton`).", "type": "number", "example": 1 }, "serviceProvider": { "description": "Service provider name from `getServiceInfo` (BBVA QR).", "type": "string", "example": "ISIL S.A." }, "serviceId": { "description": "Service id from `getServiceInfo` (BBVA QR).", "type": "string", "example": "00110010020680005" }, "contractId": { "description": "Contract id from `getServiceInfo` (BBVA QR).", "type": "string", "example": "00110241000189034289" }, "bill": { "$ref": "#/components/schemas/AlternativePaymentBillDto" }, "partner": { "$ref": "#/components/schemas/AlternativePaymentPartnerDto" }, "additionalData": { "items": { "$ref": "#/components/schemas/AlternativePaymentAdditionalDataDto" }, "description": "Additional payment fields from `getServiceInfo` (BBVA QR).", "type": "array" }, "token": { "description": "Apple Pay payment token from `ApplePaySession.onpaymentauthorized`\n(`applePayFac`)." }, "paymentMethod": { "description": "Apple Pay payment method metadata (`applePayFac`)." }, "billTo": { "description": "Apple Pay billing address (`applePayFac`)." }, "transactionIdentifier": { "description": "Apple Pay transaction identifier returned by Apple (`applePayFac`).", "type": "string" } }, "additionalProperties": {}, "title": "AlternativePaymentDataDto", "description": "**Unified data envelope for `POST /v1/mw-trxs/{trxUid}/payments`.**\n\nThe integrator may always send every field below — the runtime only reads\nthe keys that apply to the chosen `processor`, validated against\n`ALTERNATIVE_PAYMENT_METHODS[processor].payload` from the global config.\nFields that do not apply are ignored.\n\nField-to-processor mapping:\n- `phoneNumber`: `nequi`\n- `coupon`: `oky`\n- `bank`, `fisType`, `fiscalNumber`, `userType`, `userName`, `email`,\n `installments`: `globalPay-PSE`\n- `installments`: also `bamPaymentButton`\n- `serviceProvider`, `serviceId`, `contractId`, `bill`, `partner`,\n `additionalData`: `bbvaQR`\n- `token`, `paymentMethod`, `billTo`, `transactionIdentifier`: `applePayFac`\n\nProcessors with no `data` requirements: `bancoIndustrial`, `quickPayQR`,\n`akisiQR`, `pronet`, `fri`, `zigi` (send an empty `{}`).", "type": "object" }, "AlternativePaymentBodyDto": { "properties": { "processor": { "description": "Identifier of the alternative payment method to charge against. Must be\npresent in the `paymentMethods` array returned at transaction creation.", "type": "string", "example": "nequi" }, "data": { "$ref": "#/components/schemas/AlternativePaymentDataDto" } }, "required": [ "processor" ], "additionalProperties": false, "title": "AlternativePaymentBodyDto", "type": "object" }, "AlternativePaymentResponseDataDto": { "properties": { "uid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "type": { "description": "Indicates how the merchant should consume the `data` field:\n - `url`: redirect customer to URL\n - `qr`: render QR string as image\n - `html`: render HTML form (eg. PSE)\n - `json`: structured payload (cash references, intents)\n - `payButton`: Nequi-style button payload", "type": "string", "example": "url" }, "data": { "description": "Payload whose shape depends on `type` (URL string, QR string, HTML string,\nor JSON object). See processors guide for details per provider.", "example": "https://gateway.example.com/redirect/abc" }, "cancelAt": { "description": "Optional auto-cancel window in seconds (computed from\n`clientConfig.minutesToCancel`).", "nullable": true, "type": "number", "example": 600 } }, "additionalProperties": false, "title": "AlternativePaymentResponseDataDto", "type": "object" }, "AlternativePaymentResponseDto": { "properties": { "success": { "description": "Whether the payment was successfully initiated with the processor.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "success" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/AlternativePaymentResponseDataDto" }, { "nullable": true } ] } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "AlternativePaymentResponseDto", "type": "object" }, "PaymentIntentsBodyDto": { "properties": { "processor": { "description": "Alternative payment processor for which to fetch metadata\n(banks for PSE, fixtures for Nequi, etc).", "type": "string", "example": "globalPay-PSE" } }, "required": [ "processor" ], "additionalProperties": false, "title": "PaymentIntentsBodyDto", "type": "object" }, "PaymentIntentsResponseDto": { "properties": { "success": { "description": "Whether the intent metadata was retrieved successfully.", "type": "boolean", "example": true }, "message": { "description": "Human-readable status message.", "type": "string", "example": "success" }, "data": { "description": "Processor-specific intent payload. For `globalPay-PSE` returns\n`{ banks, accountTypes, fisTypes, userTypes }`; other processors return\nfixtures or the raw provider response.", "nullable": true } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "PaymentIntentsResponseDto", "type": "object" }, "DismissTransactionBodyDto": { "properties": { "reason": { "description": "Optional reason exposed for audit/logging. The handler ignores unknown\nfields, so this object is intentionally permissive.", "type": "string", "example": { "reason": "user_cancelled" } }, "metadata": { "description": "Free-form metadata propagated to processor-side cancel hooks (when the\nprocessor supports `requestConfig.cancel`)." } }, "additionalProperties": false, "title": "DismissTransactionBodyDto", "type": "object" }, "DismissTransactionResponseTransactionDto": { "properties": { "uid": { "description": "Migo transaction uid.", "type": "string", "example": "trx_8f3c2b1d9e7a" }, "status": { "description": "Final transaction status after dismissal. `CANCELLED` when a processor\ncancel hook ran; `DISMISSED` otherwise.", "type": "string", "example": "CANCELLED" } }, "required": [ "uid", "status" ], "additionalProperties": false, "title": "DismissTransactionResponseTransactionDto", "type": "object" }, "DismissTransactionResponseDto": { "properties": { "message": { "description": "Human-readable status message.", "type": "string", "example": "Transaction dismissed successfully" }, "transaction": { "$ref": "#/components/schemas/DismissTransactionResponseTransactionDto" } }, "required": [ "message" ], "additionalProperties": false, "title": "DismissTransactionResponseDto", "type": "object" }, "VerifyBinBodyDto": { "properties": { "bin": { "description": "Bank Identification Number: first 6 to 8 digits of the card.", "type": "string", "example": "411111" }, "phone": { "description": "User phone number in E.164 format.", "type": "string", "example": "+50212345678" } }, "required": [ "bin", "phone" ], "additionalProperties": false, "title": "VerifyBinBodyDto", "type": "object" }, "VerifyBinResponseDto": { "properties": { "bin": { "description": "BIN echoed from the request.", "type": "string", "example": "411111" }, "isValid": { "description": "Whether the BIN/phone pair is eligible for the Coppel credit flow.", "type": "boolean", "example": true }, "message": { "description": "Human-readable message returned by Coppel.", "type": "string", "example": "BIN is eligible for Coppel credit" } }, "required": [ "bin" ], "additionalProperties": {}, "title": "VerifyBinResponseDto", "type": "object" }, "SuccessMessageDto": { "properties": { "success": { "description": "Indicates whether the operation succeeded.", "type": "boolean", "example": true }, "message": { "description": "Human-readable outcome message.", "type": "string", "example": "Operation successful" } }, "required": [ "success" ], "additionalProperties": false, "title": "SuccessMessageDto", "type": "object" }, "PlanFrequencyDto": { "properties": { "frequency": { "description": "Number of days between charges (INTERVAL) or minimum cycle length (FIXED_DAY).", "type": "number", "example": 30 }, "shortDescription": { "description": "Short label shown in UIs.", "type": "string", "example": "Monthly" }, "longDescription": { "description": "Long label shown in UIs.", "type": "string", "example": "Charged every 30 days" }, "day": { "description": "Day of month for FIXED_DAY plans (1-28). Ignored for other types.", "type": "number", "example": 15 } }, "required": [ "frequency", "shortDescription", "longDescription", "day" ], "additionalProperties": false, "title": "PlanFrequencyDto", "type": "object" }, "PlanPayloadDto": { "properties": { "name": { "description": "Plan display name.", "type": "string", "example": "Monthly Premium" }, "amount": { "description": "Recurring amount charged each cycle.", "type": "number", "example": 29.99 }, "methods": { "items": { "type": "string" }, "description": "Allowed payment methods for this plan.", "type": "array", "example": [ "card" ] }, "installments": { "items": { "type": "number" }, "description": "Allowed installment counts.", "type": "array", "example": [ 1 ] }, "frequency": { "$ref": "#/components/schemas/PlanFrequencyDto" }, "autoRenewal": { "description": "True when the plan auto-renews at the end of each cycle.", "type": "boolean", "example": true }, "currency": { "description": "ISO 4217 currency code.", "type": "string", "example": "GTQ" }, "dailyAttempts": { "description": "Max daily retry attempts when a charge fails.", "type": "number", "example": 3 }, "daysNotifyExpiringCard": { "description": "Days before expiry to notify the customer about an expiring card.", "type": "number", "example": 15 }, "type": { "description": "Plan billing type.", "type": "string", "example": "INTERVAL" } }, "required": [ "name", "amount", "methods", "installments", "frequency", "autoRenewal", "currency", "dailyAttempts", "daysNotifyExpiringCard", "type" ], "additionalProperties": false, "title": "PlanPayloadDto", "type": "object" }, "CreatePlanBodyDto": { "properties": { "client": { "description": "Client slug the plan belongs to.", "type": "string", "example": "cobasy" }, "plan": { "$ref": "#/components/schemas/PlanPayloadDto" } }, "required": [ "client", "plan" ], "additionalProperties": false, "title": "CreatePlanBodyDto", "type": "object" }, "CreatePlanResponseDto": { "properties": { "success": { "type": "boolean" }, "planId": { "description": "Newly generated plan identifier.", "type": "string", "example": "7b3a8a76-24fd-4b7d-9f88-f3ad1e5d7b10" }, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false, "title": "CreatePlanResponseDto", "type": "object" }, "UpdatePlanBodyDto": { "properties": { "client": { "description": "Client slug owning the plan.", "type": "string", "example": "cobasy" }, "planId": { "description": "Plan identifier.", "type": "string", "example": "7b3a8a76-24fd-4b7d-9f88-f3ad1e5d7b10" }, "plan": {} }, "required": [ "client", "planId", "plan" ], "additionalProperties": false, "title": "UpdatePlanBodyDto", "type": "object" }, "UpdatePlanResponseDto": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false, "title": "UpdatePlanResponseDto", "type": "object" }, "GetPlansQueryDto": { "properties": { "client": { "description": "Client slug whose plan catalog to return.", "type": "string", "example": "cobasy" } }, "required": [ "client" ], "additionalProperties": false, "title": "GetPlansQueryDto", "type": "object" }, "GetPlansResponseDto": { "properties": { "success": { "type": "boolean" }, "data": { "items": { "$ref": "#/components/schemas/PlanPayloadDto" }, "type": "array" } }, "required": [ "success", "data" ], "additionalProperties": false, "title": "GetPlansResponseDto", "type": "object" }, "GetPlanByIdResponseDto": { "properties": { "id": { "description": "Plan identifier.", "type": "string", "example": "7b3a8a76-24fd-4b7d-9f88-f3ad1e5d7b10" }, "nextPaymentDate": { "description": "Next scheduled payment date (ISO 8601).", "type": "string", "example": "2026-05-15T00:00:00.000Z" } }, "required": [ "id", "nextPaymentDate" ], "additionalProperties": false, "title": "GetPlanByIdResponseDto", "type": "object" }, "SubscriptionSummaryDto": { "properties": { "planName": { "description": "Name of the plan the user is subscribed to.", "type": "string", "example": "Monthly Premium" }, "uid": { "description": "Public subscription identifier.", "type": "string", "example": "sub_8f2c1e5a" }, "URL": { "description": "Signed URL to the hosted subscription management page.", "type": "string", "example": "https://webview.migopayments.com/subscriptions/sub_8f2c1e5a" } }, "required": [ "planName", "uid", "URL" ], "additionalProperties": false, "title": "SubscriptionSummaryDto", "type": "object" }, "ListSubscriptionsResponseDto": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "items": { "$ref": "#/components/schemas/SubscriptionSummaryDto" }, "type": "array" } }, "required": [ "success", "data" ], "additionalProperties": false, "title": "ListSubscriptionsResponseDto", "type": "object" }, "UpdateSubscriptionBodyDto": { "properties": { "subscriptionUid": { "description": "Subscription uid to update.", "type": "string", "example": "sub_8f2c1e5a" }, "email": { "description": "New notification email address.", "type": "string", "example": "customer@example.com" } }, "required": [ "subscriptionUid" ], "additionalProperties": false, "title": "UpdateSubscriptionBodyDto", "type": "object" }, "CardSummaryDto": { "properties": { "maskedNumber": { "description": "Masked card number.", "type": "string", "example": "411111******1111" }, "type": { "description": "Card brand.", "type": "string", "example": "visa" }, "expirationDate": { "description": "Card expiration date in MM/YY format.", "type": "string", "example": "12/29" }, "alias": { "description": "Alias set by the cardholder.", "type": "string", "example": "Personal" }, "expiringSoon": { "description": "True when the card's expiration is within the configured notification window.", "type": "boolean", "example": false }, "expired": { "description": "True when the card is already past its expiration.", "type": "boolean", "example": false } }, "additionalProperties": false, "title": "CardSummaryDto", "type": "object" }, "SubscriptionDetailResponseDto": { "properties": { "subscription": {}, "planAmount": { "type": "number" }, "cards": { "items": { "$ref": "#/components/schemas/CardSummaryDto" }, "type": "array" }, "webConfig": {}, "currentBalance": { "type": "number" } }, "required": [ "subscription", "cards" ], "additionalProperties": false, "title": "SubscriptionDetailResponseDto", "type": "object" }, "CancelSubscriptionResponseDto": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Subscription cancelled" } }, "required": [ "success", "message" ], "additionalProperties": false, "title": "CancelSubscriptionResponseDto", "type": "object" }, "AddPaymentMethodBodyDto": { "properties": { "tokenizeData": { "properties": { "userId": { "type": "number", "example": 42 }, "clientId": { "type": "number", "example": 7 }, "processorId": { "type": "number", "example": 3 }, "cardId": { "type": "number", "example": 11 }, "alias": { "type": "string", "example": "Personal" } }, "required": [ "userId", "clientId", "processorId", "cardId" ], "additionalProperties": false, "type": "object" } }, "required": [ "tokenizeData" ], "additionalProperties": false, "title": "AddPaymentMethodBodyDto", "type": "object" }, "AddPaymentMethodResponseDto": { "properties": { "success": { "type": "boolean" }, "data": {}, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false, "title": "AddPaymentMethodResponseDto", "type": "object" }, "VerifyCardBodyDto": { "properties": { "transactionUid": { "description": "Transaction UID that initiated the card verification.", "type": "string", "example": "trx_a1b2c3d4" }, "processor": { "description": "Processor to run the verification through.", "type": "string", "example": "visa-cybersource" }, "cardInfo": { "description": "Tokenizable card payload; shape depends on the processor." }, "shouldCreateSubscription": { "description": "When true, creates the subscription inline after a successful verification.", "type": "boolean", "example": false } }, "required": [ "transactionUid", "processor", "cardInfo" ], "additionalProperties": false, "title": "VerifyCardBodyDto", "type": "object" }, "VerifyCardResponseDto": { "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "challenge": {}, "data": {}, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false, "title": "VerifyCardResponseDto", "type": "object" }, "SetPaymentMethodBodyDto": { "properties": { "subscriptionId": { "description": "Internal subscription id.", "type": "number", "example": 101 }, "paymentMethodId": { "description": "Internal payment method id.", "type": "number", "example": 55 }, "userId": { "description": "Internal user id.", "type": "number", "example": 42 }, "clientId": { "description": "Internal client id.", "type": "number", "example": 7 } }, "required": [ "subscriptionId", "paymentMethodId", "userId", "clientId" ], "additionalProperties": false, "title": "SetPaymentMethodBodyDto", "type": "object" }, "SetPaymentMethodResponseDto": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false, "title": "SetPaymentMethodResponseDto", "type": "object" }, "PaymentHistoryQueryDto": { "properties": { "subscriptionId": { "description": "Internal subscription id.", "type": "string", "example": "101" } }, "required": [ "subscriptionId" ], "additionalProperties": false, "title": "PaymentHistoryQueryDto", "type": "object" }, "PaymentHistoryItemDto": { "properties": { "transactionUid": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "card": { "$ref": "#/components/schemas/CardSummaryDto" } }, "additionalProperties": false, "title": "PaymentHistoryItemDto", "type": "object" }, "PaymentHistoryResponseDto": { "properties": { "success": { "type": "boolean" }, "data": { "items": { "$ref": "#/components/schemas/PaymentHistoryItemDto" }, "type": "array" } }, "required": [ "success", "data" ], "additionalProperties": false, "title": "PaymentHistoryResponseDto", "type": "object" }, "DeletePaymentMethodQueryDto": { "properties": { "methodId": { "description": "Payment method id to delete.", "type": "string", "example": "55" }, "subId": { "description": "Subscription id the method belongs to.", "type": "string", "example": "101" } }, "required": [ "methodId", "subId" ], "additionalProperties": false, "title": "DeletePaymentMethodQueryDto", "type": "object" }, "DeletePaymentMethodResponseDto": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false, "title": "DeletePaymentMethodResponseDto", "type": "object" }, "ChargeItemDto": { "properties": { "subscriptionId": { "description": "Subscription UID to charge.", "type": "string", "example": "sub_8f2c1e5a" }, "amount": { "description": "Amount to charge for this item.", "anyOf": [ { "type": "number" }, { "type": "string" } ], "example": 29.99 }, "metadata": { "description": "Optional free-form metadata attached to the charge." } }, "required": [ "subscriptionId", "amount" ], "additionalProperties": false, "title": "ChargeItemDto", "type": "object" }, "IntakeSubscriptionChargesBodyDto": { "properties": { "client": { "description": "Client slug owning the charges.", "type": "string", "example": "cobasy" }, "data": { "items": { "$ref": "#/components/schemas/ChargeItemDto" }, "description": "Charge entries; max 5000.", "type": "array" } }, "required": [ "client", "data" ], "additionalProperties": false, "title": "IntakeSubscriptionChargesBodyDto", "type": "object" }, "IntakeSubscriptionChargesResponseDto": { "properties": { "clientId": { "description": "Internal client id.", "type": "number", "example": 7 }, "batchId": { "description": "Batch id assigned to the intake.", "type": "string", "example": "batch_6df41a" }, "totals": { "properties": { "accepted": { "type": "number", "example": 120 }, "rejected": { "type": "number", "example": 3 } }, "required": [ "accepted", "rejected" ], "additionalProperties": false, "type": "object" }, "errorsSample": { "items": {}, "type": "array" } }, "required": [ "clientId", "batchId", "totals" ], "additionalProperties": false, "title": "IntakeSubscriptionChargesResponseDto", "type": "object" }, "UploadChargeCsvResponseDto": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": {} }, "required": [ "success" ], "additionalProperties": false, "title": "UploadChargeCsvResponseDto", "type": "object" } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter JWT token" } } } }