Available Endpoints

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)

{
    "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)

{
    "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)

{
    "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)

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)

{
    "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

More Information

Need Help?

For questions about integration or the API, hit the live chat. Our team's on standby.

Open Live Chat