Payments API

The Payments API allows you to create, manage, and track payment transactions for both authenticated users and guest customers.

Base URL

https://your-instance.pubflow.com/bridge-payment

Authentication

Include one of the following in your requests:

• Header: X-Session-ID: <session_id> (recommended)
• Header: Authorization: Bearer <token>
• Query Parameter: ?session_id=<session_id> (alternative method)
• Guest: Provide guest_data in request body (no auth required)

Query Parameter Authentication

You can pass the session ID as a query parameter for convenience:

POST /bridge-payment/payments/intents?session_id=your_session_id

This is useful for testing but the header method is recommended for production.

Endpoints Overview

Method	Endpoint	Description
POST	/payments/intents	Create payment intent
PUT	/payments/intents/:id	Update payment intent
POST	/payments/confirm/:id	Confirm payment
POST	/payments/sync/:provider_payment_id	Sync payment status
GET	/payments/:id	Get payment by ID
GET	/payments	List user payments
GET	/payments/guest/:email	List guest payments

---

Create Payment Intent

Create a new payment intent to start a payment transaction.

Request

POST /bridge-payment/payments/intents
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Field	Type	Required	Description
subtotal_cents	number	Yes	Subtotal amount in cents
tax_cents	number	No	Tax amount in cents (default: 0)
discount_cents	number	No	Discount amount in cents (default: 0)
total_cents	number	Yes	Total amount in cents
currency	string	Yes	Currency code (USD, EUR, etc.)
provider_id	string	No	Payment provider (default: "stripe")
description	string	No	Payment description
concept	string	No	Payment concept/title
reference_code	string	No	Your internal reference
category	string	No	Payment category
tags	string	No	Comma-separated tags
setup_future_usage	string	No	"off_session" to save payment method
payment_method_id	string	No	Use saved payment method
customer_id	string	No	Customer ID (auto-detected if not provided)
organization_id	string	No	Organization ID
metadata	object	No	Additional metadata
guest_data	object	No*	Guest customer data (*required for guests)
guest_data.email	string	Yes	Guest email
guest_data.name	string	Yes	Guest name
guest_data.phone	string	No	Guest phone

Response

{
  "id": "pay_1234567890",
  "provider_payment_id": "pi_stripe_abc123",
  "client_secret": "pi_stripe_abc123_secret_xyz",
  "status": "created",
  "subtotal_cents": 1800,
  "tax_cents": 200,
  "discount_cents": 0,
  "total_cents": 2000,
  "currency": "USD",
  "provider_id": "stripe",
  "concept": "Premium Subscription",
  "description": "Monthly premium plan",
  "is_guest_payment": false,
  "created_at": "2025-01-15T10:30:00Z"
}

Client Secret Security

The client_secret is automatically deleted after 24 hours for security. Use it immediately on the frontend to confirm payment.

Examples

Authenticated User Payment

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "subtotal_cents": 1800,
    "tax_cents": 200,
    "total_cents": 2000,
    "currency": "USD",
    "concept": "Premium Subscription",
    "description": "Monthly premium plan",
    "provider_id": "stripe",
    "setup_future_usage": "off_session"
  }'

Guest Payment

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -d '{
    "subtotal_cents": 5000,
    "tax_cents": 500,
    "total_cents": 5500,
    "currency": "USD",
    "concept": "Donation",
    "provider_id": "stripe",
    "guest_data": {
      "email": "donor@example.com",
      "name": "John Doe",
      "phone": "+1234567890"
    }
  }'

Payment with Saved Method

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/intents" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "total_cents": 2000,
    "currency": "USD",
    "concept": "Subscription Renewal",
    "provider_id": "stripe",
    "payment_method_id": "pm_saved_card_123"
  }'

---

Update Payment Intent

Update an existing payment intent before confirmation.

Request

PUT /bridge-payment/payments/intents/:id
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Same fields as Create Payment Intent (all optional).

Response

Returns updated payment intent object.

---

Confirm Payment

Confirm a payment intent (backend confirmation).

Request

POST /bridge-payment/payments/confirm/:id
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Field	Type	Required	Description
payment_method_id	string	No	Payment method to use

Response

{
  "id": "pay_1234567890",
  "status": "succeeded",
  "provider_payment_id": "pi_stripe_abc123",
  "completed_at": "2025-01-15T10:35:00Z"
}

Frontend Confirmation

Most integrations use Stripe Elements for frontend confirmation. Use this endpoint only for backend-only flows.

---

Sync Payment Status

Sync payment status from provider after frontend confirmation.

Request

POST /bridge-payment/payments/sync/:provider_payment_id
X-Session-ID: <session_id>

Response

Returns updated payment object with current status from provider.

Example

# After Stripe redirects to return_url with payment_intent parameter
curl -X POST "https://your-instance.pubflow.com/bridge-payment/payments/sync/pi_stripe_abc123" \
  -H "X-Session-ID: session_abc123"

---

Get Payment

Retrieve a specific payment by ID.

Request

GET /bridge-payment/payments/:id
X-Session-ID: <session_id>

Response

Returns complete payment object.

---

List Payments

List all payments for authenticated user.

Request

GET /bridge-payment/payments
X-Session-ID: <session_id>

Response

[
  {
    "id": "pay_123",
    "total_cents": 2000,
    "status": "succeeded",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

---

List Guest Payments

List payments for a guest email.

Request

GET /bridge-payment/payments/guest/:email

No authentication required.

---

Next Steps

• Payment Methods API - Manage saved payment methods
• Customers API - Manage customer information
• Subscriptions API - Set up recurring payments