Payment Service API

A RESTful API for payment service management.

Base URL

http://localhost:8000

Authentication

The API uses two types of authentication:

2. Partner Authentication: Required for partner-specific operations
   • Header: Authorization: Bearer <partner_token>
   • Header: X-Partner-ID: <partner_id>

Partners

Create Partner

POST /partners

Headers:

• X-Admin-API-Key: Required

Request Body:

{
  "name": "string",
  "email": "string",
  "username": "string",
  "password": "string",
  "phone": "string (optional)",
  "account": "string"
}

Response: 201 Created

{
  "id": "string",
  "name": "string",
  "email": "string",
  "username": "string",
  "phone": "string",
  "is_active": boolean,
  "created_at": "datetime",
  "updated_at": "datetime"
}

List Partners

GET /partners

Headers:

• X-Admin-API-Key: Required

Query Parameters:

• skip: integer (default: 0)
• limit: integer (default: 100, max: 100)

Response: 200 OK

[
  {
    "id": "string",
    "name": "string",
    "email": "string",
    "username": "string",
    "phone": "string",
    "is_active": boolean,
    "created_at": "datetime",
    "updated_at": "datetime"
  }
]

Get Partner

GET /partners/{partner_id}

Headers:

• X-Admin-API-Key: Required

Response: 200 OK

{
  "id": "string",
  "name": "string",
  "email": "string",
  "username": "string",
  "phone": "string",
  "is_active": boolean,
  "created_at": "datetime",
  "updated_at": "datetime"
}

Update Partner

PATCH /partners/{partner_id}

Headers:

• X-Admin-API-Key: Required

Request Body:

{
  "name": "string (optional)",
  "email": "string (optional)",
  "phone": "string (optional)",
  "password": "string (optional)",
  "is_active": boolean (optional)
}

Response: 200 OK

{
  "id": "string",
  "name": "string",
  "email": "string",
  "username": "string",
  "phone": "string",
  "is_active": boolean,
  "created_at": "datetime",
  "updated_at": "datetime"
}

Delete Partner

DELETE /partners/{partner_id}

Headers:

• X-Admin-API-Key: Required

Response: 204 No Content

Dashboard Users

Create Dashboard User

POST /users

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Request Body:

{
  "username": "string",
  "email": "string",
  "password": "string",
  "is_admin": boolean
}

Response: 201 Created

