Quick Start
Start accepting payments in under 5 minutes with this step-by-step guide.
Prerequisites
- A Cashier merchant account
- An API key (get one from the Dashboard)
- A server that can make HTTPS requests
1
Get Your API Key
Log into the Dashboard, navigate to your merchant, and generate an API key. Your key will look like:
Example API Key
text
sk_live_a1b2c3d4e5f6g7h8i9j0...Important: Save your API key immediately - it's only shown once!
2
Create a Checkout Session
From your server, create a checkout session to get a payment URL:
Create Checkout Session
bash
curl -X POST https://cashier.flowpayment.net/api/v1/checkout \
-H "X-API-Key: sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 99.90,
"currency": "BRL",
"description": "Premium Subscription",
"success_url": "https://yoursite.com/success",
"cancel_url": "https://yoursite.com/cancel"
}'Response:
Response
json
{
"id": "cs_abc123xyz",
"checkout_url": "https://cashier-checkout.s-interio.com/checkout/cs_abc123xyz",
"expires_at": "2024-12-12T15:30:00Z"
}3
Redirect Your Customer
Redirect the customer to the checkout_url. They'll see a hosted payment page with PIX, credit card, and other options:
Redirect Example
javascript
// Node.js/Express example
app.post('/create-checkout', async (req, res) => {
const session = await createCheckoutSession({
amount: 99.90,
currency: 'BRL',
success_url: 'https://yoursite.com/success',
cancel_url: 'https://yoursite.com/cancel'
});
// Redirect customer to hosted checkout
res.redirect(session.checkout_url);
});4
Handle the Result
After payment, the customer is redirected to your success_urlor cancel_url. To reliably track payment status, set up a webhook:
With Webhook
json
// Add notification_url to your checkout request
{
"amount": 99.90,
"currency": "BRL",
"success_url": "https://yoursite.com/success",
"cancel_url": "https://yoursite.com/cancel",
"notification_url": "https://yoursite.com/webhooks/cashier"
}Webhook Handler
javascript
// Handle webhook on your server
app.post('/webhooks/cashier', express.json(), (req, res) => {
const { event, data } = req.body;
if (event === 'payment.success') {
// Payment successful! Fulfill the order
console.log('Payment received:', data.payment_id);
fulfillOrder(data);
}
res.status(200).send('OK');
});Full Integration Example
Here's a complete Node.js example putting it all together:
Complete Integration
javascript
const express = require('express');
const axios = require('axios');
const app = express();
app.use(express.json());
const CASHIER_API_KEY = process.env.CASHIER_API_KEY;
const CASHIER_API_URL = 'https://cashier.flowpayment.net';
// Create checkout session and redirect
app.post('/checkout', async (req, res) => {
try {
const response = await axios.post(
`${CASHIER_API_URL}/api/v1/checkout`,
{
amount: req.body.amount,
currency: 'BRL',
description: req.body.description,
customer: {
name: req.body.customerName,
email: req.body.customerEmail,
document: req.body.customerDocument
},
success_url: 'https://yoursite.com/success?session_id={SESSION_ID}',
cancel_url: 'https://yoursite.com/cancel',
notification_url: 'https://yoursite.com/webhooks/cashier',
metadata: {
order_id: req.body.orderId
}
},
{
headers: {
'X-API-Key': CASHIER_API_KEY,
'Content-Type': 'application/json'
}
}
);
// Store session ID in your database
await saveCheckoutSession(response.data.id, req.body.orderId);
// Redirect to hosted checkout
res.redirect(response.data.checkout_url);
} catch (error) {
console.error('Checkout error:', error.response?.data);
res.status(500).json({ error: 'Failed to create checkout' });
}
});
// Success page
app.get('/success', async (req, res) => {
const sessionId = req.query.session_id;
// Show success message to customer
res.send('Payment successful! Thank you for your order.');
});
// Webhook handler
app.post('/webhooks/cashier', async (req, res) => {
const { event, data } = req.body;
// Respond immediately
res.status(200).send('OK');
// Process event
switch (event) {
case 'payment.success':
await markOrderAsPaid(data.metadata?.order_id);
await sendConfirmationEmail(data.customer.email);
break;
case 'payment.failed':
await markOrderAsFailed(data.metadata?.order_id);
break;
}
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});