Payment Methods API

The Payment Methods API allows you to securely store and manage payment instruments (credit cards, bank accounts) for future use.

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>
• Guest: Provide guest_data in request body (no auth required)

Endpoints Overview

Method	Endpoint	Description
POST	/payment-methods	Create payment method
GET	/payment-methods	List payment methods
GET	/payment-methods/:id	Get payment method
PUT	/payment-methods/:id	Update payment method
DELETE	/payment-methods/:id	Delete payment method
POST	/payment-methods/:id/set-default	Set as default

---

Create Payment Method

Create a new payment method for a customer.

Request

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

Request Body

Field	Type	Required	Description
provider_id	string	Yes	Payment provider (stripe, paypal, authorize_net)
provider_payment_method_token	string	Yes*	Provider's payment method token (*recommended)
type	string	No	Payment method type (card, bank_account)
billing_address_id	string	No	Billing address ID
is_default	boolean	No	Set as default method (default: false)
alias	string	No	Friendly name for the payment method
Direct Card Data (Development Only)
card_number	string	No**	Card number (**not recommended for production)
card_exp_month	string	No**	Expiration month (MM)
card_exp_year	string	No**	Expiration year (YYYY)
card_cvc	string	No**	Card security code
Guest Data
guest_data	object	No***	Guest customer data (***required for guests)
guest_data.email	string	Yes	Guest email
guest_data.name	string	Yes	Guest name

Token-Based vs Direct Card Data

Token-Based (Recommended for Production):

• ✅ PCI compliant
• ✅ Secure tokenization by provider
• ✅ No raw card data handling

Direct Card Data (Development Only):

• ⚠️ Requires PCI compliance
• ⚠️ Only for testing
• ⚠️ Use tokenization in production

Response

{
  "id": "pm_1234567890",
  "provider_id": "stripe",
  "provider_payment_method_id": "pm_stripe_abc123",
  "type": "card",
  "card_brand": "visa",
  "card_last_four": "4242",
  "card_exp_month": "12",
  "card_exp_year": "2025",
  "billing_address_id": "addr_123",
  "is_default": false,
  "alias": "My Visa Card",
  "is_guest_method": false,
  "created_at": "2025-01-15T10:30:00Z"
}

Examples

Token-Based Payment Method (Recommended)

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payment-methods" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "provider_id": "stripe",
    "provider_payment_method_token": "pm_1234567890",
    "billing_address_id": "addr_123",
    "alias": "My Primary Card"
  }'

Direct Card Data (Development Only)

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payment-methods" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "provider_id": "stripe",
    "card_number": "4242424242424242",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_cvc": "123",
    "billing_address_id": "addr_123"
  }'

Guest Payment Method

curl -X POST "https://your-instance.pubflow.com/bridge-payment/payment-methods" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "stripe",
    "provider_payment_method_token": "pm_1234567890",
    "guest_data": {
      "email": "[email protected]",
      "name": "Guest User"
    }
  }'

---

List Payment Methods

List all payment methods for authenticated user.

Request

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

Response

[
  {
    "id": "pm_123",
    "provider_id": "stripe",
    "type": "card",
    "card_brand": "visa",
    "card_last_four": "4242",
    "is_default": true,
    "alias": "My Visa Card",
    "created_at": "2025-01-15T10:30:00Z"
  },
  {
    "id": "pm_456",
    "provider_id": "stripe",
    "type": "card",
    "card_brand": "mastercard",
    "card_last_four": "5555",
    "is_default": false,
    "alias": "Backup Card",
    "created_at": "2025-01-10T08:20:00Z"
  }
]

---

Get Payment Method

Retrieve a specific payment method by ID.

Request

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

Response

Returns complete payment method object.

---

Update Payment Method

Update payment method details (alias, default status, billing address).

Request

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

Request Body

Field	Type	Description
alias	string	Update friendly name
billing_address_id	string	Update billing address
is_default	boolean	Set as default

Example

curl -X PUT "https://your-instance.pubflow.com/bridge-payment/payment-methods/pm_123" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "alias": "Updated Card Name",
    "is_default": true
  }'

---

Delete Payment Method

Delete a payment method.

Request

DELETE /bridge-payment/payment-methods/:id
X-Session-ID: <session_id>

Response

HTTP/1.1 204 No Content

---

Set Default Payment Method

Set a payment method as the default.

Request

POST /bridge-payment/payment-methods/:id/set-default
X-Session-ID: <session_id>

Response

Returns updated payment method with is_default: true.

---

Next Steps

• Payments API - Create payments with saved methods
• Addresses API - Manage billing addresses
• Customers API - Manage customer information