Payment API

Use these endpoints to purchase credits, confirm completed payments, and inspect balances for your MIRI API account.

Authentication

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

All payment endpoints require an API key. When initiating purchases, include X-Idempotency-Key to protect against duplicate orders.

Purchase Credits

Start a credit purchase with the configured payment provider.

Endpoint

POST /public/v1/payments/purchase

Headers

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Idempotency-Key: unique-request-id-123 (optional)

Request Body

{
  "packageType": "STANDARD",
  "paymentMethod": "CARD"
}

Field Reference

Field	Type	Required	Description
packageType	string	Yes	Credit package to purchase: BASIC, STANDARD, PRO, or MAX.
paymentMethod	string	No	Payment method (currently only CARD). Defaults to CARD when omitted.

Response (201 Created)

{
  "success": true,
  "data": {
    "orderId": "ord_2025090100001",
    "packageType": "STANDARD",
    "amount": 20000,
    "clientKey": "test_ck_xxxxxxxxxxxxxxxxx",
    "successUrl": "https://partner.example.com/payments/success",
    "failUrl": "https://partner.example.com/payments/fail"
  },
  "message": "Payment initiated. Please proceed with payment.",
  "code": "SUCCESS",
  "metadata": null
}

Response Fields

Field	Type	Description
orderId	string	Unique payment order identifier.
packageType	string	Selected package tier.
amount	number	Purchase amount in KRW.
clientKey	string	Payment gateway client key for front-end checkout.
successUrl	string	Redirect URL after a successful payment.
failUrl	string	Redirect URL after a failed payment.

Idempotent submissions

Reuse the same X-Idempotency-Key if you need to retry a purchase request. The service will return the original orderId instead of creating a duplicate transaction.

Confirm Payment

Finalize a payment after the user completes checkout with the gateway.

Endpoint

POST /public/v1/payments/confirm

Headers

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Request Body

{
  "orderId": "ord_2025090100001",
  "paymentKey": "payment_key_from_gateway",
  "amount": 20000
}

Response (200 OK)

{
  "success": true,
  "data": {
    "orderId": "ord_2025090100001",
    "creditsAdded": 60,
    "totalCredits": 300,
    "message": "Payment successful. Credits have been added to your account."
  },
  "message": "Payment confirmed successfully",
  "code": "SUCCESS",
  "metadata": null
}

Response Fields

Field	Type	Description
orderId	string	Confirmed payment order.
creditsAdded	integer	Credits granted by this transaction.
totalCredits	integer	Customer’s total balance after confirmation.
message	string	Human-readable confirmation message.

Get Payment Status

Retrieve the status of a payment order at any time.

Endpoint

GET /public/v1/payments/{orderId}

Response (200 OK)

{
  "success": true,
  "data": {
    "orderId": "ord_2025090100001",
    "status": "CONFIRMED",
    "packageType": "STANDARD",
    "amount": 20000,
    "createdAt": "2025-09-01T10:00:00Z",
    "confirmedAt": "2025-09-01T10:15:00Z"
  },
  "message": "Payment status retrieved",
  "code": "SUCCESS",
  "metadata": null
}

Status Reference

Status	Description
PENDING	Order is awaiting confirmation; no credits have been added yet.
CONFIRMED	Payment succeeded and credits were added to the account.
FAILED	Payment failed or was rejected; credits were not added.
CANCELLED	Cancellation succeeded and the order is closed. Any previously added credits are rolled back during cancellation.
REFUNDED	A previously confirmed order was refunded by the platform after settlement.

Get Credit Balance

Check the current credit balance for the authenticated customer.

Endpoint

GET /public/v1/payments/credits

Response (200 OK)

{
  "success": true,
  "data": {
    "credits": 240,
    "customerId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": "Credit amount retrieved",
  "code": "SUCCESS",
  "metadata": null
}

List Credit Packages

Retrieve the packages available for purchase.

Endpoint

GET /public/v1/payments/packages

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "packageType": "BASIC",
      "credits": 1,
      "price": 1000,
      "displayName": "Basic Plan - 1 Credit",
      "description": "1 credit for ₩1,000",
      "bonusPercentage": 0,
      "bonusCredits": 0
    },
    {
      "packageType": "STANDARD",
      "credits": 21,
      "price": 20000,
      "displayName": "Standard Plan - 21 Credits",
      "description": "21 credits for ₩20,000",
      "bonusPercentage": 5,
      "bonusCredits": 1
    },
    {
      "packageType": "PRO",
      "credits": 110,
      "price": 100000,
      "displayName": "Pro Plan - 110 Credits",
      "description": "110 credits for ₩100,000",
      "bonusPercentage": 10,
      "bonusCredits": 10
    },
    {
      "packageType": "MAX",
      "credits": 1200,
      "price": 1000000,
      "displayName": "Max Plan - 1,200 Credits",
      "description": "1,200 credits for ₩1,000,000",
      "bonusPercentage": 20,
      "bonusCredits": 200
    }
  ],
  "message": "Available credit packages",
  "code": "SUCCESS",
  "metadata": null
}

Package Summary

Package	Credits (base+bonus)	Bonus %	Price (KRW)
BASIC	1	0%	₩1,000
STANDARD	20 + 1	5%	₩20,000
PRO	100 + 10	10%	₩100,000
MAX	1,000 + 200	20%	₩1,000,000

Cancel Payment

Cancel a previously initiated payment.

Endpoint

POST /public/v1/payments/cancel

Headers

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Request Body

{
  "paymentKey": "payment_key_from_gateway",
  "reason": "User requested cancellation"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "message": "Payment cancelled"
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

The top-level message remains null; use data.message for user-facing copy. If the cancellation fails, the service returns 400 Bad Request with code = "PAYMENT_CANCEL_FAILED" and includes the paymentKey and reason in metadata.

Error Codes

Code	HTTP Status	Description
INVALID_API_KEY	401	Header missing or malformed (edge authentication filter).
AUTH001	401	API key not recognized.
AUTH003	403	API key suspended.
VAL001	400	Request body could not be parsed.
VAL002	400	Required field missing (for example, packageType).
VAL003	400	Field validation failed or contained an unsupported enum value.
VAL004	400	Request size exceeded the platform limit.
BUS002	402	Credit balance insufficient for the attempted operation.
PAYMENT_CANCEL_FAILED	400	Cancellation request rejected; metadata echoes the paymentKey and reason.
NOT000	404	Payment not found or does not belong to the caller.
SVC001	503	Payment service temporarily unavailable; retry later.
INT001	500	Unexpected server error.

Related Endpoints

• Analysis API – Consume credits for single analyses.
• Batch API – Consume credits for batch submissions.