Search docs

Search the API documentation

POST

Create Payment

/v1/payments/create

Creates a new payment and initiates the transaction with the payment provider. Requires the X-API-Key header. The response contains a hosted payment page URL plus the raw QR string or virtual account number, depending on the payment method.

Request Body

merchantOrderIdstringrequired

Your own order ID, 1–50 characters. Must be unique per account — reusing an existing value returns 409.

amountintegerrequired

Payment amount in IDR (Indonesian Rupiah). Must be an integer greater than 0.

productDetailsstringrequired

Product description, 1–255 characters.

paymentMethodstring

Payment method code. Defaults to SP (QRIS) when enabled, otherwise to the first method enabled by the admin. Must be one of the methods enabled by the Artos admin, otherwise the request fails with 400.

customerEmailstring

Customer email address. Must be a valid email.

customerNamestring

Customer name.

returnUrlstring

URL to redirect the customer to after payment. Must be an http or https URL.

expiryPeriodinteger

Payment expiry in minutes, between 1 and 10080 (7 days). Defaults to 60.

Response

idstring

Payment link ID.

slugstring

Slug of the hosted payment page.

merchantOrderIdstring

Your merchantOrderId, echoed back.

amountinteger

Payment amount in IDR.

paymentMethodstring

Payment method used for this transaction.

referencestring

Payment provider (Duitku) reference.

qrStringstring | null

QRIS payload to render as a QR code, when applicable.

vaNumberstring | null

Virtual account number, when applicable.

duitkuPaymentUrlstring | null

Payment provider's own payment page, when available.

paymentUrlstring

Artos hosted payment page (https://<frontend>/pay/<slug>).

expiredAtstring

Expiry time (ISO 8601).

createdAtstring

Creation time (ISO 8601).

The recommended flow is to redirect your customer to paymentUrl. Alternatively, render qrString as a QR code or display vaNumber in your own UI. The create response does not include a status — use webhooks or Get Payment to track the outcome.

Examples

curl
curl -X POST https://api-artos.kasir.ai/v1/payments/create \
  -H "X-API-Key: art_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantOrderId": "ORDER-001",
    "amount": 50000,
    "productDetails": "Premium Plan",
    "paymentMethod": "SP",
    "customerEmail": "[email protected]",
    "customerName": "Budi Santoso",
    "returnUrl": "https://yoursite.com/success",
    "expiryPeriod": 60
  }'
JavaScript
const response = await fetch('https://api-artos.kasir.ai/v1/payments/create', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ARTOS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    merchantOrderId: 'ORDER-001',
    amount: 50000,
    productDetails: 'Premium Plan',
  }),
})
const { success, data, error } = await response.json()
if (success) {
  // Redirect the customer to the hosted payment page
  redirect(data.paymentUrl)
}
200 — Success
{
  "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"
  }
}

Errors

400 — Validation error
{
  "success": false,
  "error": "Invalid input",
  "details": {
    "fieldErrors": {
      "amount": ["Expected number, received string"]
    }
  }
}
409 — Duplicate merchantOrderId
{ "success": false, "error": "merchantOrderId already exists" }
502 — Payment provider error
{ "success": false, "error": "Payment provider error: ..." }

See Error Handling for the full list of status codes.