{
  "id": "string",
  "username": "string",
  "email": "string",
  "is_admin": boolean,
  "is_active": boolean,
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

List Dashboard Users

GET /users

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Query Parameters:

• skip: integer (default: 0)
• limit: integer (default: 100, max: 100)

Response: 200 OK

[
  {
    "id": "string",
    "username": "string",
    "email": "string",
    "is_admin": boolean,
    "is_active": boolean,
    "partner_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
  }
]

Get Dashboard User

GET /users/{user_id}

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Response: 200 OK

{
  "id": "string",
  "username": "string",
  "email": "string",
  "is_admin": boolean,
  "is_active": boolean,
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Update Dashboard User

PATCH /users/{user_id}

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Request Body:

{
  "username": "string (optional)",
  "email": "string (optional)",
  "password": "string (optional)",
  "is_active": boolean (optional),
  "is_admin": boolean (optional)
}

Response: 200 OK

{
  "id": "string",
  "username": "string",
  "email": "string",
  "is_admin": boolean,
  "is_active": boolean,
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Delete Dashboard User

DELETE /users/{user_id}

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Response: 204 No Content

Shoppers

Create Shopper

POST /shoppers

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Request Body:

{
  "name": "string",
  "email": "string",
  "phone": "string (optional)",
  "account": "string"
}

Response: 201 Created

{
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "account": "string",
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime",
  "total_completed_charges": {
    "currency": "decimal"
  }
}

List Shoppers

GET /shoppers

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Query Parameters:

• skip: integer (default: 0)
• limit: integer (default: 100, max: 100)

Response: 200 OK

[
  {
    "id": "string",
    "name": "string",
    "email": "string",
    "phone": "string",
    "account": "string",
    "partner_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "total_completed_charges": {
      "currency": "decimal"
    }
  }
]

Get Shopper

GET /shoppers/{shopper_id}

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Response: 200 OK

{
  "id": "string",
  "name": "string",
  "email": "string",
  "phone": "string",
  "account": "string",
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime",
  "total_completed_charges": {
    "currency": "decimal"
  }
}

Get Shopper Charges

GET /shoppers/{shopper_id}/charges

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Query Parameters:

• skip: integer (default: 0)
• limit: integer (default: 100, max: 100)

Response: 200 OK

[
  {
    "id": "string",
    "amount": "decimal",
    "currency": "string",
    "status": "string",
    "description": "string",
    "charge_metadata": object,
    "partner_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
  }
]

Charges

Create Charge

POST /charges

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Request Body:

{
  "amount": "decimal",
  "currency": "string",
  "description": "string",
  "charge_metadata": object,
  "shopper_id": "string (optional)"
}

Response: 201 Created

{
  "id": "string",
  "amount": "decimal",
  "currency": "string",
  "status": "string",
  "description": "string",
  "charge_metadata": object,
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Update Charge

PATCH /charges/{charge_id}

Headers:

• X-Admin-API-Key: Required

Request Body:

{
  "amount": "decimal (optional)",
  "currency": "string (optional)",
  "status": "string (optional)",
  "description": "string (optional)",
  "charge_metadata": object (optional)
}

Response: 200 OK

{
  "id": "string",
  "amount": "decimal",
  "currency": "string",
  "status": "string",
  "description": "string",
  "charge_metadata": object,
  "partner_id": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

Get Charge History

GET /charges/{charge_id}/history

Headers:

• Authorization: Bearer token
• X-Partner-ID: Partner ID

Query Parameters:

• skip: integer (default: 0)
• limit: integer (default: 100, max: 100)

Response: 200 OK

[
  {
    "id": "string",
    "charge_id": "string",
    "status": "string",
    "previous_status": "string",
    "description": "string",
    "created_at": "datetime"
  }
]

Webhooks

LINE Webhook

POST /webhook/line

Request Body:

{
  "destination": "string",
  "events": [
    {
      "type": "string",
      "message": {
        "type": "string",
        "id": "string",
        "contentProvider": {
          "type": "string"
        },
        "content": {
          "type": "string"
        }
      },
      "timestamp": "integer",
      "source": {
        "type": "string",
        "userId": "string"
      },
      "replyToken": "string",
      "mode": "string",
      "deliveryContext": {
        "isRedelivery": boolean
      }
    }
  ]
}

Response: 200 OK

Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 204 No Content: Request successful, no content to return
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing authentication
• 404 Not Found: Resource not found
• 409 Conflict: Resource already exists or conflict with existing data
• 500 Internal Server Error: Server error

Valid Currencies

The following ISO 4217 currency codes are supported:

• USD (US Dollar)
• EUR (Euro)
• GBP (British Pound)
• JPY (Japanese Yen)
• AUD (Australian Dollar)
• CAD (Canadian Dollar)
• CHF (Swiss Franc)
• CNY (Chinese Yuan)
• INR (Indian Rupee)
• NZD (New Zealand Dollar)
• BRL (Brazilian Real)
• RUB (Russian Ruble)
• KRW (South Korean Won)
• SGD (Singapore Dollar)
• HKD (Hong Kong Dollar)
• SEK (Swedish Krona)
• NOK (Norwegian Krone)
• MXN (Mexican Peso)
• ZAR (South African Rand)
• TRY (Turkish Lira)
• THB (Thai Baht)

Charge Statuses

The following charge statuses are supported:

• pending: Initial state when charge is created
• processing: Charge is being processed
• completed: Charge has been successfully completed
• failed: Charge processing failed
• cancelled: Charge was cancelled
• refunded: Charge was refunded