paym (v1.0.0)

Centralized Daki payments service. Manages the full payment lifecycle (authorization → capture → refund → chargeback) through the Adyen (cards/digital wallets), Stark Bank (PIX) and Nubank (NuPay) gateways, notifying results via HTTP webhook and Kafka.

Service

Service Overview

paym (payments_backend) is Daki’s centralized payment service, built with Rails 7 (API-only). It manages the complete payment lifecycle — authorization, capture, refund and chargeback — through three gateways:

  • Adyen: credit/debit cards and digital wallets
  • Stark Bank: PIX
  • Nubank: NuPay

Every bill state transition is notified twice with the same payload: first via HTTP webhook to the URL registered by the caller at bill creation, then via Kafka on the bills.out topic.

API Endpoints

Authentication: user endpoints use Firebase JWT (jokr-jwt header); operational endpoints use API key (INTEGRATION_API_KEY); gateway webhooks use gateway-specific validation (Adyen HMAC-SHA256, Stark Bank SDK JWT).

MethodPathAuthPurpose
GET/—Healthcheck
GET/v1/payment_methodsJWTList the user’s payment methods
POST/v1/payment_methodsJWTCreate a payment method (PIX, encrypted card, digital wallet, click-to-pay, NuPay)
DELETE/v1/payment_methods/:idJWTRemove a payment method
GET/v1/payment_methods/availableJWTList available payment types
GET/v1/payment_methods/extraJWTExtra payment methods per platform
POST/v1/billsJWTCreate a bill (charge) — includes payment data, user data, webhook config and full fraud.order block for anti-fraud evaluation
POST/v1/bills/:id/captureAPI keyCapture a pre-authorized payment
POST/v1/bills/:id/refundAPI keyRefund a payment (full or partial)
POST/v1/bills/:id/cancelAPI keyCancel a pre-authorization
POST/v1/adyen/webhookHMACInbound Adyen notifications (AUTHORISATION, CAPTURE, REFUND, CHARGEBACK…)
POST/v1/stark_bank/webhookSDK JWTInbound Stark Bank PIX notifications
POST/v1/nubank/webhookrequest validationInbound NuPay payment notifications
POST/v1/nubank/webhook/refundsrequest validationInbound NuPay refund notifications
POST/v1/integrations/payment_methodsAPI keyServer-to-server payment method creation

Events Consumed

  • seller_order.delivered / seller_order.canceled (Kafka topic seller_orders.out, consumer group payments-seller-orders-consumer): reacts to the Daki channel (own marketplace) order lifecycle to automatically capture or cancel the payment pre-authorization. Only messages with meta.version >= 2 and payload.external_source_name == "daki" are processed:
    • seller_order.delivered → notifies anti-fraud and captures the bill (skipped when unpicked_items is non-empty or the bill is not pre_authorized)
    • seller_order.canceled → cancels the bill (ignored when the bill does not exist or is already paid)

Events Produced

  • bill.* (Kafka topic bills.out, keyed by bill id): published on every bill state transition — pre_authorized, waiting, paid, failed, canceled, chargeback, partially_refunded, refunded, failed_refund — plus fraud_detected from the PIX fraud check. Refund events are published with a 2-minute delay.

Non-broker Integrations

  • HTTP webhook outbound: POST to the URL stored on the bill (config.webhook at creation) on every state transition, same payload as Kafka
  • frauds_backend: fire-and-forget HTTP notifications (notify_approved / notify_delivered)
Edit this page