{ "openapi": "3.1.0", "info": { "title": "Vero API", "version": "1.0.0", "summary": "API pública da Vero — escrow para o comércio digital. Segure o pagamento, verifique a condição, libere no momento certo.", "description": "Superfície **pública** da API Vero — a que marketplaces, plataformas e integradores usam.\n\n- **Partner API** (`/api/v1/...`) — chave de API (`Authorization: Bearer vero_...`) + escopo por endpoint. Feita para integrações externas e consumo via **MCP**.\n- **Links & checkout público** — páginas do comprador abertas por um token opaco no caminho; retornam só campos seguros ao comprador.\n- **Webhooks de entrada** — callbacks de provedores de pagamento e transportadoras, autenticados por segredo ou assinatura.\n\nExecução financeira de alto risco (liquidação/estorno) **não** é exposta aqui — permanece interna.\n\n**Dinheiro** é string decimal (`\"4199.00\"`) + `currency` ISO-4217. **Datas** em ISO-8601 UTC. Todo erro traz um `code` estável — ramifique por ele, não pelo status.", "contact": { "name": "Vero Developer Support", "url": "https://vero.com/developers" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.vero.com", "description": "Production" }, { "url": "https://sandbox.api.vero.com", "description": "Sandbox (behaves like production; test keys)" }, { "url": "http://localhost:8080", "description": "Local development" } ], "tags": [ { "name": "Partner API", "description": "A superfície versionada para terceiros e **agentes/MCP**. Autentica com uma chave de API (`Authorization: Bearer vero_...`) e um **escopo** por endpoint. É por aqui que marketplaces e plataformas integram." }, { "name": "Links & checkout público", "description": "Páginas e ações voltadas ao comprador, abertas com um **token opaco no caminho** — sem credencial de conta. Retornam apenas campos seguros para o comprador." }, { "name": "Webhooks de entrada", "description": "Callbacks que a Vero **recebe** de provedores de pagamento e transportadoras. Autenticados por segredo compartilhado ou assinatura, idempotentes e seguros contra enumeração." } ], "components": { "schemas": { "ApiError": { "type": "object", "description": "Normalized error body returned by every endpoint on failure.", "required": [ "code", "message", "status", "timestamp" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code (see the error table in README).", "example": "INVALID_STATE_TRANSITION" }, "message": { "type": "string", "example": "The transaction cannot be released in its current state." }, "status": { "type": "integer", "example": 409 }, "correlationId": { "type": [ "string", "null" ], "description": "Request correlation id; quote it in support requests.", "example": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-05-10T14:21:00Z" }, "details": { "type": "array", "description": "Field-level validation details (present for VALIDATION_FAILED).", "items": { "type": "object", "properties": { "path": { "type": "string", "example": "destination" }, "message": { "type": "string", "example": "must not be blank" } } } } } }, "LinkDefinitionRequest": { "type": "object", "required": [ "transactionType", "amount", "currency", "feePayer", "methods", "expiresAt" ], "properties": { "transactionType": { "type": "string", "enum": [ "GOODS", "SERVICE" ] }, "amount": { "type": "string", "description": "Decimal item amount." }, "currency": { "type": "string", "description": "ISO-4217." }, "feePayer": { "type": "string", "enum": [ "BUYER", "MERCHANT", "SPLIT" ] }, "methods": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "PIX", "CARD", "BOLETO" ] } }, "expiresAt": { "type": "string", "format": "date-time" }, "buyerRequirements": { "type": "array", "items": { "type": "string" } }, "goods": { "type": "object", "description": "Required when transactionType is GOODS.", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer", "default": 1 }, "condition": { "type": "string" }, "deliveryMode": { "type": "string", "default": "SHIPPING" }, "shippingAddressRequired": { "type": "boolean" }, "shippingTerms": { "type": "string" } } }, "service": { "type": "object", "description": "Required when transactionType is SERVICE.", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "startConditions": { "type": "string" }, "estimatedDurationDays": { "type": "integer" }, "maximumDurationDays": { "type": "integer" }, "deliverables": { "type": "array", "items": { "type": "string" } }, "completionCriteria": { "type": "string" } } } } }, "LinkResponse": { "type": "object", "properties": { "linkId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "EXPIRED", "CANCELLED", "CONSUMED" ] }, "transactionType": { "type": "string", "enum": [ "GOODS", "SERVICE" ] }, "amount": { "type": "string" }, "currency": { "type": "string" }, "feePayer": { "type": "string", "enum": [ "BUYER", "MERCHANT", "SPLIT" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "buyerRequirements": { "type": "array", "items": { "type": "string" } }, "pricing": { "type": "object", "properties": { "itemAmount": { "type": "string" }, "feeAmount": { "type": "string" }, "buyerTotal": { "type": "string" }, "merchantExpectedNet": { "type": "string" }, "currency": { "type": "string" }, "feePayer": { "type": "string" } } } } }, "PartnerSubMerchant": { "type": "object", "description": "A seller owned by the calling platform.", "required": [ "merchantId", "displayName", "status", "blocked" ], "properties": { "merchantId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "displayName": { "type": "string", "example": "Loja do João" }, "legalName": { "type": [ "string", "null" ], "example": "João da Silva ME" }, "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED", "DISABLED" ], "example": "ACTIVE" }, "blocked": { "type": "boolean", "description": "True when the account is not ACTIVE (e.g. blocked).", "example": false }, "externalReference": { "type": [ "string", "null" ], "description": "The platform's own id for this seller.", "example": "seller-1042" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-05-10T14:21:00Z" } } }, "PartnerRegisterMerchant": { "type": "object", "description": "Register a seller under the calling platform.", "required": [ "type", "displayName" ], "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ], "description": "INDIVIDUAL follows KYC; BUSINESS follows KYB.", "example": "INDIVIDUAL" }, "displayName": { "type": "string", "example": "Loja do João" }, "legalName": { "type": "string", "example": "João da Silva ME" }, "externalReference": { "type": "string", "description": "The platform's own id for this seller; makes registration idempotent (a repeat is rejected 409).", "example": "seller-1042" } } }, "PartnerUpdateMerchant": { "type": "object", "description": "Update a seller's display/legal name. Omitted fields are left unchanged.", "properties": { "displayName": { "type": "string", "example": "Loja do João — Oficial" }, "legalName": { "type": "string", "example": "João da Silva ME" } } } }, "responses": { "Unauthorized": { "description": "Authentication missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found (or hidden cross-tenant).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ValidationFailed": { "description": "Request body/params failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Conflict": { "description": "State / version / idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "securitySchemes": { "PartnerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "vero_xxx", "description": "Third-party API key. Send `Authorization: Bearer vero_...`. Each endpoint requires an explicit scope: `payment_links:read`, `payment_links:write` (high-risk), `transactions:read`, `refunds:read`, `settlements:read`, `webhooks:read`. New keys default to least privilege.\n" }, "WebhookSecret": { "type": "apiKey", "in": "header", "name": "X-Webhook-Secret", "description": "Shared secret for inbound payment/tracking provider webhooks (constant-time compared; not an HMAC of the body)." }, "CarrierSignature": { "type": "apiKey", "in": "header", "name": "X-Carrier-Signature", "description": "Carrier webhook signature, validated by the carrier adapter over `trackingNumber|rawStatus|carrierEventId` before the body is trusted." } } }, "paths": { "/api/v1/whoami": { "get": { "tags": [ "Partner API" ], "operationId": "partnerWhoami", "summary": "Identity of the calling API key", "description": "Returns the merchant, environment and granted scopes for the presented API key.\n**Surface:** Partner API. Any valid key; no specific scope required.\nSend `X-Request-Id` to have it echoed back (else one is generated).\n", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The calling key's identity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "merchantId": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "SANDBOX", "PRODUCTION" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "example": { "requestId": "7f3c2b10-...", "merchantId": "3a2b...", "environment": "SANDBOX", "scopes": [ "transactions:read" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/transactions": { "get": { "tags": [ "Partner API" ], "operationId": "partnerListTransactions", "summary": "List transactions (demonstration surface)", "description": "Lists transactions for the calling key's merchant. **Surface:** Partner API. Requires the\n`transactions:read` scope. In this version the `data` array is a documented placeholder (empty).\n", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction list envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "merchantId": { "type": "string", "format": "uuid" }, "data": { "type": "array", "items": { "type": "object" } } } }, "example": { "requestId": "7f3c2b10-...", "merchantId": "3a2b...", "data": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/payment-links/{token}": { "get": { "tags": [ "Links & checkout público" ], "operationId": "getPublicLink", "summary": "Resolve a public link (buyer-safe)", "description": "Resolves a public link token to the buyer-safe offer. **Surface:** Public — the link token is the only credential. No ids, fee split or merchant net.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Buyer-safe offer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantDisplayName": { "type": "string" }, "transactionType": { "type": "string", "enum": [ "GOODS", "SERVICE" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "buyerTotal": { "type": "string" }, "currency": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "buyerRequirements": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "AVAILABLE", "EXPIRED", "UNAVAILABLE" ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/payment-links/{token}/fund": { "post": { "tags": [ "Links & checkout público" ], "operationId": "fundPublicLink", "summary": "Fund a link (create the escrow agreement)", "description": "Records the durable escrow agreement (creates a Transaction) and consumes the single-use link. **Surface:** Public — no session; a fresh anonymous buyer id is minted. Distinct from `/v1/public/payment-links/{token}` (checkout).", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "buyerName": { "type": "string" }, "contactReferences": { "type": "array", "items": { "type": "string" } }, "shippingRecipient": { "type": "string" }, "shippingAddress": { "type": "string" }, "maskedDocumentReference": { "type": "string" }, "description": { "type": "string" }, "sellerReference": { "type": "string" } } } } } }, "responses": { "201": { "description": "Transaction created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string", "format": "uuid" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/status/{accessToken}": { "get": { "tags": [ "Links & checkout público" ], "operationId": "publicStatus", "summary": "Public transaction status", "description": "Buyer-safe public status view for a transaction identified solely by its status access token. **Surface:** Public token. Read-only; buyer-safe fields only.", "security": [], "parameters": [ { "name": "accessToken", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public status view.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantDisplayName": { "type": "string" }, "title": { "type": "string" }, "buyerTotal": { "type": "string" }, "currency": { "type": "string" }, "outcomeState": { "type": "string", "enum": [ "PENDING", "DETECTED", "CONFIRMING", "PROTECTED", "FAILED", "DECLINED", "EXPIRED", "CANCELLED", "UNCERTAIN", "DUPLICATE_REVIEW", "NONE" ] }, "financialState": { "type": "string" }, "protectedAmount": { "type": "string" }, "messageCode": { "type": "string" }, "nextAction": { "type": "string", "enum": [ "AWAIT_FULFILLMENT", "WAIT", "WAIT_DO_NOT_RETRY", "CHOOSE_ANOTHER_METHOD", "RESTART" ] }, "escrowStages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "PAYMENT", "PROTECTED", "FULFILLMENT", "RELEASE" ] }, "status": { "type": "string", "enum": [ "DONE", "CURRENT", "PENDING" ] } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/integrations/payments/{provider}/webhook": { "post": { "tags": [ "Webhooks de entrada" ], "operationId": "paymentProviderWebhook", "summary": "Inbound payment provider webhook", "description": "Receives a normalized provider payment event, dedups it, drives the attempt through the state\nmachine and protects funds if confirmed. **Surface:** Webhook — authenticated by a static\n`X-Webhook-Secret` (constant-time compare, not an HMAC of the body).\n", "security": [ { "WebhookSecret": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerReference", "eventId", "status" ], "properties": { "providerReference": { "type": "string" }, "eventId": { "type": "string", "description": "Used for dedup." }, "status": { "type": "string", "enum": [ "INITIATED", "PENDING", "AUTHENTICATION_REQUIRED", "AUTHORIZED", "DETECTED", "CONFIRMING", "CONFIRMED", "DECLINED", "EXPIRED", "UNAVAILABLE", "UNCERTAIN" ] }, "amountMinor": { "type": "integer" }, "currency": { "type": "string" } } } } } }, "responses": { "200": { "description": "Processing result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "callbackOutcome": { "type": "string", "enum": [ "PROCESSED", "DUPLICATE", "IGNORED_OUT_OF_ORDER", "AMOUNT_MISMATCH", "ATTEMPT_NOT_FOUND" ] }, "protectionOutcome": { "type": [ "string", "null" ], "enum": [ "PROTECTED", "ALREADY_PROTECTED", "NOT_CONFIRMED", "NO_TRANSACTION", null ] }, "attemptStatus": { "type": [ "string", "null" ] } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/integrations/tracking/{provider}/webhook": { "post": { "tags": [ "Webhooks de entrada" ], "operationId": "trackingWebhook", "summary": "Inbound tracking webhook (normalized)", "description": "Applies a normalized canonical state to a shipment. **Surface:** Webhook — `X-Webhook-Secret` constant-time compare. Unknown tracking code is an enumeration-safe no-op (still 200).", "security": [ { "WebhookSecret": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trackingCode": { "type": "string" }, "canonicalState": { "type": "string", "description": "A GoodsFulfillmentState name." }, "sourceReference": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "APPLIED", "IGNORED_UNKNOWN_TRACKING" ] } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/logistics/carriers/{carrierId}/webhook": { "post": { "tags": [ "Webhooks de entrada" ], "operationId": "carrierWebhook", "summary": "Inbound carrier webhook (signed)", "description": "Signature-validated carrier webhook, normalized and deduped into tracking ingestion. **Surface:** Webhook — `X-Carrier-Signature` validated over `trackingNumber|rawStatus|carrierEventId` before the body is trusted. Never releases escrow or mutates the ledger.", "security": [ { "CarrierSignature": [] } ], "parameters": [ { "name": "carrierId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trackingNumber": { "type": "string" }, "rawStatus": { "type": "string" }, "carrierEventId": { "type": "string", "description": "Used for dedup." }, "occurredAt": { "type": "string", "format": "date-time" }, "rawPayloadRef": { "type": "string" } } } } } }, "responses": { "200": { "description": "Result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "IGNORED_UNKNOWN_TRACKING", "DEDUPED", "ADVANCED", "RECORDED" ] } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/merchants": { "get": { "tags": [ "Partner API" ], "summary": "List my sub-merchants", "description": "All sellers the calling platform owns, newest first. Requires the `merchants:read` scope.", "security": [ { "PartnerApiKey": [] } ], "responses": { "200": { "description": "The platform's sellers.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerSubMerchant" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Partner API" ], "summary": "Register a sub-merchant (seller)", "description": "Register a seller account owned by the calling platform (e.g. a marketplace onboarding its sellers one by one). The account is created ACTIVE and platform-managed — no dashboard user is provisioned. Verification and activation still happen through onboarding before the seller can take payments. Requires the `merchants:write` scope.", "security": [ { "PartnerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRegisterMerchant" } } } }, "responses": { "201": { "description": "The registered seller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSubMerchant" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A seller is already registered for this externalReference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/merchants/{merchantId}": { "get": { "tags": [ "Partner API" ], "summary": "Get a sub-merchant", "description": "Fetch one seller the platform owns. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `merchants:read` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." } ], "responses": { "200": { "description": "The seller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSubMerchant" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Partner API" ], "summary": "Update a sub-merchant", "description": "Update a seller's display/legal name. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `merchants:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUpdateMerchant" } } } }, "responses": { "200": { "description": "The updated seller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSubMerchant" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/merchants/{merchantId}/block": { "post": { "tags": [ "Partner API" ], "summary": "Block a sub-merchant", "description": "Block a seller (reversible). The account moves to SUSPENDED and the authorization layer refuses every money-moving and management action for it until unblock. Idempotent. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `merchants:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." } ], "responses": { "200": { "description": "The blocked seller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSubMerchant" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/merchants/{merchantId}/unblock": { "post": { "tags": [ "Partner API" ], "summary": "Unblock a sub-merchant", "description": "Restore a blocked seller to ACTIVE. Idempotent. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `merchants:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." } ], "responses": { "200": { "description": "The reinstated seller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSubMerchant" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/merchants/{merchantId}/payment-links": { "get": { "tags": [ "Partner API" ], "summary": "List a seller's payment links", "description": "List the seller's payment links. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `payment_links:read` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." } ], "responses": { "200": { "description": "The seller's links.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "linkId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "EXPIRED", "CANCELLED", "CONSUMED" ] }, "transactionType": { "type": "string", "enum": [ "GOODS", "SERVICE" ] }, "amount": { "type": "string" }, "currency": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "title": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Partner API" ], "summary": "Create a payment link for a seller", "description": "Create a DRAFT payment link on behalf of a seller. The seller must be active (not blocked) and activated (holds the create-payment-link capability). The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `payment_links:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkDefinitionRequest" } } } }, "responses": { "201": { "description": "Created draft link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "linkId": { "type": "string", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "publicToken": { "type": "string", "description": "The shareable token, returned once.", "example": "plink_9aZ" }, "status": { "type": "string", "example": "DRAFT" } } } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The seller cannot create links yet (not activated).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/merchants/{merchantId}/payment-links/{linkId}": { "get": { "tags": [ "Partner API" ], "summary": "Get a payment link", "description": "Fetch one of the seller's payment links. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `payment_links:read` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment link id." } ], "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Partner API" ], "summary": "Update a payment link", "description": "Replace a DRAFT link's definition. Only a DRAFT link can be updated. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `payment_links:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment link id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkDefinitionRequest" } } } }, "responses": { "200": { "description": "The updated link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The link is not editable in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/merchants/{merchantId}/payment-links/{linkId}/activate": { "post": { "tags": [ "Partner API" ], "summary": "Activate a payment link", "description": "Activate a DRAFT link so it can be funded. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `payment_links:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment link id." } ], "responses": { "200": { "description": "The activated link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The link cannot be activated in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/merchants/{merchantId}/payment-links/{linkId}/cancel": { "post": { "tags": [ "Partner API" ], "summary": "Cancel (deactivate) a payment link", "description": "Cancel a draft or active link. This is a soft deactivation — the link moves to CANCELLED and can no longer be funded. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the `payment_links:write` scope.", "security": [ { "PartnerApiKey": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sub-merchant (seller) id." }, { "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment link id." } ], "responses": { "204": { "description": "Cancelled." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } } }