{ "openapi": "3.1.0", "info": { "title": "Payflow API", "version": "2026-09-01", "description": "A API pública do Payflow (Kingdom). Dinheiro em inteiros na subunidade da moeda; datas ISO 8601 em UTC com Z; IDs com prefixo (prod_, ord_, cus_, evt_, re_, cs_, we_, sub_, in_). Chaves sk_live_/sk_test_ no cabeçalho Authorization. Erros RFC 9457. Paginação por cursor. Veja o README do repositório para as assinaturas dos webhooks." }, "servers": [ { "url": "https://api.kingdomcompny.com/v1" }, { "url": "https://epqfotzxrcyligwpauwk.supabase.co/functions/v1/api/v1" } ], "security": [ { "chave": [] } ], "paths": { "/products": { "get": { "operationId": "list_products", "summary": "Listar products", "tags": [ "products" ], "x-scope": "products:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "active", "inactive" ] } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/products/{id}": { "get": { "operationId": "get_products", "summary": "Obter um de products", "tags": [ "products" ], "x-scope": "products:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/orders": { "get": { "operationId": "list_orders", "summary": "Listar orders", "tags": [ "orders" ], "x-scope": "orders:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrderStatus" } }, { "name": "created[gte]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO 8601 ou segundos Unix" }, { "name": "created[lte]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "customer_email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "metadata", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "metadata[chave]=valor" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/orders/{id}": { "get": { "operationId": "get_orders", "summary": "Obter um de orders", "tags": [ "orders" ], "x-scope": "orders:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/customers": { "get": { "operationId": "list_customers", "summary": "Listar customers", "tags": [ "customers" ], "x-scope": "customers:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/customers/{id}": { "get": { "operationId": "get_customers", "summary": "Obter um de customers", "tags": [ "customers" ], "x-scope": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/events": { "get": { "operationId": "list_events", "summary": "Listar events", "tags": [ "events" ], "x-scope": "events:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/events/{id}": { "get": { "operationId": "get_events", "summary": "Obter um de events", "tags": [ "events" ], "x-scope": "events:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/refunds": { "get": { "operationId": "list_refunds", "summary": "Listar refunds", "tags": [ "refunds" ], "x-scope": "refunds:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "create_refund", "summary": "Reembolsar um pedido, todo ou em parte", "tags": [ "refunds" ], "x-scope": "refunds:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order", "reason" ], "properties": { "order": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" }, "amount": { "type": "integer", "minimum": 1, "description": "Subunidades. Sem valor: tudo o que falta devolver." }, "reason": { "type": "string", "minLength": 1 } } } } } }, "responses": { "201": { "description": "Criado e aprovado. Pela Paystack executa-se já; pelo M-Pesa espera a execução no painel.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/refunds/{id}": { "get": { "operationId": "get_refunds", "summary": "Obter um de refunds", "tags": [ "refunds" ], "x-scope": "refunds:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^re_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/checkout_sessions": { "get": { "operationId": "list_checkout_sessions", "summary": "Listar checkout_sessions", "tags": [ "checkout_sessions" ], "x-scope": "checkout_sessions:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "create_checkout_session", "summary": "Criar uma sessão de checkout", "tags": [ "checkout_sessions" ], "x-scope": "checkout_sessions:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "product" ], "properties": { "product": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" }, "quantity": { "const": 1 } } } }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "locale": { "enum": [ "en", "pt", "es" ] }, "metadata": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "maxProperties": 51, "description": "Mapa de texto para texto, até 50 chaves. member_user_id vai sempre (null sem ref)." }, "return_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "expires_in": { "type": "integer", "minimum": 1800, "maximum": 604800, "default": 86400 } } } } } }, "responses": { "201": { "description": "Criada. Manda quem vai pagar para o `url`.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/checkout_sessions/{id}": { "get": { "operationId": "get_checkout_sessions", "summary": "Obter um de checkout_sessions", "tags": [ "checkout_sessions" ], "x-scope": "checkout_sessions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/checkout_sessions/{id}/expire": { "post": { "operationId": "expire_checkout_session", "summary": "Expirar uma sessão aberta", "tags": [ "checkout_sessions" ], "x-scope": "checkout_sessions:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/webhook_endpoints": { "get": { "operationId": "list_webhook_endpoints", "summary": "Listar webhook_endpoints", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "create_webhook_endpoint", "summary": "Criar um endpoint de webhooks", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "pattern": "^https://" }, "description": { "type": "string" }, "enabled_events": { "type": "array", "items": { "enum": [ "order.paid", "order.refunded", "order.disputed", "order.dispute_resolved", "deal.stage_changed", "subscription.created", "subscription.updated", "subscription.canceled", "invoice.created", "invoice.paid", "invoice.voided" ] } }, "products": { "type": "array", "items": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" } }, "return_url_domains": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Criado. O `secret` só se mostra agora.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/webhook_endpoints/{id}": { "get": { "operationId": "get_webhook_endpoints", "summary": "Obter um de webhook_endpoints", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "update_webhook_endpoint", "summary": "Actualizar", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "enabled_events": { "type": "array", "items": { "type": "string" } }, "products": { "type": "array", "items": { "type": "string" } }, "return_url_domains": { "type": "array", "items": { "type": "string" } }, "status": { "enum": [ "enabled", "paused" ] } } } } } }, "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "delete": { "operationId": "delete_webhook_endpoint", "summary": "Apagar", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedWebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/webhook_endpoints/{id}/rotate_secret": { "post": { "operationId": "rotate_webhook_secret", "summary": "Rodar o segredo (o antigo vale mais 24 h)", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/webhook_endpoints/{id}/test": { "post": { "operationId": "test_webhook_endpoint", "summary": "Enviar um integration.test agora", "tags": [ "webhook_endpoints" ], "x-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/subscriptions": { "get": { "operationId": "list_subscriptions", "summary": "Listar as assinaturas", "tags": [ "subscriptions" ], "x-scope": "subscriptions:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SubscriptionStatus" } }, { "name": "customer_email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "created[gte]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO 8601 ou segundos Unix." }, { "name": "created[lte]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO 8601 ou segundos Unix." }, { "name": "metadata[chave]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela metadata: metadata[escola]=…" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "create_subscription", "summary": "Criar uma assinatura", "tags": [ "subscriptions" ], "x-scope": "subscriptions:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "customer", "payment_method" ], "properties": { "product": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Um produto recorrente (Product.recurring não é null)." }, "customer": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "payment_method": { "$ref": "#/components/schemas/PaymentMethodInput" }, "billing_details": { "$ref": "#/components/schemas/BillingDetails" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Texto para texto, até 40 chaves." } } } } } }, "responses": { "201": { "description": "Criada, com a latest_invoice em aberto (a validação, ou o primeiro período sem validação) e o payment_token dela. Com dias grátis e sem validação, nasce trialing e sem fatura.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/subscriptions/{id}": { "get": { "operationId": "get_subscription", "summary": "Obter uma assinatura", "tags": [ "subscriptions" ], "x-scope": "subscriptions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sub_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } }, "post": { "operationId": "update_subscription", "summary": "Mudar uma assinatura", "tags": [ "subscriptions" ], "x-scope": "subscriptions:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sub_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method": { "$ref": "#/components/schemas/PaymentMethodInput" }, "billing_details": { "$ref": "#/components/schemas/BillingDetails" }, "automatic_collection": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Junta-se à que já há." } } } } } }, "responses": { "200": { "description": "OK. Uma assinatura que já acabou (canceled, incomplete_expired) não se muda: 409.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/subscriptions/{id}/cancel": { "post": { "operationId": "cancel_subscription", "summary": "Cancelar uma assinatura", "tags": [ "subscriptions" ], "x-scope": "subscriptions:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sub_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/KingdomVersion" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "at_period_end": { "type": "boolean", "default": false, "description": "true: continua até ao fim do período pago, e só então acaba." }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK. Já acabada: 409.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/invoices": { "get": { "operationId": "list_invoices", "summary": "Listar as faturas das assinaturas", "tags": [ "invoices" ], "x-scope": "invoices:read", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/KingdomVersion" }, { "name": "subscription", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^sub_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/InvoiceStatus" } } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } }, "/invoices/{id}": { "get": { "operationId": "get_invoice", "summary": "Obter uma fatura", "tags": [ "invoices" ], "x-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^in_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "$ref": "#/components/parameters/KingdomVersion" } ], "responses": { "200": { "description": "OK", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "409": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" } } } } }, "webhooks": { "order.paid": { "post": { "summary": "order.paid", "description": "Pagamento confirmado pela Paystack (verify) ou pelo M-Pesa, ou confirmado à mão.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.order.paid" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "order.refunded": { "post": { "summary": "order.refunded", "description": "Cada reembolso executado, parcial ou total. refunded_amount é o acumulado.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.order.refunded" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "order.disputed": { "post": { "summary": "order.disputed", "description": "Disputa aberta (chargeback).", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.order.disputed" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "order.dispute_resolved": { "post": { "summary": "order.dispute_resolved", "description": "Disputa fechada. outcome: won ou lost.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.order.dispute_resolved" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "integration.test": { "post": { "summary": "integration.test", "description": "Botão «Enviar evento de teste», ou POST /webhook_endpoints/{id}/test.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.integration.test" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "deal.stage_changed": { "post": { "summary": "deal.stage_changed", "description": "Uma oportunidade nasceu ou mudou de etapa no quadro do Payflow. Passa a won só quando o primeiro pagamento é confirmado, e aí traz order_id. Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.deal.stage_changed" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "subscription.created": { "post": { "summary": "subscription.created", "description": "Nasceu uma assinatura (por POST /v1/subscriptions). Vem com a latest_invoice aberta. Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.subscription.created" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "subscription.updated": { "post": { "summary": "subscription.updated", "description": "A assinatura mudou: de estado (previous_status diz o de antes), de período, de método ou de metadata. Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.subscription.updated" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "subscription.canceled": { "post": { "summary": "subscription.canceled", "description": "A assinatura acabou: cancelada já, ou no fim do período que estava pago. Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.subscription.canceled" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "invoice.created": { "post": { "summary": "invoice.created", "description": "Saiu uma fatura: a validação à entrada ou a de um período, N dias antes do fim do ciclo. Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.invoice.created" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "invoice.paid": { "post": { "summary": "invoice.paid", "description": "Uma fatura foi paga, por onde quer que seja. A assinatura activa-se ou estende o período. Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.invoice.paid" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } }, "invoice.voided": { "post": { "summary": "invoice.voided", "description": "Uma fatura foi anulada (por exemplo, a validação que não se pagou em 24 h). Não vem por omissão: a integração tem de o pedir em enabled_events.", "parameters": [ { "name": "X-Kingdom-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Kingdom-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event.invoice.voided" } } } }, "responses": { "2XX": { "description": "Recebido. Qualquer 2xx conta como entregue, incluindo {\"duplicate\":true}." } } } } }, "components": { "securitySchemes": { "chave": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_… / sk_test_…" } }, "parameters": { "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, "StartingAfter": { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "O next_cursor da página anterior." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 255 }, "description": "A resposta guarda-se 24 h e devolve-se igual se a chave se repetir; a mesma chave com outro corpo dá 409." }, "KingdomVersion": { "name": "Kingdom-Version", "in": "header", "schema": { "enum": [ "2026-09-01" ] }, "description": "Sem o cabeçalho, vale a versão da chave." } }, "headers": { "Request-Id": { "schema": { "type": "string" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "responses": { "Problem": { "description": "Erro", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "code", "request_id" ], "description": "RFC 9457 (application/problem+json). `code` é estável; `detail` é para pessoas.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "param": { "type": "string" }, "request_id": { "type": "string", "pattern": "^req_" } } }, "Product": { "type": "object", "required": [ "id", "object", "name", "price", "status", "checkout_url", "created_at", "livemode" ], "properties": { "id": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "product" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217" } } }, "status": { "enum": [ "active", "inactive" ] }, "checkout_url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "recurring": { "type": [ "object", "null" ], "description": "Só nos produtos de assinatura (cobrança recorrente mensal ou anual); null nos outros.", "required": [ "interval", "interval_days", "setup_amount", "trial_days", "invoice_days_before", "retry_days", "grace_days" ], "properties": { "interval": { "enum": [ "month", "year" ] }, "interval_days": { "type": "integer", "enum": [ 30, 365 ], "description": "O ciclo: 30 dias (mensal) ou 365 (anual)." }, "setup_amount": { "type": "integer", "minimum": 0, "description": "A validação: cobrada à entrada para provar o método e descontada na primeira fatura de período. 0 = sem validação." }, "trial_days": { "type": "integer", "minimum": 0, "description": "Dias grátis antes do primeiro período." }, "invoice_days_before": { "type": "integer", "minimum": 0, "description": "A fatura de cada período sai estes dias antes do fim do ciclo e vence no último." }, "retry_days": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Dias, contados da emissão, em que se volta a pedir o pagamento." }, "grace_days": { "type": "integer", "minimum": 0, "description": "Dias depois do vencimento até a assinatura passar a unpaid." } } } } }, "Customer": { "type": "object", "required": [ "id", "object", "email", "created_at", "livemode" ], "properties": { "id": { "type": "string", "pattern": "^cus_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "customer" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" } } }, "OrderCustomer": { "type": "object", "required": [ "id", "email", "name", "phone" ], "properties": { "id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "OrderItem": { "type": "object", "required": [ "product_id", "name", "quantity", "unit_amount" ], "properties": { "product_id": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" }, "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "unit_amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." } } }, "OrderStatus": { "enum": [ "pending", "paid", "partially_refunded", "refunded", "disputed", "dispute_won", "dispute_lost" ] }, "Order": { "type": "object", "required": [ "id", "object", "reference", "status", "amount", "currency", "refunded_amount", "full_refund", "paid_at", "created_at", "provider", "provider_reference", "livemode", "customer", "items", "metadata", "locale" ], "properties": { "id": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "order" }, "reference": { "type": "string", "pattern": "^KG-[0-9]{8}-[0-9A-HJKMNP-TV-Z]{5}$" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217" }, "refunded_amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "full_refund": { "type": "boolean" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "provider": { "type": [ "string", "null" ], "enum": [ "paystack", "mpesa", "manual", null ] }, "provider_reference": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "customer": { "$ref": "#/components/schemas/OrderCustomer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "metadata": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "maxProperties": 51, "description": "Mapa de texto para texto, até 50 chaves. member_user_id vai sempre (null sem ref)." }, "locale": { "enum": [ "en", "pt", "es" ] } } }, "Refund": { "type": "object", "required": [ "id", "object", "order", "amount", "currency", "status", "created_at", "livemode" ], "properties": { "id": { "type": "string", "pattern": "^re_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "refund" }, "order": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" }, "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217" }, "reason": { "type": [ "string", "null" ] }, "status": { "enum": [ "pending", "succeeded", "failed", "canceled" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" } } }, "CheckoutSession": { "type": "object", "required": [ "id", "object", "url", "status", "product", "expires_at", "created_at", "livemode" ], "properties": { "id": { "type": "string", "pattern": "^cs_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "checkout_session" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "enum": [ "open", "complete", "expired" ] }, "product": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" }, "customer_email": { "type": [ "string", "null" ] }, "customer_name": { "type": [ "string", "null" ] }, "customer_phone": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ], "enum": [ "en", "pt", "es", null ] }, "metadata": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "maxProperties": 51, "description": "Mapa de texto para texto, até 50 chaves. member_user_id vai sempre (null sem ref)." }, "return_url": { "type": [ "string", "null" ] }, "order": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "object", "url", "enabled_events", "status", "api_version", "livemode", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "webhook_endpoint" }, "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "description": { "type": "string" }, "enabled_events": { "type": "array", "items": { "enum": [ "order.paid", "order.refunded", "order.disputed", "order.dispute_resolved", "deal.stage_changed", "subscription.created", "subscription.updated", "subscription.canceled", "invoice.created", "invoice.paid", "invoice.voided" ] } }, "products": { "type": "array", "items": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" } }, "status": { "enum": [ "enabled", "paused", "disabled" ] }, "api_version": { "type": "string" }, "return_url_domains": { "type": "array", "items": { "type": "string" } }, "secret_prefix": { "type": [ "string", "null" ] }, "alert": { "type": [ "string", "null" ] }, "secret": { "type": "string", "pattern": "^whsec_", "description": "Só na criação e na rotação. Não se volta a mostrar." }, "previous_secret_expires_at": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" } } }, "DeletedWebhookEndpoint": { "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string", "pattern": "^we_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "webhook_endpoint" }, "deleted": { "const": true } } }, "WebhookTest": { "type": "object", "required": [ "object", "delivered", "outcome" ], "properties": { "object": { "const": "webhook_test" }, "event": { "type": [ "string", "null" ] }, "delivered": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ] }, "outcome": { "enum": [ "entregue", "temporario", "configuracao", "definitivo", "queued" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "response_excerpt": { "type": [ "string", "null" ] } } }, "OrderEventData": { "type": "object", "required": [ "order", "customer", "locale", "items", "metadata" ], "properties": { "order": { "type": "object", "required": [ "id", "reference", "status", "amount", "currency", "refunded_amount", "full_refund", "paid_at", "provider", "provider_reference" ], "properties": { "id": { "type": "string", "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$" }, "reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217" }, "refunded_amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "full_refund": { "type": "boolean" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "provider": { "type": [ "string", "null" ] }, "provider_reference": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" } } }, "customer": { "$ref": "#/components/schemas/OrderCustomer" }, "locale": { "enum": [ "en", "pt", "es" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "metadata": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "maxProperties": 51, "description": "Mapa de texto para texto, até 50 chaves. member_user_id vai sempre (null sem ref)." }, "refund": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^re_[0-9A-HJKMNP-TV-Z]{26}$" }, "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" } } }, "dispute": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dp_[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": [ "string", "null" ] }, "amount": { "type": [ "integer", "null" ] }, "opened_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "closed_at": { "type": "string", "format": "date-time", "pattern": "Z$" } } }, "outcome": { "enum": [ "won", "lost" ] } } }, "Event.order.paid": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "order.paid" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/OrderEventData" } } }, "Event.order.refunded": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "order.refunded" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OrderEventData" }, { "required": [ "refund" ] } ] } } }, "Event.order.disputed": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "order.disputed" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OrderEventData" }, { "required": [ "dispute" ] } ] } } }, "Event.order.dispute_resolved": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "order.dispute_resolved" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OrderEventData" }, { "required": [ "outcome", "dispute" ] } ] } } }, "Event.integration.test": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "integration.test" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } }, "Event": { "oneOf": [ { "$ref": "#/components/schemas/Event.order.paid" }, { "$ref": "#/components/schemas/Event.order.refunded" }, { "$ref": "#/components/schemas/Event.order.disputed" }, { "$ref": "#/components/schemas/Event.order.dispute_resolved" }, { "$ref": "#/components/schemas/Event.deal.stage_changed" }, { "$ref": "#/components/schemas/Event.subscription.created" }, { "$ref": "#/components/schemas/Event.subscription.updated" }, { "$ref": "#/components/schemas/Event.subscription.canceled" }, { "$ref": "#/components/schemas/Event.invoice.created" }, { "$ref": "#/components/schemas/Event.invoice.paid" }, { "$ref": "#/components/schemas/Event.invoice.voided" } ] }, "ProductList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "OrderList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "CustomerList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "RefundList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "CheckoutSessionList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "WebhookEndpointList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "EventList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "DealStage": { "enum": [ "opportunity", "proposal_sent", "negotiating", "won", "lost", "archived" ], "description": "opportunity, proposal_sent, negotiating, won (só pelo primeiro pagamento confirmado), lost, archived." }, "Deal": { "type": "object", "required": [ "id", "stage", "previous_stage", "amount", "currency", "product_id", "product_name", "expected_close_date", "owner", "lost_reason", "source", "source_reference", "order_id", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^opp_[0-9A-HJKMNP-TV-Z]{26}$" }, "stage": { "$ref": "#/components/schemas/DealStage" }, "previous_stage": { "enum": [ "opportunity", "proposal_sent", "negotiating", "won", "lost", "archived", null ], "description": "null quando a oportunidade acabou de nascer." }, "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (R 149,00 = 14900)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217" }, "product_id": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" }, "product_name": { "type": "string" }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "owner": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } } ] }, "lost_reason": { "type": [ "string", "null" ], "description": "Só em lost." }, "source": { "enum": [ "manual", "tracktor", "migracao" ] }, "source_reference": { "type": [ "string", "null" ] }, "order_id": { "type": [ "string", "null" ], "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$", "description": "O pedido do pagamento que a fechou; só em won." }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" } } }, "Event.deal.stage_changed": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "deal.stage_changed" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "deal", "customer" ], "properties": { "deal": { "$ref": "#/components/schemas/Deal" }, "customer": { "$ref": "#/components/schemas/OrderCustomer" } } } } }, "Touch": { "type": [ "object", "null" ], "description": "Uma visita com origem: os UTM, o clique do anúncio, de onde veio e a página de entrada (sem a query).", "properties": { "source": { "type": "string", "description": "utm_source" }, "medium": { "type": "string", "description": "utm_medium" }, "campaign": { "type": "string", "description": "utm_campaign" }, "content": { "type": "string", "description": "utm_content" }, "term": { "type": "string", "description": "utm_term" }, "fbclid": { "type": "string" }, "ttclid": { "type": "string" }, "gclid": { "type": "string" }, "referrer": { "type": "string", "format": "uri", "description": "Sem query nem fragmento." }, "landing_page": { "type": "string", "format": "uri", "description": "Sem query nem fragmento." }, "at": { "type": "string", "format": "date-time", "pattern": "Z$" } } }, "Attribution": { "type": "object", "required": [ "first_touch", "last_touch" ], "description": "De onde veio a venda. first_touch é a primeira visita da pessoa com origem conhecida; last_touch é a visita que pagou. null quando não se sabe.", "properties": { "first_touch": { "$ref": "#/components/schemas/Touch" }, "last_touch": { "$ref": "#/components/schemas/Touch" } } }, "InvoiceStatus": { "enum": [ "open", "paid", "void" ] }, "Invoice": { "type": "object", "required": [ "id", "object", "number", "subscription", "kind", "status", "amount", "currency", "period_start", "period_end", "due_date", "paid_at", "order", "hosted_invoice_url", "payment_token", "created_at", "livemode" ], "properties": { "id": { "type": "string", "pattern": "^in_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "invoice" }, "number": { "type": [ "string", "null" ], "description": "O número do documento (KMZ-…, KSA-…)." }, "subscription": { "type": "string", "pattern": "^sub_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "enum": [ "setup", "period" ], "description": "setup: a validação à entrada; period: um período da assinatura." }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (MZ 10,00 = 1000)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "period_start": { "type": [ "string", "null" ], "format": "date", "description": "Dia, AAAA-MM-DD." }, "period_end": { "type": [ "string", "null" ], "format": "date", "description": "Dia, AAAA-MM-DD." }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "Dia, AAAA-MM-DD." }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "order": { "type": [ "string", "null" ], "description": "O pedido (ord_…) que esta fatura gerou." }, "hosted_invoice_url": { "type": [ "string", "null" ], "format": "uri", "description": "A página pública da fatura (/c/), onde se paga e se descarrega o PDF." }, "payment_token": { "type": [ "string", "null" ], "description": "Só numa fatura em aberto. O token público com que o browser de quem paga pede o pagamento ao Payflow (o PIN do M-Pesa). Pode ir para o browser; a chave sk_ nunca." }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" } } }, "SubscriptionStatus": { "enum": [ "incomplete", "trialing", "active", "past_due", "unpaid", "canceled", "incomplete_expired" ], "description": "incomplete: à espera da validação; incomplete_expired: a validação não foi paga em 24 h; trialing: nos dias grátis; active: em dia; past_due: a fatura venceu; unpaid: passou a tolerância (suspensa); canceled: acabou." }, "Subscription": { "type": "object", "required": [ "id", "object", "status", "product", "customer", "price", "current_period_start", "current_period_end", "trial_end", "paid_through", "cancel_at_period_end", "canceled_at", "cancellation_reason", "payment_method", "automatic_collection", "credit", "billing_details", "latest_invoice", "metadata", "created_at", "livemode" ], "properties": { "id": { "type": "string", "pattern": "^sub_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "const": "subscription" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "product": { "type": "string", "pattern": "^prod_[0-9A-HJKMNP-TV-Z]{26}$" }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "null" } ] }, "price": { "type": "object", "required": [ "amount", "currency", "interval", "interval_days" ], "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Em subunidades da moeda (MZ 10,00 = 1000)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "interval": { "enum": [ "month", "year" ] }, "interval_days": { "type": "integer", "enum": [ 30, 365 ] } } }, "current_period_start": { "type": [ "string", "null" ], "format": "date", "description": "Dia, AAAA-MM-DD." }, "current_period_end": { "type": [ "string", "null" ], "format": "date", "description": "Dia, AAAA-MM-DD." }, "trial_end": { "type": [ "string", "null" ], "format": "date", "description": "Dia, AAAA-MM-DD." }, "paid_through": { "type": [ "string", "null" ], "format": "date", "description": "O último dia que está pago." }, "cancel_at_period_end": { "type": "boolean" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time", "pattern": "Z$" }, "cancellation_reason": { "type": [ "string", "null" ] }, "payment_method": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "mpesa", "card", "manual" ] }, "phone_last4": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}$", "description": "Só no M-Pesa." }, "card": { "type": [ "object", "null" ], "description": "Só no cartão, depois de paga a primeira fatura com um cartão que se pode voltar a cobrar.", "properties": { "brand": { "type": "string" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" } } } } }, "automatic_collection": { "type": "boolean", "description": "false: o Payflow emite as faturas mas não pede o pagamento sozinho." }, "credit": { "type": "integer", "minimum": 0, "description": "O que já foi pago e se desconta na próxima fatura de período (a validação)." }, "billing_details": { "$ref": "#/components/schemas/BillingDetails" }, "latest_invoice": { "anyOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" } } }, "BillingDetails": { "type": "object", "description": "Os dados que saem na fatura.", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_id": { "type": [ "string", "null" ], "maxLength": 40, "description": "O NUIT (MZ) ou o número fiscal." }, "address": { "type": [ "string", "null" ], "maxLength": 300 } } }, "PaymentMethodInput": { "oneOf": [ { "type": "object", "required": [ "type", "phone" ], "properties": { "type": { "const": "mpesa" }, "phone": { "type": "string", "description": "Moçambique, 84 ou 85, com 9 algarismos (ou 258…). Só em produtos MZN." } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "card", "description": "Só em produtos de uma moeda que aceita cartão (hoje ZAR). A primeira fatura paga-se na página dela (hosted_invoice_url), pela Paystack; as seguintes cobram-se sozinhas nesse cartão, no vencimento e nos dias de tentativa." } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "manual", "description": "As faturas emitem-se e pagam-se pela página delas, sem pedido automático." } } } ] }, "SubscriptionList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "InvoiceList": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Event.subscription.created": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "subscription.created" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "Event.subscription.updated": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "subscription.updated" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "subscription", "previous_status" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "previous_status": { "anyOf": [ { "$ref": "#/components/schemas/SubscriptionStatus" }, { "type": "null" } ] }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "Event.subscription.canceled": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "subscription.canceled" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "Event.invoice.created": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "invoice.created" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "subscription", "invoice" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "Event.invoice.paid": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "invoice.paid" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "subscription", "invoice" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "Event.invoice.voided": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "const": "invoice.voided" }, "api_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "livemode": { "type": "boolean" }, "data": { "type": "object", "required": [ "subscription", "invoice" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } } } }