Criar um provedor - pagamentos.dev

Visão geral

Provedores são a espinha dorsal do pagamentos.dev. Cada provedor implementa a interface Provider e expõe os recursos (clientes, cobranças, checkout, webhooks) que o SDK gerencia de forma unificada. Para criar um novo provedor, você precisa:

Definir os métodos de pagamento suportados
Implementar os recursos (clientes, cobranças, checkout, webhooks)
Criar a função factory que instancia o provedor
Exportar os tipos para os consumidores

Estrutura básica

src/provider/meu-provedor/
├── meu-provedor.ts    # Implementação principal
└── ...                # Testes, tipos auxiliares, etc.

Passo a passo

1. Defina os métodos de pagamento suportados

// src/provider/meu-provedor/meu-provedor.ts
import type { MetodoPagamento } from 'pagamentos'

export type MeuProvedorSupportedMethods = 'pix' | 'boleto'

2. Defina os recursos suportados

Cada provedor declara quais operações de cada recurso ele implementa:

const MEU_PROVEDOR_RESOURCES = {
  clientes: ['create', 'get', 'update', 'list', 'delete'] as const,
  cobrancas: ['create', 'get', 'update', 'list', 'cancel'] as const,
  checkout: ['create'] as const,
  webhooks: [
    'signatureHeader',
    'verifySecret',
    'verifySignature',
    'decodePayload',
    'verifyAndDecode'
  ] as const
} as const

3. Implemente os recursos

Cada recurso é um objeto com funções que seguem os tipos definidos no SDK:

import { Provider } from 'pagamentos'
import type { Cliente, Cobranca, Checkout } from 'pagamentos'

const resources = {
  clientes: {
    async create(input) {
      const response = await fetch('https://api.meuprovedor.com/clientes', {
        method: 'POST',
        headers: { Authorization: `Bearer ${apiKey}` },
        body: JSON.stringify(input)
      })
      return response.json() as Promise<Cliente>
    },
    async get(id) {
      const response = await fetch(
        `https://api.meuprovedor.com/clientes/${id}`,
        { headers: { Authorization: `Bearer ${apiKey}` } }
      )
      return response.json() as Promise<Cliente>
    },
    async update(id, input) { /* ... */ },
    async list(input) { /* ... */ },
    async delete(id) { /* ... */ }
  },
  cobrancas: {
    async create(input) {
      // Implemente a criação de cobrança
    },
    async get(id) { /* ... */ },
    async update(id, input) { /* ... */ },
    async list(input) { /* ... */ },
    async cancel(id) { /* ... */ }
  },
  checkout: {
    async create(input) { /* ... */ }
  },
  webhooks: {
    signatureHeader: 'x-meu-provedor-signature',
    verifySecret(secretFromQuery, expectedSecret) {
      return secretFromQuery === expectedSecret
    },
    async verifySignature(rawBody, signatureFromHeader, publicHmacKey) {
      // Valide a assinatura do webhook
    },
    async decodePayload(payload) {
      // Decodifique o payload do webhook para o formato do SDK
    },
    async verifyAndDecode({ rawBody, signatureFromHeader, publicHmacKey }) {
      // Valide e decodifique em um único passo
    }
  }
}

4. Crie o tipo do provedor

export type MeuProvedor<ID extends string = 'default'> = Provider<
  ID,
  'meuProvedor',
  MeuProvedorSupportedMethods,
  MeuProvedorWebhookPayload,
  typeof MEU_PROVEDOR_RESOURCES
>

5. Crie a função factory

export type MeuProvedorParams = {
  id?: string
  apiKey: string
  signingSecret?: string
  taxa?: import('pagamentos').Taxa
}

export function meuProvedor<const ID extends string>(
  params: MeuProvedorParams & { id: ID }
): MeuProvedor<ID>
export function meuProvedor(
  params?: MeuProvedorParams & { id?: never }
): MeuProvedor<'default'>
export function meuProvedor<ID extends string = 'default'>(
  params: MeuProvedorParams = {} as MeuProvedorParams
): MeuProvedor<ID> {
  return new Provider({
    id: params.id,
    provider: 'meuProvedor',
    taxa: params.taxa,
    resources,
    webhookConfig: params.signingSecret
      ? { signingSecret: params.signingSecret }
      : undefined
  }) as MeuProvedor<ID>
}

Exemplo real: Mock Provider

Consulte a implementação completa do Mock Provider para ver um exemplo funcional de provedor com suporte a todos os métodos de pagamento e webhooks.

Boas práticas

Tratamento de erros

Converta os erros da API do provedor para Error do JavaScript:

async get(id: string) {
  const response = await fetch(`https://api.provedor.com/${id}`)

  if (!response.ok) {
    throw new Error(
      `MeuProvedor: erro ao buscar cliente (${response.status})`
    )
  }

  return response.json()
}

Taxas

Se o provedor for usado com roteamento inteligente, aceite uma configuração de taxa opcional:

export type MeuProvedorParams = {
  taxa?: Taxa // Aceita flat, percentage ou async
  // ...
}

Webhooks

Para que o handler automático de webhooks funcione, implemente:

signatureHeader: nome do header que contém a assinatura
verifyAndDecode: valida a assinatura e decodifica o payload
Aceite signingSecret nos parâmetros e passe no webhookConfig

Tipagem forte

Exporte os tipos do seu provedor para que os consumidores tenham autocomplete:

export type { MeuProvedor, MeuProvedorParams, MeuProvedorSupportedMethods }

Publicando

Crie um pacote npm com o nome pagamentos-provider-nome
Declare pagamentos como peerDependency
Publique no npm

{
  "name": "pagamentos-provider-meu-provedor",
  "peerDependencies": {
    "pagamentos": "^0.x"
  }
}

​Visão geral

​Estrutura básica

​Passo a passo

​1. Defina os métodos de pagamento suportados

​2. Defina os recursos suportados

​3. Implemente os recursos

​4. Crie o tipo do provedor

​5. Crie a função factory

​Exemplo real: Mock Provider

​Boas práticas

​Tratamento de erros

​Taxas

​Webhooks

​Tipagem forte

​Publicando