Payment Charges

Payment charges represent requests to collect payments from customers. A charge is created with an amount, currency, and payment method, then generates payment instructions for the customer to complete the transaction.

For complete API documentation, see the API Reference.

The Charge Object

A payment charge contains the following attributes:

Name
id
Type
string
Description
Unique identifier for the charge
Name
payment_method
Type
string
Description
Payment method type (e.g., qris, virtual_account)
Name
channel
Type
string
Description
Payment channel code (e.g., gudang_voucher, mandiri)
Name
status
Type
string
Description
Current status: pending, success, or failed
Name
currency
Type
string
Description
Three-letter currency code (e.g., idr)
Name
amount
Type
decimal
Description
Payment amount
Name
fee
Type
decimal
Description
Transaction fee charged
Name
client_reference_id
Type
string
Description
Merchant-provided reference identifier
Name
customer_details
Type
object
Description
Customer information including name, email, and phone
Name
items
Type
array
Description
List of items included in the payment
Name
expires_at
Type
datetime
Description
Expiration timestamp for the payment
Name
paid_at
Type
datetime
Description
Timestamp when payment was completed (null if unpaid)
Name
created_at
Type
datetime
Description
Timestamp when the charge was created
Name
updated_at
Type
datetime
Description
Timestamp of last update

POST/v1/payments/charges

Create a Charge

Creates a new payment charge for a customer to complete.

Request Body

Name
payment_method
Type
string
Description
Payment method type. Supported values: qris, virtual_account
Name
channel
Type
string
Description
Payment channel code. See Payment Methods for available channels.
Name
amount
Type
decimal
Description
Payment amount. Must be greater than 0.
Name
currency
Type
string
Description
Three-letter currency code. Default: idr
Name
customer_details
Type
object
Description
Customer information object
Name
customer_details.email
Type
string
Description
Customer email address
Name
customer_details.name
Type
string
Description
Customer full name
Name
customer_details.phone_number
Type
string
Description
Customer phone number
Name
client_reference_id
Type
string
Description
Merchant reference ID for tracking (max 50 characters)
Name
expires_at
Type
datetime
Description
Custom expiration timestamp. If not provided, default expiration applies based on payment method.
Name
items
Type
array
Description
Array of item objects
Name
items[].name
Type
string
Description
Item name
Name
items[].price
Type
decimal
Description
Item unit price
Name
items[].quantity
Type
integer
Description
Item quantity
Name
description
Type
string
Description
Payment description (max 255 characters)
Name
payment_method_options
Type
object
Description
Additional options for specific payment methods

Request

POST

/v1/payments/charges

curl https://api-staging.martis.id/api/v1/payments/charges \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {API_KEY}' \
  --data '{
    "payment_method": "qris",
    "channel": "gudang_voucher",
    "amount": 50000,
    "currency": "idr",
    "customer_details": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone_number": "081234567890"
    },
    "items": [
      {
        "name": "Product A",
        "price": 50000,
        "quantity": 1
      }
    ],
    "client_reference_id": "ORDER-001",
    "description": "Payment for Order #001"
  }'

Response 200

{
  "status": "success",
  "data": {
    "id": "01HZCHARGE123456ABCDEF",
    "payment_method": "qris",
    "channel": "gudang_voucher",
    "status": "pending",
    "currency": "idr",
    "amount": 50000.00,
    "fee": 350.00,
    "client_reference_id": "ORDER-001",
    "customer_details": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone_number": "081234567890"
    },
    "items": [
      {
        "name": "Product A",
        "price": 50000.00,
        "quantity": 1
      }
    ],
    "description": "Payment for Order #001",
    "expires_at": "2025-01-15T11:30:00Z",
    "paid_at": null,
    "created_at": "2025-01-15T11:00:00Z",
    "updated_at": "2025-01-15T11:00:00Z",
    "payment_url": "https://pay.martis.id/c/01HZCHARGE123456ABCDEF",
    "qr_code_url": "https://assets.martis.id/qr/01HZCHARGE123456ABCDEF.png"
  }
}

Response 400

{
  "status": "fail",
  "data": {
    "payment_method": ["Payment method is required"],
    "amount": ["Amount must be greater than 0"],
    "customer_details.email": ["Invalid email format"]
  }
}

Response 401

{
  "status": "error",
  "message": "Invalid or missing API key"
}

GET/v1/payments/charges/{id}

Retrieve a Charge

Retrieves an existing payment charge by its unique identifier.

Path Parameters

Name
id
Type
string
Description
The unique identifier of the payment charge

Request

GET

/v1/payments/charges/{id}

curl https://api-staging.martis.id/api/v1/payments/charges/01HZCHARGE123456ABCDEF \
  --header 'Authorization: Bearer {API_KEY}'

Response 200

{
  "status": "success",
  "data": {
    "id": "01HZCHARGE123456ABCDEF",
    "payment_method": "qris",
    "channel": "gudang_voucher",
    "status": "success",
    "currency": "idr",
    "amount": 50000.00,
    "fee": 350.00,
    "client_reference_id": "ORDER-001",
    "customer_details": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone_number": "081234567890"
    },
    "items": [
      {
        "name": "Product A",
        "price": 50000.00,
        "quantity": 1
      }
    ],
    "description": "Payment for Order #001",
    "expires_at": "2025-01-15T11:30:00Z",
    "paid_at": "2025-01-15T11:15:00Z",
    "created_at": "2025-01-15T11:00:00Z",
    "updated_at": "2025-01-15T11:15:00Z"
  }
}

Response 404

{
  "status": "fail",
  "data": {
    "message": "Payment charge not found"
  }
}

Virtual Account Options

When creating a charge with payment_method: "virtual_account", additional configuration options are available:

Payment Method Options

Name
payment_method_options.virtual_account.account_name
Type
string
Description
Custom name to display on the virtual account. Defaults to customer name.
Name
payment_method_options.virtual_account.account_number
Type
string
Description
Specific virtual account number to use. If null, a number is auto-generated.

Virtual Account Request

{
  "payment_method": "virtual_account",
  "channel": "mandiri",
  "amount": 150000,
  "currency": "idr",
  "customer_details": {
    "email": "customer@example.com",
    "name": "Customer Name"
  },
  "payment_method_options": {
    "virtual_account": {
      "account_name": "PT Example Store",
      "account_number": null
    }
  }
}

Webhook Events

Payment charge status changes trigger webhook events:

Event	Description
`payment_charge.created`	Charge created and awaiting payment
`payment_charge.update`	Charge details updated
`payment_charge.succeeded`	Payment completed successfully
`payment_charge.failed`	Payment failed or expired

See Webhooks for payload examples and signature verification.