Payouts

Payouts transfer funds from an Martis balance to external bank accounts. Use payouts to send payments to vendors, employees, or withdraw funds to registered accounts.

For complete API documentation, see the API Reference.

The Payout Object

A payout contains the following attributes:

Name
id
Type
string
Description
Unique identifier for the payout
Name
account_id
Type
string
Description
Source account identifier
Name
status
Type
string
Description
Current status: pending, processing, completed, failed, cancelled, suspected, rejected, or refunded
Name
type
Type
string
Description
Destination type (e.g., bank_account)
Name
currency
Type
string
Description
Three-letter currency code (e.g., idr)
Name
amount
Type
decimal
Description
Payout amount
Name
fee
Type
decimal
Description
Transaction fee charged
Name
bank
Type
object
Description
Destination bank information
Name
account_number
Type
string
Description
Destination bank account number
Name
account_holder_name
Type
string
Description
Name of the account holder
Name
client_reference_id
Type
string
Description
Merchant-provided reference identifier
Name
description
Type
string
Description
Payout description
Name
balance_transaction_id
Type
string
Description
Associated balance transaction identifier
Name
created_at
Type
datetime
Description
Timestamp when the payout was created
Name
updated_at
Type
datetime
Description
Timestamp of last update

POST/v1/payouts

Create a Payout

Creates a new payout to an external bank account.

Request Body

Name
amount
Type
decimal
Description
Payout amount. Must be greater than 0.
Name
currency
Type
string
Description
Three-letter currency code. Currently supported: idr
Name
destination
Type
object
Description
Destination details object
Name
destination.type
Type
string
Description
Destination type. Supported value: bank_account
Name
destination.bank_account
Type
object
Description
Bank account details when type is bank_account
Name
destination.bank_account.bank_code
Type
string
Description
Bank code identifier. See Bank Accounts for supported banks.
Name
destination.bank_account.account_number
Type
string
Description
Destination account number
Name
destination.bank_account.account_holder_name
Type
string
Description
Account holder name as registered with the bank
Name
client_reference_id
Type
string
Description
Merchant reference ID for tracking and reconciliation
Name
description
Type
string
Description
Description of the payout

Request

POST

/v1/payouts

curl https://api-staging.martis.id/api/v1/payouts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {API_KEY}' \
  --data '{
    "amount": 500000.00,
    "currency": "idr",
    "destination": {
      "type": "bank_account",
      "bank_account": {
        "bank_code": "bca",
        "account_number": "1234567890",
        "account_holder_name": "John Doe"
      }
    },
    "description": "Vendor payment for services",
    "client_reference_id": "PO-2024-0001"
  }'

Response 200

{
  "status": "success",
  "data": {
    "id": "01HZPAYOUT123456ABCDEF",
    "account_id": "01HZABC987654321FEDCBA",
    "currency": "idr",
    "status": "pending",
    "type": "bank_account",
    "bank": {
      "code": "bca",
      "name": "Bank Central Asia",
      "country_code": "ID",
      "currency": "idr"
    },
    "account_number": "1234567890",
    "account_holder_name": "John Doe",
    "amount": 500000.00,
    "fee": 5000.00,
    "description": "Vendor payment for services",
    "client_reference_id": "PO-2024-0001",
    "balance_transaction_id": "01HZTXN456789012ABCDEF",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Response 400

{
  "status": "fail",
  "data": {
    "amount": ["Amount must be greater than 0"],
    "currency": ["Currency is required"],
    "destination.bank_account.account_number": ["Account number is required"]
  }
}

Response 401

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

Response 403

{
  "status": "error",
  "message": "Insufficient balance for payout"
}

GET/v1/payouts/{id}

Retrieve a Payout

Retrieves an existing payout by its unique identifier.

Path Parameters

Name
id
Type
string
Description
The unique identifier of the payout

Request

GET

/v1/payouts/{id}

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

Response 200

{
  "status": "success",
  "data": {
    "id": "01HZPAYOUT123456ABCDEF",
    "account_id": "01HZABC987654321FEDCBA",
    "currency": {
      "name": "Indonesian Rupiah",
      "value": "idr"
    },
    "status": {
      "name": "Processing",
      "value": "processing"
    },
    "type": {
      "name": "Bank Account",
      "value": "bank_account"
    },
    "bank": {
      "code": "bca",
      "name": "Bank Central Asia",
      "country_code": "ID",
      "currency": {
        "name": "Indonesian Rupiah",
        "value": "idr"
      }
    },
    "account_number": "1234567890",
    "account_holder_name": "John Doe",
    "amount": 500000.00,
    "fee": 5000.00,
    "description": "Vendor payment for services",
    "client_reference_id": "PO-2024-0001",
    "account": {
      "id": "01HZABC987654321FEDCBA",
      "name": "My Business Account"
    },
    "balance_transaction_id": "01HZTXN456789012ABCDEF",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:15:00Z"
  }
}

Response 404

{
  "status": "fail",
  "data": {
    "message": "Payout not found"
  }
}

Payout States

A payout progresses through the following states:

Status	Description
`pending`	Payout created, awaiting processing
`processing`	Payout submitted to the banking system
`completed`	Funds successfully delivered to the destination
`failed`	Payout failed due to validation or processing errors
`cancelled`	Payout cancelled before processing
`suspected`	Payout flagged for security or compliance review
`rejected`	Payout rejected after review
`refunded`	Funds returned to the source account

Webhook Events

Payout status changes trigger webhook events:

Event	Description
`payout.created`	Payout created and queued for processing
`payout.updated`	Payout details or status updated
`payout.pending`	Payout awaiting processing
`payout.processing`	Payout submitted to banking system
`payout.succeeded`	Payout completed successfully
`payout.failed`	Payout failed
`payout.suspected`	Payout flagged for review
`payout.rejected`	Payout rejected after review
`payout.refunded`	Payout refunded to source account

See Webhooks for payload examples and signature verification.

Idempotency

Include an Idempotency-Key header to safely retry payout requests without creating duplicates.

curl https://api-staging.martis.id/api/v1/payouts \
  --request POST \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'Idempotency-Key: payout-vendor-001-attempt-1' \
  --data '{...}'

See Idempotency for key generation best practices.