@cactus-agents/payments

SDK framework-agnostic para providers de pagamento, deposito e saque multi-pais (PIX/SPEI/Wallet/CreditCard/Redirect, bank-list, chave PIX, contas MX/CHL).

Instalacao

pnpm add @cactus-agents/payments

Uso recomendado

Use createPaymentsFromClient quando voce ja estiver usando @cactus-agents/api-client:

import { createApiClient } from "@cactus-agents/api-client";
import { createPaymentsFromClient } from "@cactus-agents/payments";

const client = createApiClient({ baseUrl, tenant, language });
const payments = createPaymentsFromClient(client);

const providers = await payments.getPaymentProviders();
// providers.deposit, providers.withdraw

API publica

Exports principais:

• createPaymentsService(fetcher)
• createPaymentsFromClient(client)
• getPaymentProviders(), submitDeposit(payload), checkDepositStatus(transactionId), submitWithdraw(payload)
• getBankList(), getPixKey(), updatePixKey(payload), getMexBankAccount(), storeMexBankAccount(payload), getGenericBankAccount(), storeGenericBankAccount(payload)
• Transforms: transformPaymentProviders, transformDepositResponse, buildDepositPayload, buildWithdrawPayload, transformPixKey, buildPixKeyUpdatePayload, transformMexBankAccount, buildMexBankAccountPayload, transformGenericBankAccount, buildGenericBankAccountPayload, transformBankListItem, resolvePaymentIconUrl
• Helpers: isPixMethod, isSpeiMethod, isPhoneMethod, isRedirectMethod, isCheckoutPageMethod, isCreditCardFormMethod, isWalletMethod, isBankTransferWithdrawMethod, isExternalRedirectMethod, filterProvidersByCurrency

Tipos principais: PaymentProvider, PaymentProviders, DepositPayload, DepositResult, WithdrawPayload, WithdrawResult, PixKeyUpdatePayload, GenericBankAccountPayload, PaymentsService, PaymentsFetcher.

Referencia de exports: front-cactus-core/packages/payments/src/index.ts.

Metodos de pagamento suportados

Slug	Tipo	Pais	Descricao
pix, pixtopay, paybrokers, anspacepay, pay2free, riopag, paag, triopay, starkbank, efibank, genialbank, iugu	PIX-like	BR	QR code + copia-e-cola + polling
spei	SPEI	MX	Transferencia bancaria (CLABE)
oxxo	OXXO	MX	Pagamento em loja (barcode)
credit-card	Checkout Page	CHL/MX/PER/FIN	Iframe com gateway de pagamento
bank-transfer	Checkout Page	CHL	Iframe com gateway bancario
khipu	Checkout Page	CHL	Iframe Khipu
credit-card-2, credit-card-prontopaga	Card Form	CHL/MX	Formulario de cartao no frontend
wallet	Wallet/MACH	CHL	QR + deep-link (app_link) + polling
astropay	Redirect	Multi	Iframe AstroPay
worldline	Redirect	Multi	Iframe Worldline
prontopaga	Redirect	Multi	Iframe ProntoPaga
crypto	Redirect	Multi	Iframe crypto
webpay, bitfever	External Redirect	CHL	Abre nova aba
trio	Redirect	PER/FIN	Trio payments

Classificadores de metodo

isPixMethod("pix")              // true — QR + brCode + polling
isSpeiMethod("spei")            // true — CLABE + barcode
isPhoneMethod("astropay")       // true — requer telefone no saque
isRedirectMethod("astropay")    // true — iframe com URL
isCheckoutPageMethod("credit-card")  // true — iframe com checkout_page
isCreditCardFormMethod("credit-card-2")  // true — form de cartao
isWalletMethod("wallet")        // true — app_link + QR
isBankTransferWithdrawMethod("bank-transfer")  // true — conta bancaria generica
isExternalRedirectMethod("webpay")  // true — abre nova aba

Icones de pagamento

Os icones SVG dos metodos de pagamento ficam dentro do pacote em @cactus-agents/payments/icons/payments/. O transformPaymentProvider() aplica automaticamente resolvePaymentIconUrl() para converter o slug da API (ex: payments/pix) em URL absoluta (ex: /icons/payments/pix.svg).

