Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 22.x or higher installed
  • A Stripe account (sign up for free)
  • Your Stripe API keys (test mode recommended for development)
  • A code editor and terminal

​
Installation

1

Clone or download the project

If you haven’t already, get the project files and navigate to the directory:
cd path/to/api
2

Install dependencies

Install all required packages using your preferred package manager:
npm install
This installs:
  • Express server framework
  • Stripe Node.js SDK (v11.6.0)
  • CORS and body parsing middleware
  • Swagger for API documentation
  • Development tools (nodemon, jest)
3

Configure environment variables

Create a .env file in the root directory by copying the example:
cp .env.example .env
Open .env and add your Stripe credentials:
.env
# Stripe secret key (required)
STRIPE_SECRET_KEY=sk_test_your_actual_secret_key

# Stripe webhook signing secret (required for webhooks)
STRIPE_WEBHOOK_SECRET=whsec_your_actual_webhook_secret

# API configuration
PORT=3000
PUBLIC_API_URL=http://localhost:3000
NODE_ENV=development
Get your test API keys from the Stripe Dashboard. Use test keys (starting with sk_test_) for development.
Never commit your .env file to version control. The .env.example file is provided as a template only.
4

Start the development server

Launch the API server with hot reloading:
npm run dev
You should see:
🚀 Server running on port 3000
The API is now available at http://localhost:3000
5

Verify installation

Open your browser and navigate to the Swagger documentation:
http://localhost:3000/doc
You should see the interactive API documentation with all available endpoints.

​
Make Your First API Call

Let’s create a customer in your Stripe account:
1

Create a customer

Use curl to create a new customer:
curl -X POST http://localhost:3000/api/customers \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+1234567890"
  }'
Or use Postman/Insomnia with this request body:
{
  "email": "[email protected]",
  "name": "John Doe",
  "phone": "+1234567890"
}
2

Review the response

You should receive a successful response:
{
  "status": true,
  "statusCode": 201,
  "message": "Cliente creado correctamente",
  "data": {
    "id": "cus_xxxxxxxxxxxxx",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+1234567890"
  }
}
Save the id field - you’ll need it for creating payments.
3

Verify in Stripe Dashboard

Log into your Stripe Dashboard and navigate to Customers. You should see your newly created customer.

​
Create a Payment

Now let’s create a payment intent for the customer: 
curl -X POST http://localhost:3000/api/payments \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xxxxxxxxxxxxx",
    "amount": 50,
    "payment_method": "pm_card_visa"
  }'
The amount is in your currency’s base unit (e.g., dollars/euros). The API automatically converts it to cents (multiplies by 100) before sending to Stripe.
Expected response: 
{
  "status": true,
  "statusCode": 201,
  "message": "Intento de pago creado correctamente",
  "data": {
    "id": "pi_xxxxxxxxxxxxx",
    "amount": 5000,
    "currency": "eur",
    "status": "requires_confirmation",
    "customer": "cus_xxxxxxxxxxxxx"
    // ... additional Stripe payment intent fields
  }
}

​
Next Steps

Authentication

Learn about API keys and security best practices

API Reference

Explore all available endpoints and parameters

Webhooks

Set up webhook handling for real-time events

Error Handling

Understand error responses and status codes

​
Testing with Stripe Test Cards

Stripe provides test card numbers for different scenarios:
Card NumberScenario
4242424242424242Successful payment
4000000000000002Card declined
4000002500003155Requires authentication (3D Secure)
Use any future expiry date and any 3-digit CVC for testing. For more test cards, see the Stripe Testing Documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us