Kover Payments Online
API REST de pagamentos — MB WAY · Multibanco · Cartão · PayPal · Webhooks
📖 Introdução
A Kover Payments API permite integrar múltiplos métodos de pagamento (MB WAY, Multibanco, Cartão de Crédito e PayPal) em qualquer plataforma através de uma única API REST. Todas as respostas são em JSON.
| Propriedade | Valor |
|---|---|
| Base URL | https://apidev.comsoftweb.pt/api/v1 |
| Formato | JSON (application/json) |
| Autenticação | API Key no body ou header x-api-key |
| Versão | v1 |
🔑 Autenticação
Todos os pedidos requerem uma API Key. Pode ser enviada de 3 formas:
Header
x-api-key: csw_live_xxxxxxxxxxxxxxxx
Body (JSON)
{
"kover_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"shopshop_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"x_studio_key_api": "csw_live_xxxxxxxxxxxxxxxx"
}
As API Keys são criadas no backoffice em Gestão API. Prefixo
csw_live_ para produção, csw_test_ para sandbox.
💳 Métodos de Pagamento
MB WAY
Pagamento instantâneo via app
Multibanco
Referência ATM (entidade + ref)
Cartão
VISA / Mastercard via SIBS SPG
PayPal
Sandbox e Live
🚀 Criar Pagamento (Endpoint Unificado)
Um único endpoint aceita todos os métodos. O campo *_metodo_pagamento determina o processador.
POST
/api/v1/payments
API Key no body
Parâmetros comuns obrigatórios
| Campo | Tipo | Descrição |
|---|---|---|
| kover_key_api | string | API Key da organização (ou x_studio_key_api / shopshop_key_api) |
| kover_metodo_pagamento | string | MBWAY · MULTIBANCO · CREDIT_CARD · PAYPAL |
| merchantTransactionId | string | ID único da transação (max 50 chars) |
| amount | number | Valor em EUR (positivo) |
| currency | string | EUR (default) · USD · GBP |
📱 MB WAY
POST
/api/v1/payments
kover_metodo_pagamento: "MBWAY"
Exemplo de pedido
{
"kover_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"kover_metodo_pagamento": "MBWAY",
"merchantTransactionId": "ORDER-001",
"amount": 29.99,
"currency": "EUR",
"phoneNumber": "351912345678",
"description": "Encomenda #001"
}
phoneNumber aceita 351912345678 ou 351#912345678.
🏦 Multibanco
POST
/api/v1/payments
kover_metodo_pagamento: "MULTIBANCO"
{
"kover_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"kover_metodo_pagamento": "MULTIBANCO",
"merchantTransactionId": "ORDER-002",
"amount": 89.50,
"currency": "EUR",
"expiryDays": 3,
"description": "Fatura INV-002"
}
Resposta
{
"success": true,
"data": {
"entity": "54355",
"reference": "123 456 789",
"amount": 89.50,
"expiryDate": "2026-04-24T23:59:59Z"
}
}
💳 Cartão de Crédito / Débito
POST
/api/v1/payments
kover_metodo_pagamento: "CREDIT_CARD"
{
"kover_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"kover_metodo_pagamento": "CREDIT_CARD",
"merchantTransactionId": "ORDER-003",
"amount": 149.00,
"currency": "EUR",
"customerName": "João Silva",
"customerEmail": "joao@empresa.pt",
"redirectUrl": "https://minha-loja.pt/sucesso",
"description": "Compra online"
}
Resposta
{
"success": true,
"data": {
"transactionId": "CARD_1745...",
"paymentUrl": "https://spg.sibs.pt/...",
"jwt": "eyJhbGci..."
}
}
🅿️ PayPal
POST
/api/v1/payments
kover_metodo_pagamento: "PAYPAL"
{
"kover_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"kover_metodo_pagamento": "PAYPAL",
"merchantTransactionId": "ORDER-004",
"amount": 59.90,
"currency": "EUR",
"customerEmail": "cliente@empresa.pt",
"redirectUrl": "https://minha-loja.pt/paypal/sucesso"
}
🔌 Integração Odoo
POST
/api/v1/odoo/webhook
Handshake — devolve config completa
{
"x_studio_key_api": "csw_live_xxxxxxxxxxxxxxxx"
}
POST
/api/v1/payments
Criar pagamento via Odoo
{
"x_studio_key_api": "csw_live_xxxxxxxxxxxxxxxx",
"x_studio_metodo_pagamento": "MBWAY",
"merchantTransactionId": "SO-001",
"amount": 50.00,
"phoneNumber": "351912345678"
}
🛍️ Integração ShopShop
POST
/api/v1/shopshop/webhook
Handshake — devolve config completa
{
"shopshop_key_api": "csw_live_xxxxxxxxxxxxxxxx"
}
⚡ Kover API (Genérica)
Integração white-label para qualquer plataforma — Magento, WooCommerce, Laravel, apps custom.
POST
/api/v1/kover/webhook
Handshake — devolve config completa
{
"kover_key_api": "csw_live_xxxxxxxxxxxxxxxx"
}
GET
/api/v1/kover/payment-status/:merchantTransactionId
Estado de pagamento (público)
GET /api/v1/kover/payment-status/ORDER-001
{
"success": true,
"data": {
"kover_payment_status": "Success",
"kover_amount": 29.99,
"kover_currency": "EUR"
}
}
📊 Códigos de Estado HTTP
| Código | Significado |
|---|---|
| 200 | Sucesso |
| 201 | Criado com sucesso |
| 400 | Pedido inválido — campo em falta ou formato errado |
| 401 | API Key inválida ou inativa |
| 403 | Organização suspensa ou cancelada |
| 404 | Recurso não encontrado |
| 429 | Rate limit excedido |
| 500 | Erro interno do servidor |
⚠️ Formato de Erros
{
"success": false,
"message": "Descrição do erro",
"errors": ["detalhe 1", "detalhe 2"]
}
Kover Payments · COMSOFTWEB, SISTEMAS INFORMÁTICOS, LDA · 2026