Medusa.js

Integre a Cost+ como provedor de pagamento na sua loja Medusa.js v2. O plugin oficial costplus-medusa regista um provedor de pagamento Medusa separado para cada método de pagamento Cost+, utiliza o fluxo de Página de Pagamento Alojada, e verifica cada alteração de estado contra a API Cost+ — totalmente compatível com PCI DSS.

Pré-requisitos

• Conta de comerciante Cost+ ativa
• Medusa.js 2.14.2 ou superior
• Node.js 22
• Acesso a PostgreSQL através do DATABASE_URL da Medusa
• Um URL público HTTPS para o backend Medusa (necessário para webhooks)
• Um checkout no storefront que passe cart_id ao iniciar a sessão de pagamento

Métodos de Pagamento Suportados

Cada provedor cria uma encomenda Cost+ para exatamente um método de pagamento, pelo que as opções de checkout do storefront permanecem alinhadas com o fluxo de redirecionamento da página de pagamento alojada Cost+.

1. Instalar o Plugin

Instale o pacote no seu projeto de backend Medusa:

npm install costplus-medusa

2. Registar o Plugin e o Provedor

Adicione o plugin e o provedor de pagamento ao seu medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

module.exports = defineConfig({
  plugins: [
    {
      resolve: "costplus-medusa",
      options: {},
    },
  ],
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "costplus-medusa/providers/costplus",
            id: "costplus",
            options: {},
          },
        ],
      },
    },
  ],
})

Reinicie o backend Medusa para que o novo plugin e provedor sejam carregados.

3. Configurar no Admin

No Medusa Admin, abra Cost+ (rota /app/costplus) e configure:

• API Key — a sua chave API de comerciante do Portal do Comerciante (Websites → o seu website → Integration)
• Checkout Expiry — tempo limite em minutos (enviado para Cost+ como duração ISO-8601, ex.: 5 → PT5M, predefinição é 5 minutos)
• Manual Capture — opcional, autoriza pagamentos com cartão sem captura imediata
• Debug Logging — opcional, regista pedidos e respostas da API para resolução de problemas

Na mesma página Cost+ do Admin, ative os métodos de pagamento que pretende disponibilizar para cada região:

• Cost+ Credit / Debit Card
• Cost+ Apple Pay
• Cost+ Google Pay
• Cost+ Vipps MobilePay

4. Integração no Storefront

Ao iniciar uma sessão de pagamento Cost+, passe o cart_id da Medusa em data:

await sdk.store.payment.initiatePaymentSession(paymentCollection.id, {
  provider_id: "pp_costplus-credit-card_costplus",
  data: {
    cart_id: cart.id,
    return_url: `${origin}/${countryCode}/checkout/costplus/return?cart_id=${cart.id}`,
    failure_url: `${origin}/${countryCode}/checkout?step=payment&costplus_cancelled=1&cart_id=${cart.id}`,
  },
})

Depois da sessão ser criada, redirecione o cliente para payment_session.data.costplus_payment_url.

A rota de sucesso predefinida é /checkout/costplus/return?cart_id={cart_id} — essa página deve invocar o endpoint complete-cart da Medusa e depois mostrar a página de confirmação da encomenda. O URL de falha deve devolver o cliente ao passo de pagamento sem completar o carrinho.

Listar métodos de pagamento a partir da Store API

Liste os métodos de pagamento a partir da Store API do Medusa em vez de codificar os IDs dos provedores Cost+ na sua loja. Se a loja armazenar em cache /store/payment-providers, use no-store ou invalide o cache após alterações de método no Admin, para que os métodos desativados desapareçam imediatamente do checkout.

5. Webhooks

O plugin regista automaticamente um endpoint de webhook em /hooks/payment/{identifier}_costplus. O URL do backend Medusa tem de estar publicamente acessível via HTTPS para que a Cost+ possa entregar atualizações de estado assíncronas.

Se as encomendas permanecerem pendentes muito depois do tempo de expiração configurado, isso indica um problema com a entrega do webhook ou o fluxo de retorno, e não com a definição de expiração em si.

6. Segurança e Armazenamento de Definições

A chave API é encriptada antes de ser armazenada na base de dados da Medusa. Defina COSTPLUS_SETTINGS_SECRET em produção:

COSTPLUS_SETTINGS_SECRET=your-strong-secret

Se COSTPLUS_SETTINGS_SECRET não estiver definida, o plugin recorre ao COOKIE_SECRET ou JWT_SECRET da Medusa.

7. Testar e Lançar

O ambiente Cost+ é determinado pela chave API — uma chave de website sandbox corre em modo de teste, uma chave de website de produção corre em modo live (sem URL sandbox separado). Efetue algumas transações de teste para verificar fluxos com sucesso, cancelados e expirados antes de entrar em produção.

Suporte

Precisa de ajuda? Contacte a nossa equipa de suporte em support@costplus.io.