No front-web-base, um plugin Vite (copyPaymentIcons) copia os icones do pacote para public/icons/ automaticamente no build e dev server.

import { resolvePaymentIconUrl } from "@cactus-agents/payments";

resolvePaymentIconUrl("payments/pix");  // "/icons/payments/pix.svg"
resolvePaymentIconUrl("payments/pix", "/assets");  // "/assets/payments/pix.svg"

DepositPayload

Shape canonico do payload aceito por submitDeposit() / buildDepositPayload(). O builder converte camelCase → snake_case antes de enviar pro BFF (POST /wallet/add-credit).

interface DepositPayload {
  userId: number;
  /** Valor em centavos. */
  creditAmount: number;
  paymentMethod: PaymentMethodSlug;
  currency: string;
  couponCode?: string;

  // ─── Tracking de marketing (paridade com legado Nuxt) ─────────────────
  // Anexados pelo template no `DepositModal` a partir do cookie
  // `cookie_tracking` + `_ga`. Detalhes em
  // → ../architecture/marketing-tracking.md
  utmCampaign?: string;
  utmSource?: string;
  utmMedium?: string;
  utmContent?: string;
  gaClientId?: string;

  /** Campos de cartao de credito (apenas `credit-card-2` / `credit-card-prontopaga`). */
  cardNumber?: string;
  cardName?: string;
  cardExpiryMonth?: string;
  cardExpiryYear?: string;
  cardCvv?: string;
}

:::caution Paridade estrita: src NAO vai no deposit Diferente do signup, o deposit nao envia src (first-touch source). Nenhum dos quatro projetos legado (base, 7k, cassino, vera) jamais incluiu src em /wallet/add-credit. Manter essa distincao evita quebrar dashboards de BI calibrados na atribuicao legacy.

Se voce ver um pull request adicionando utmSrc ou src ao DepositPayload / buildDepositPayload, bloqueie ate validar com BI/backoffice. Existe um teste em packages/payments/src/__tests__/transform.test.ts que falha intencionalmente caso o campo seja reintroduzido. :::

affiliation_code e app_source tambem nao sao enviados no deposit — so no signup.

Endpoints do PaymentsService

Metodo	Endpoint	Observacao
getPaymentProviders()	GET /payment-providers	Providers deposit/withdraw por pais
submitDeposit(payload)	POST /wallet/add-credit	Deposito (payload em snake_case)
checkDepositStatus(transactionId)	GET /wallet/charge/{transactionId}	Status do deposito (polling)
submitWithdraw(payload)	POST /new-withdraws	Saque (PIX, SPEI, bank, phone)
getBankList()	GET /bff/users/bank-list	Lista de bancos
getPixKey()	POST /pix-keys/user-key	BR — chave PIX do usuario
updatePixKey(payload)	POST /pix-keys/update-user-key-v2	BR — atualizar chave PIX
getMexBankAccount()	GET /mex-bank-accounts/user-account	MX — conta do usuario
storeMexBankAccount(payload)	POST /mex-bank-accounts/store	MX — salvar conta
getGenericBankAccount()	GET /bff/users/bank-account	CHL — conta bancaria generica
storeGenericBankAccount(payload)	POST /bff/users/bank-account	CHL — salvar conta generica

Integracao no front-web-base

Quando o token fica em cookie HttpOnly, as chamadas de deposito/saque passam por API routes no servidor. O template expoe:

• Rotas: api.payments.providers, api.payments.deposit, api.payments.deposit-status, api.payments.withdraw, api.payments.bank-list, api.payments.pix-key
• Store Zustand payments.ts (providers, estado do modal)
• Hook usePayments (submit deposit/withdraw, polling de status)
• Componentes: DepositModal, WithdrawModal, DepositForm, WithdrawForm, resultados PIX/SPEI/Wallet/CheckoutPage/CreditCard/Redirect/ExternalRedirect

Carteira e historico de transacoes usam @cactus-agents/wallet (rotas api.wallet.*).