Quickstart

Get up and running with the Artos API in under 5 minutes.

Prerequisites

An Artos account — sign up here
Your account approved by an Artos admin (requests return 403 until then)
An API key (created in the dashboard)

1. Get an API Key

Go to Dashboard → API Keys and create a new key. Copy it — it's only shown once.

.env

ARTOS_API_KEY=art_live_your_key_here

2. Create a Payment

Make a POST request to create a payment transaction. merchantOrderId must be unique — reusing one returns 409. The payment method defaults to QRIS (SP) and expires after 60 minutes unless you set expiryPeriod.

curl

curl -X POST https://api-artos.kasir.ai/v1/payments/create \
  -H "X-API-Key: art_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER-001",
    "amount": 50000,
    "productDetails": "Premium Plan",
    "customerEmail": "[email protected]",
    "returnUrl": "https://yoursite.com/success"
  }'

200 OK

{
  "success": true,
  "data": {
    "id": "6f1c2a9e-3b7d-4c1a-9f0e-2d5b8a4c7e11",
    "slug": "inv-a1B2c3D4e5",
    "merchantOrderId": "ORDER-001",
    "amount": 50000,
    "paymentMethod": "SP",
    "reference": "DS1234525ABCDEFGH",
    "qrString": "00020101021226...",
    "vaNumber": null,
    "duitkuPaymentUrl": "https://app-sandbox.duitku.com/redirect_checkout?reference=...",
    "paymentUrl": "https://artos.dev/pay/inv-a1B2c3D4e5",
    "expiredAt": "2025-01-01T01:00:00.000Z",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

Redirect your customer to paymentUrl (the Artos hosted payment page), or render the qrString / vaNumber yourself.

3. Handle the Webhook

Register a webhook URL in Dashboard → Webhooks. Artos will POST to your URL when a payment succeeds, fails, or expires.

Node.js / Express

app.post('/webhooks/artos', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Verify X-Artos-Signature against the raw body (see Verifying Signatures)
  const { id, event, data } = JSON.parse(req.body.toString('utf8'))

  // 2. Skip events you have already processed (retries reuse the same id)

  if (event === 'payment.success') {
    // 3. Fulfill the order for data.merchantOrderId (your own order ID)
    console.log('Payment received:', id, data.transactionId)
  }

  // Respond 2xx within 10s, otherwise Artos retries
  res.status(200).send('OK')
})

Always verify the webhook signature before processing.

Next Steps