Quickstart

This guide walks through the essential steps to process a first payment with Martis. Complete these steps to go from account creation to a successful test transaction.

1. Create an Account

Before making API requests, an account must be created and verified.

1. Navigate to the Martis Dashboard and sign up
2. Complete the business profile with company name and country
3. Access the sandbox environment upon successful registration

Account verification enables access to API keys, webhook configuration, and transaction management. Review the account requirements before beginning.

2. Configure the Environment

Martis provides two isolated environments for development and production use.

All examples in this guide use the sandbox environment. See Environments for detailed configuration.

3. Generate an API Key

API keys authenticate requests to the Martis API. Each environment requires its own API key.

1. Navigate to Creator Hub → Integration → API Keys in the dashboard
2. Click Create new API key
3. Copy the secret key immediately — it is displayed only once
4. Store the key securely using environment variables or a secrets manager

4. Authenticate Requests

All API requests require authentication via the Authorization header using a Bearer token.

curl https://api-staging.martis.id/api/v1/payments/charges \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'Content-Type: application/json'

A 401 Unauthorized response indicates an invalid or missing API key. See Authentication for detailed implementation.

5. Create a Payment Charge

Create a payment charge to collect funds from a customer.

curl https://api-staging.martis.id/api/v1/payments/charges \
  --request POST \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment_method": "qris",
    "channel": "gudang_voucher",
    "amount": 50000,
    "currency": "idr",
    "customer_details": {
      "name": "Test Customer",
      "email": "customer@example.com"
    },
    "client_reference_id": "order-001"
  }'

Response

A successful request returns a charge object with payment instructions:

{
  "status": "success",
  "data": {
    "id": "01HZCHARGE123456ABCDEF",
    "payment_method": "qris",
    "channel": "gudang_voucher",
    "status": "pending",
    "amount": 50000.00,
    "currency": "idr",
    "payment_url": "https://pay.martis.id/c/01HZCHARGE123456ABCDEF",
    "qr_code_url": "https://assets.martis.id/qr/01HZCHARGE123456ABCDEF.png",
    "expires_at": "2025-01-15T11:30:00Z"
  }
}

Test the Payment Flow

Use the interactive demo to create and test payment charges without writing code:

6. Handle Webhooks

Webhooks deliver real-time notifications when payment events occur. Configure a webhook endpoint to receive status updates.

1. Create an HTTPS endpoint that accepts POST requests
2. Register the endpoint in Creator Hub → Integration → Webhooks
3. Verify webhook signatures using the provided secret
4. Return a 2xx response to acknowledge receipt

Next Steps

With a successful test payment complete, continue integration with these resources: