Skip to main content
This guide walks you through the complete payment workflow using the Stripe Payments API, from creating a customer to confirming a payment and handling refunds.

​
Overview

The complete payment flow consists of the following steps:
  1. Create a customer
  2. Create a card token
  3. Assign the card to the customer
  4. Create a payment intent
  5. Confirm the payment
  6. Handle refunds (optional)
1
Step 1: Create a Customer
2
First, create a customer in Stripe with their basic information.
3
curl -X POST http://localhost:3000/api/customers \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+34612345678"
  }'
4
Expected Response:
5
{
  "status": true,
  "message": "Cliente creado correctamente",
  "data": {
    "id": "cus_xxxxxxxxxx",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+34612345678"
  }
}
6
Save the id from the response - you’ll need it for subsequent steps.
7
Step 2: Create a Card Token
8
Tokenize the customer’s card details securely. This converts sensitive card information into a one-time-use token.
9
curl -X POST http://localhost:3000/api/cards \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2025,
    "cvc": "123"
  }'
10
Expected Response:
11
{
  "status": true,
  "message": "Tarjeta tokenizada correctamente",
  "data": {
    "token_id": "tok_xxxxxxxxxx",
    "card_id": "card_xxxxxxxxxx",
    "card_brand": "visa",
    "card_last4": "4242"
  }
}
12
The token_id is single-use and expires after a short time. Use it immediately in the next step.
13
Step 3: Assign Card to Customer
14
Attach the tokenized card to the customer account.
15
curl -X POST http://localhost:3000/api/cards/assign \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "cus_xxxxxxxxxx",
    "source": "tok_xxxxxxxxxx"
  }'
16
Expected Response:
17
{
  "status": true,
  "message": "Tarjeta añadida con éxito",
  "data": {
    "cardId": "card_xxxxxxxxxx",
    "brand": "visa",
    "last4": "4242"
  }
}
18
Step 4: Create a Payment Intent
19
Create a payment intent with the amount and payment method. The amount is automatically converted to cents (multiplied by 100) by the API.
20
curl -X POST http://localhost:3000/api/payments \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xxxxxxxxxx",
    "amount": 50.00,
    "payment_method": "card_xxxxxxxxxx"
  }'
21
Expected Response:
22
{
  "status": true,
  "message": "Intento de pago creado correctamente",
  "data": {
    "id": "pi_xxxxxxxxxx",
    "amount": 5000,
    "currency": "eur",
    "status": "requires_confirmation",
    "customer": "cus_xxxxxxxxxx",
    "payment_method": "card_xxxxxxxxxx"
  }
}
23
The amount in the response is in cents (5000 = €50.00). All payments are processed in EUR.
24
Step 5: Confirm the Payment
25
Finally, confirm the payment intent to complete the transaction.
26
curl -X POST http://localhost:3000/api/payments/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "pi_xxxxxxxxxx"
  }'
27
Expected Response:
28
{
  "status": true,
  "message": "Pago confirmado correctamente",
  "data": {
    "id": "pi_xxxxxxxxxx",
    "amount": 5000,
    "currency": "eur",
    "status": "succeeded",
    "charges": {
      "data": [
        {
          "id": "ch_xxxxxxxxxx",
          "amount": 5000,
          "paid": true,
          "status": "succeeded"
        }
      ]
    }
  }
}
29
Step 6: Handle Refunds (Optional)
30
If you need to refund a payment, use the charge ID from the confirmed payment.
31
Full Refund
curl -X POST http://localhost:3000/api/payments/refund \
  -H "Content-Type: application/json" \
  -d '{
    "chargeId": "ch_xxxxxxxxxx",
    "reason": "requested_by_customer"
  }'
Partial Refund
curl -X POST http://localhost:3000/api/payments/refund \
  -H "Content-Type: application/json" \
  -d '{
    "chargeId": "ch_xxxxxxxxxx",
    "amount": 25.00,
    "reason": "requested_by_customer"
  }'
32
Expected Response:
33
{
  "status": true,
  "message": "Reembolso creado correctamente",
  "data": {
    "id": "re_xxxxxxxxxx",
    "amount": 2500,
    "charge": "ch_xxxxxxxxxx",
    "status": "succeeded",
    "reason": "requested_by_customer"
  }
}

​
Implementation Notes

Amount Handling

When creating payments, provide the amount in your currency (e.g., 50.00). The API automatically multiplies by 100 to convert to cents for Stripe.

Currency

All payments are processed in EUR. If you need to support other currencies, you’ll need to modify the payment intent creation logic.

Payment Method Types

Currently, only card payments are supported. The API is configured with payment_method_types: ['card'] in the payment intent creation.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us