Payments example

Create and retrieve payment

These two endpoints show the core request-response shape a buyer expects to see in a credible payments API example: how money is created and how status is retrieved.

Back to example index View source

Endpoint

Create payment

POST /payments creates a payment for a customer checkout session.

Auth: Bearer token required
Body: amount, currency, customer_id, optional payment_method_id
Idempotency: send Idempotency-Key on create requests

curl -X POST "https://api.startup-payments.example/v1/payments"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{"amount":125.5,"currency":"USD","customer_id":"cus_123","payment_method_id":"pm_123"}'

{
  "payment_id": "pay_123",
  "status": "pending",
  "amount": 125.5,
  "currency": "USD"
}

Endpoint

Retrieve payment

GET /payments/{id} retrieves the current state and metadata for a payment.

Auth: Bearer token required
Path parameter: id
Common errors: 401 Unauthorized, 404 Payment not found

curl -X GET "https://api.startup-payments.example/v1/payments/pay_123"   -H "Authorization: Bearer <token>"

{
  "payment_id": "pay_123",
  "status": "completed",
  "amount": 125.5,
  "currency": "USD"
}

Related guidance

These endpoints depend on the shared operational model.

The example endpoint docs refer back to authentication, error handling, idempotency, and webhook delivery so the example reads like a complete API, not isolated endpoint fragments.

Authentication Operational model