2. Payments API

Version 1.0.0

API for processing and managing payments.

Payments API details

openapi: 3.0.3
info:
  title: Payments API
  description: API for processing and managing payments.
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /payments:
    get:
      summary: List payments
      description: Retrieve a list of payments.
      responses:
        "200":
          description: A list of payments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Payment"

    post:
      summary: Create a payment
      description: Create a new payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentCreate"
      responses:
        "201":
          description: Payment created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"

  /payments/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string

    get:
      summary: Get payment by ID
      responses:
        "200":
          description: Payment found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "404":
          description: Payment not found

    put:
      summary: Update a payment
      description: Update metadata of a payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentUpdate"
      responses:
        "200":
          description: Payment updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
        "404":
          description: Payment not found

    delete:
      summary: Cancel a payment
      description: Cancel a payment that has not been completed.
      responses:
        "204":
          description: Payment canceled
        "404":
          description: Payment not found

components:
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
          example: "pay_123"
        amount:
          type: integer
          description: Amount in cents.
          example: 1999
        currency:
          type: string
          example: "EUR"
        status:
          type: string
          description: Payment status.
          enum:
            - pending
            - succeeded
            - failed
            - canceled
        createdAt:
          type: string
          format: date-time
          example: "2025-01-01T12:00:00Z"

    PaymentCreate:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: integer
          description: Amount in cents.
        currency:
          type: string
          example: "EUR"
        description:
          type: string
          example: "Order #1234"

    PaymentUpdate:
      type: object
      properties:
        description:
          type: string
          example: "Updated payment description"

Path Table

Method	Path	Description
GET	/payments	List payments
POST	/payments	Create a payment
GET	/payments/{id}	Get payment by ID
PUT	/payments/{id}	Update a payment
DELETE	/payments/{id}	Cancel a payment

Reference Table

Name	Path	Description
Payment	#/components/schemas/Payment
PaymentCreate	#/components/schemas/PaymentCreate
PaymentUpdate	#/components/schemas/PaymentUpdate

Path Details

---

GET /payments

• Summary
  List payments

• Description
  Retrieve a list of payments.

Responses

• 200 A list of payments

application/json

{
  id?: string
  // Amount in cents.
  amount?: integer
  currency?: string
  // Payment status.
  status?: enum[pending, succeeded, failed, canceled]
  createdAt?: string
}[]

---

POST /payments

• Summary
  Create a payment

• Description
  Create a new payment.

RequestBody

• application/json

{
  // Amount in cents.
  amount: integer
  currency: string
  description?: string
}

Responses

• 201 Payment created

application/json

{
  id?: string
  // Amount in cents.
  amount?: integer
  currency?: string
  // Payment status.
  status?: enum[pending, succeeded, failed, canceled]
  createdAt?: string
}

---

GET /payments/{id}

• Summary
  Get payment by ID

Responses

• 200 Payment found

application/json

{
  id?: string
  // Amount in cents.
  amount?: integer
  currency?: string
  // Payment status.
  status?: enum[pending, succeeded, failed, canceled]
  createdAt?: string
}

• 404 Payment not found

---

PUT /payments/{id}

• Summary
  Update a payment

• Description
  Update metadata of a payment.

RequestBody

• application/json

{
  description?: string
}

Responses

• 200 Payment updated

application/json

{
  id?: string
  // Amount in cents.
  amount?: integer
  currency?: string
  // Payment status.
  status?: enum[pending, succeeded, failed, canceled]
  createdAt?: string
}

• 404 Payment not found

---

DELETE /payments/{id}

• Summary
  Cancel a payment

• Description
  Cancel a payment that has not been completed.

Responses

• 204 Payment canceled

• 404 Payment not found

References

#/components/schemas/Payment

{
  id?: string
  // Amount in cents.
  amount?: integer
  currency?: string
  // Payment status.
  status?: enum[pending, succeeded, failed, canceled]
  createdAt?: string
}

#/components/schemas/PaymentCreate

{
  // Amount in cents.
  amount: integer
  currency: string
  description?: string
}

#/components/schemas/PaymentUpdate

{
  description?: string
}