API Documentation

← Back to Home

QRIS Payment Gateway API

This documentation provides detailed information about the API endpoints available for integrating QRIS payments into your application.

Authentication

All protected API requests require authentication using Sanctum tokens. First, you need to authenticate using the login endpoint to obtain a token, then include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

To authenticate and get a token:

POST /api/auth/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "your_password"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "User Name",
      "email": "user@example.com"
    },
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer"
  }
}

API Endpoints

Authentication Endpoints

Login

Endpoint: POST /api/auth/login

Description: Authenticate user and obtain access token

Authentication: Not required

Request Body:

{
  "email": "user@example.com",
  "password": "your_password"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "User Name",
      "email": "user@example.com"
    },
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer"
  }
}
Get Authenticated User

Endpoint: GET /api/auth/user

Description: Get the authenticated user's information

Authentication: Required

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "User Name",
    "email": "user@example.com"
  }
}
Logout

Endpoint: POST /api/auth/logout

Description: Revoke the current access token

Authentication: Required

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

Test API Connection

Endpoint: GET /api/test-api

Description: Test if the API is working

Authentication: Not required

Response:

{
  "success": true,
  "message": "QRIS Payment Gateway API is working!",
  "timestamp": "2025-09-03T10:30:00.000000Z"
}

Generate QRIS Payment

Endpoint: POST /api/payment/generate-qris

Description: Generates a QRIS code for payment

Authentication: Required

Request Body:

{
  "amount": 100000,
  "description": "Payment for order #123",
  "callback_url": "https://yourapp.com/payment/callback",
  "distribution_strategy": "random", // Optional: random, round_robin, specific
  "qris_id": 1 // Required only if distribution_strategy is "specific"
}

Parameters:

  • amount (required, numeric): Payment amount (minimum 1000)
  • description (optional, string): Payment description (max 255 characters)
  • callback_url (optional, url): URL to receive payment notifications
  • distribution_strategy (optional, enum): QRIS selection strategy
    • random - Select a random active QRIS (default)
    • round_robin - Distribute payments evenly across QRIS
    • specific - Use a specific QRIS (requires qris_id)
  • qris_id (conditional, integer): Specific QRIS ID (required only if distribution_strategy is "specific")

Response:

{
  "success": true,
  "data": {
    "transaction_id": "TRX-ABC123XYZ7",
    "amount": 100000,
    "fee": 700,
    "total_amount": 100700,
    "qris_code": "DUMMY_QRIS_CODE_BCA_STATIC_001",
    "qris_image": null,
    "bank_name": "BCA",
    "expires_at": "2025-09-03T10:45:00.000000Z"
  }
}

Get Transaction Status

Endpoint: GET /api/payment/transaction/{transactionId}

Description: Retrieves the status of a transaction

Authentication: Required

Path Parameters:

  • transactionId (required, string): The transaction ID returned when generating QRIS

Response:

{
  "success": true,
  "data": {
    "transaction_id": "TRX-ABC123XYZ7",
    "amount": 100000,
    "fee": 700,
    "status": "success", // pending, success, failed, expired
    "description": "Payment for order #123",
    "paid_at": "2025-09-03T10:25:00.000000Z",
    "created_at": "2025-09-03T10:20:00.000000Z"
  }
}

Get QRIS List

Endpoint: GET /api/payment/qris-list

Description: Retrieves the list of available active QRIS

Authentication: Required

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "BCA Static QRIS",
      "bank_name": "BCA",
      "type": "static",
      "qris_image": null
    },
    {
      "id": 2,
      "name": "Mandiri Dynamic QRIS",
      "bank_name": "Mandiri",
      "type": "dynamic",
      "qris_image": null
    }
  ]
}

Handle Payment Callback

Endpoint: POST /api/payment/callback

Description: Receives payment notifications from the payment gateway

Authentication: Not required (public endpoint)

Request Body:

{
  "transaction_id": "TRX-ABC123XYZ7",
  "status": "success",
  "amount": 100000,
  "timestamp": "2025-09-03T10:25:00.000000Z"
}

Response:

{
  "success": true,
  "message": "Payment processed successfully"
}

Admin Endpoints

Get Reports

Endpoint: GET /api/admin/reports

Description: Get reports data (admin users only)

Authentication: Required (admin privileges)

Response:

{
  "message": "Reports page"
}
Export Reports

Endpoint: GET /api/admin/reports/export

Description: Export reports data (admin users only)

Authentication: Required (admin privileges)

Response:

{
  "message": "Export reports"
}

Distribution Strategies

The QRIS Payment Gateway supports multiple distribution strategies for selecting which QRIS to use for a payment:

1. Random Distribution

Selects a random active QRIS for each payment request. This is the default strategy.

{
  "distribution_strategy": "random"
}

2. Round Robin Distribution

Distributes payments evenly across all active QRIS in a rotating fashion.

{
  "distribution_strategy": "round_robin"
}

3. Specific QRIS

Uses a specific QRIS identified by its ID.

{
  "distribution_strategy": "specific",
  "qris_id": 1
}

Note: The default distribution strategy can be configured in the config/qris.php file or through the QRIS_DEFAULT_DISTRIBUTION_STRATEGY environment variable.

Error Responses

All API endpoints return consistent error responses in the following format:

{
  "success": false,
  "message": "Error description"
}

Common HTTP Status Codes:

  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - Insufficient permissions (e.g., accessing admin endpoints without admin role)
  • 404 Not Found - Resource not found (e.g., transaction ID)
  • 500 Internal Server Error - Server-side errors

Rate Limiting

The API implements rate limiting to prevent abuse. Excessive requests may result in temporary blocks.

Usage Examples

1. Authenticate and Generate a Payment QRIS

# First, authenticate to get a token
curl -X POST https://yourdomain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

# Use the token to generate a payment QRIS
curl -X POST https://yourdomain.com/api/payment/generate-qris \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "description": "Product purchase",
    "callback_url": "https://yourapp.com/webhook"
  }'

2. Check Transaction Status

curl -X GET https://yourdomain.com/api/payment/transaction/TRX-ABC123XYZ7 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

3. Get Available QRIS List

curl -X GET https://yourdomain.com/api/payment/qris-list \
  -H "Authorization: Bearer YOUR_API_TOKEN"

4. Handle Payment Callback (Server-side)

// This endpoint is called by the payment gateway
// Your server should handle this to update order status
curl -X POST https://yourdomain.com/api/payment/callback \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TRX-ABC123XYZ7",
    "status": "success",
    "amount": 50000
  }'