Available Endpoints 🔗

🌏 Environment Modes

Komerce Payment API supports two environments:

• Production: https://api.collaborator.komerce.id/user
• Sandbox: https://api-sandbox.collaborator.komerce.id/user

Use sandbox mode for testing payment flows without actual transactions. You can simulate payment status updates in sandbox environment.

Payment Page URLs:

• Production: https://pay.komerce.id/{token}
• Sandbox: https://pay-sandbox.komerce.id/{token}

1. Get Payment Methods 📋

GET /api/v1/user/methods

Retrieve a list of available payment methods including Virtual Account banks and QRIS.

Use Case: Display payment options to customers during checkout.

Authentication: Required (API Key in header)

Response Example

{
    "meta": {
        "message": "success get payment methods",
        "code": 200,
        "status": "success"
    },
    "data": [
        {
            "payment_type": "va",
            "display_name": "Bank Central Asia",
            "bank_code": "BCA",
            "logo_url": "https://storage.googleapis.com/komerce/assets/logo/bca.png",
            "min_amount": 10000,
            "max_amount": 999999999999,
            "currency": "IDR"
        },
        {
            "payment_type": "qris",
            "display_name": "QRIS",
            "bank_code": "",
            "logo_url": "https://storage.googleapis.com/komerce/assets/logo/qris.png",
            "min_amount": 10000,
            "max_amount": 10000000,
            "currency": "IDR"
        }
    ]
}

Features:

• Lists all supported VA banks (BNI, BCA, Mandiri, BRI, Permata, CIMB, BSI, BJB, etc.)
• QRIS availability information
• Bank logos and display names
• Cached responses (1 hour TTL) for optimal performance
• Response time < 500ms

2. Create Payment - Virtual Account 🏦

POST /api/v1/user/payment/create

Create a payment transaction using Virtual Account (bank transfer).

Use Case: Generate VA number for customers to complete payment via bank transfer.

Authentication: Required (API Key in header)

Request BodyResponse Example

{
    "order_id": "KOM12345",
    "payment_type": "bank_transfer",
    "channel_code": "BCA",
    "amount": 100000,
    "customer": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "081234567890"
    },
    "items": [
        {
            "name": "Product A",
            "quantity": 2,
            "price": 50000
        }
    ],
    "expiry_duration": 3600,
    "callback_url": "https://yoursite.com/callback",
    "callback_API_KEY": "your-generated-key"
}

Validation Rules:

• order_id: Required, max 100 characters
• channel_code: Must be from available banks list
• amount: Required, minimum Rp 10,000
• expiry_duration: Minimum 3600 seconds (1 hour)
• callback_API_KEY: Required if callback_url is provided

Response Time: < 2-5 seconds

3. Create Payment - QRIS 📱

POST /api/v1/user/payment/create

Create a payment transaction using QRIS (Quick Response Code Indonesian Standard).

Use Case: Generate QR code for customers to scan and pay via e-wallet apps.

Authentication: Required (API Key in header)

Request BodyResponse Example

{
    "order_id": "KOM12345",
    "payment_type": "qris",
    "amount": 100000,
    "customer": {
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "081234567890"
    },
    "items": [
        {
            "name": "Product A",
            "quantity": 2,
            "price": 50000
        }
    ],
    "callback_url": "https://yoursite.com/callback",
    "callback_API_KEY": "your-generated-key"
}

Key Differences from VA:

• No channel_code required
• Fixed expiration: 5 minutes (QRIS standard)
• Returns qr_string to generate QR code image
• Minimum amount: Rp 10,000

Response Time: < 2-5 seconds

4. Get Payment Status 🔍

GET /api/v1/user/payment/status/{payment_id}

Check the current status of a payment transaction.

Use Case: Verify if customer has completed payment, useful for order confirmation.

Authentication: Required (API Key in header)

Request ExampleResponse Example

curl --location 'https://api-sandbox.collaborator.komerce.id/user/api/v1/user/payment/status/{payment_id}' \
--header 'x-api-key: YOUR_API_KEY'

Payment Status Values:

• PENDING: Waiting for customer payment
• PAID: Payment completed successfully
• EXPIRED: Payment period has ended
• CANCELED: Payment was canceled

Features:

• Real-time status checking
• Settlement amount calculation included
• Payment method details (when paid)
• Response time < 300ms
• Rate limiting: 1 request per 3 seconds per payment_id

5. Cancel Payment ❌

POST /api/v1/user/payment/cancel

Cancel a pending payment transaction.

Use Case: Prevent customer from paying after order cancellation.

Authentication: Required (API Key in header)

Request BodyResponse Example

{
    "payment_id": "KOMPAY-1699012345-A1B2C3",
    "reason": "Customer canceled the order"
}

Validation Rules:

• Only PENDING payments can be canceled
• PAID or EXPIRED payments cannot be canceled
• payment_id must be valid and exist in database

Behavior:

• For VA: Deactivates virtual account
• For QRIS: No action needed (expires automatically)
• Logs cancellation reason and timestamp

Response Time: < 2 seconds

Authentication 🔐

All endpoints require authentication using your API Key. Include it in the request header:

# Production
curl --location 'https://api.collaborator.komerce.id/user/api/v1/user/methods' \
--header 'x-api-key: YOUR_API_KEY'

# Sandbox
curl --location 'https://api-sandbox.collaborator.komerce.id/user/api/v1/user/methods' \
--header 'x-api-key: YOUR_API_KEY'

HTTP Status Codes 🌐

Best Practices 🤖

Secure Your API Key

• Never share your key publicly or include it in client-side code
• Use environment variables to store your API key securely

Payment Flow Recommendations

1. Checkout Page: Call GET /api/v1/user/methods to display payment options
2. Create Payment: Call POST /api/v1/user/payment/create when customer selects payment method
3. Status Monitoring: Use GET /api/v1/user/payment/status/ to check payment completion
4. Order Cancellation: Call POST /api/v1/user/payment/cancel if order is canceled before payment

Callback Implementation

• Always provide callback_url for real-time payment notifications
• Secure your callback endpoint with callback_API_KEY
• Verify the authenticity of callback requests

Environment Usage

🧑‍💻 Development/Testing: Use sandbox environment

• Simulate payment status updates
• No real transactions

🚀 Production: Use production environment

• Real payment processing
• Actual money transfer

Rate Limiting

• Status check: Maximum 1 request per 3 seconds per payment_id
• Implement proper retry mechanisms with exponential backoff

Payment Method Comparison 💳