Convex component for ePayco that handles credit cards, PSE, cash vouchers, Daviplata, SafetyPay, and subscriptions with reactive tables and webhook verification
npm install @pulgueta/epayco-convexA typed Convex component for integrating ePayco, Colombia's payment aggregator, supporting credit/debit cards, PSE bank transfers, cash vouchers (Efecty, Baloto), Daviplata, SafetyPay, and recurring subscriptions. It reimplements ePayco's wire protocol using Web platform APIs (fetch, Web Crypto) without Node.js dependencies, so it runs natively in the Convex V8 runtime. Payment state is persisted to component-managed tables and exposed as reactive queries, eliminating polling for async payment confirmations.
The epayco-convex component exposes a chargeCreditCard method on the EPayco client that you call from a Convex action. It tokenizes the card, creates a customer record, charges the token, and persists the result to a reactive Convex table. The listTransactions query then returns live status updates to your React UI without polling.
Use the createPseTransaction method from @pulgueta/epayco-convex inside a Convex action. PSE payments are async, so ePayco sends a confirmation webhook when the bank debit settles. The component verifies the webhook signature and updates the transaction row in Convex, which any subscribed query picks up automatically.
Call createPlan to define a billing plan, then createSubscription to attach a customer to it. Both methods run inside Convex actions via the EPayco client. The component stores subscription state locally so you can query active subscriptions with getActiveSubscription from a reactive Convex query.
The epayco-convex component includes built-in webhook handling with signature verification using the EPAYCO_P_CUST_ID_CLIENTE and EPAYCO_P_KEY environment variables. When ePayco posts a confirmation, the component checks the signature and updates the corresponding transaction row in Convex, so you never need to implement the verification logic yourself.
No. The @pulgueta/epayco-convex component reimplements ePayco's wire protocol using Web platform APIs (fetch and Web Crypto) because Convex components run in the V8 runtime, not Node. JWT login, AES-128-CBC encryption for PSE, and the apify Basic-auth flow are all ported field-for-field from epayco-sdk-node@1.4.4 and verified byte-identical in the test suite.
The @pulgueta/epayco-convex component supports credit and debit card charges, PSE online bank transfers, cash vouchers (Efecty, Baloto, Gana), Daviplata wallet payments with OTP confirmation, SafetyPay, recurring plans and subscriptions, and split payments for marketplace disbursement.
Every mutating method on the EPayco client accepts a userId parameter that you resolve from your own auth layer inside the Convex action before calling the component. The component files the transaction, token, customer, or subscription under that userId. Local read methods like listTransactions and getActiveSubscription then filter by it, so one user never sees another's data.
Yes. Credentials can be passed directly to the EPayco constructor via publicKey, privateKey, testMode, and lang parameters, which take precedence over the EPAYCO_PUBLIC_KEY and EPAYCO_PRIVATE_KEY environment variables. This lets you instantiate a separate EPayco client per tenant, each with its own keys.
Methods that call the ePayco API live, such as chargeCreditCard, createPseTransaction, getCharge, and getPlan, must run inside a Convex action. Methods that read from the component's synced Convex tables, such as listTransactions, getLocalTokens, and listLocalBanks, run inside a Convex query and are fully reactive.