ccashcow

CCashCow 💳💲🐄

Accept credit cards and cryptocurrencies. Dead simple user payment system so simple a caveman cow could do it.

CCashCow is a small app that sits between your application and the payment processors it uses. CCashCow offloads as much of the logic and user-interaction as possible to the forms maintained by and hosted on the payment processors themselves. Your app in turn offloads to CCashCow everything but the bare minimum needed for your app to accept payments. The end result is a system that's straightforward for developers and users, secure, easy to mantain, and as customizable as possible without introducing too much complexity.

Built and mantained by Ptorx and other Xyfir projects.

Features

• Accept credit cards and debit cards with Square
• Accept popular cryptocurrencies like Bitcoin with Coinbase Commerce
• Configurable fiat currency
• No dependencies other than Node and what npm will install
  • Older Node versions not actively supported
• No database needed
  • Data is saved on disk in simple JSON files
• Standalone server and web client
  • Easy integration into new and existing applications of any stack
• JSON Web Tokens (JWT)
  • Secure and easy communication between your app and CCashCow
• Easy theming via Material-UI

Install

As simple as CCashCow is, you'll still need to download, configure, build, and integrate it into your app. We've made it just about as easy as it could possibly be.

Note #1: If your system does not yet have Node installed, start with nvm (or nvm for Windows).

Note #2: You may alternatively download CCashCow through npm (see here), however this is not currently the recommended installation method. In the future we'll likely have a CLI tool available through npm to make configuring, running, and managing CCashCow instances easier.

Server

git clone https://github.com/Xyfir/ccashcow.git
cd ccashcow/server
npm install
touch .env

Now open up ccashcow/server/.env in your editor and fill out the values. See the CCashCow.Env.Common and CCashCow.Env.Server interfaces in types/ccashcow.d.ts for expected environment variables. Format is KEY=VALUE (PORT=1234, NAME="CCashCow", etc).

npm run build
npm run start # or launch ./dist/app.js however you like

At this point the setup is based on your environment and what your needs are. Probably you'll run the server with pm2 and put Node behind Nginx or Apache.

Web Client

cd ../web
npm install
touch .env

Now open up ccashcow/web/.env in your editor and fill out the values. See the CCashCow.Env.Common and CCashCow.Env.Web interfaces in types/ccashcow.d.ts for expected environment variables.

npm run build

Integration Into Your App

This part is largely up to you, so it's important to understand the flow of data between your app and CCashCow:

1. Your app sends users to CCashCow's payment form either by user action or automatically through a forced redirection. You'll pass a JWT whose payload contains basic payment information, like an identifier, amount, and accepted methods.
2. CCashCow will handle everything until there's a successful purchase or until the user quits back to your app, at which point it will redirect the user back to your app with the JWT in the URL based on your configuration. The JWT will either be the original one you sent, or a new one generated by CCashCow containing the full payment data.

To be a bit more specific:

1. You'll need to be able to sign and verify/decode JSON Web Tokens via jsonwebttoken or the equivalent in your preferred language.
2. Somewhere in your app you'll allow the user to select products they wish to purchase.
3. Your app will save this data somehow, linking it to a unique id.
4. Your app will send the user to CCashCow with a JWT containing that id, the total amount of the purchase, and the accepted payment methods.
5. At some point the user will be redirected back to your app with the JWT in the url as you configured. Verify and decode this JWT to retrieve the payment information.
6. Using the JWT's payload, your app will check if the payment as been paid, and if your app has not already fulfilled the user's order it will do so then.

Payment JWT Payload

Check the CCashCow.Payment interface. Your app should only ever send a JWT containing id, amount, and methods; everything else will be added by CCashCow and sent back to your app with the user later. To check if a payment has been paid, all you have to do is check that paid is a number, and not undefined. Other values sent back to your app like method or squareTransactionId can be ignored unless you have some other use for them.