Transactions

Transactions are the core of the Dimebia payment platform. This guide covers creating, retrieving, and managing payment transactions.

Overview

A transaction represents a payment attempt between a customer and your business. Transactions track the entire payment lifecycle from creation to settlement.

Transaction Lifecycle

Created → Processing → Succeeded/Failed
                ↓
            Refunded (partial or full)

Status	Description
PENDING	Transaction created, awaiting processing
PROCESSING	Payment is being processed
SUCCESS	Payment completed successfully
FAILED	Payment failed
REFUNDED	Transaction refunded
CANCELLED	Transaction cancelled

Create a Transaction

POST /api/transaction/create

Request Body

Field	Type	Required	Description
amount	Long	Yes	Amount in cents (e.g., 10000 = $100.00)
currency	String	Yes	ISO 4217 currency code (USD, EUR, etc.)
channelId	Long	Yes	Payment channel ID
description	String	No	Transaction description
metadata	Object	No	Custom key-value pairs
customerId	Long	No	Customer ID
invoiceId	Long	No	Associated invoice ID

Example

curl -X POST http://localhost:8080/api/transaction/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "amount": 100000,
    "currency": "USD",
    "channelId": 1,
    "description": "Premium subscription",
    "metadata": {
      "orderId": "ORD-12345"
    }
  }'

Response

{
  "code": 200,
  "message": "Transaction created",
  "data": {
    "id": "TXN2026081800001",
    "amount": 100000,
    "currency": "USD",
    "status": "PENDING",
    "channelId": 1,
    "channelName": "Stripe",
    "description": "Premium subscription",
    "createdTime": "2026-08-18T10:00:00Z",
    "updatedTime": "2026-08-18T10:00:00Z"
  }
}

Retrieve a Transaction

GET /api/transaction/detail?id={transactionId}

List Transactions

GET /api/transaction/list?page=1&pageSize=20&status=SUCCESS

Query Parameters

Parameter	Type	Description
page	Integer	Page number (default: 1)
pageSize	Integer	Items per page (default: 20, max: 100)
status	String	Filter by status
channelId	Long	Filter by channel
startDate	String	Start date (YYYY-MM-DD)
endDate	String	End date (YYYY-MM-DD)

Refund a Transaction

POST /api/refund/create

{
  "transactionId": "TXN2026081800001",
  "amount": 50000,
  "reason": "Customer request",
  "refundType": "FULL"
}

Webhooks

Configure webhooks to receive real-time notifications for transaction events:

• transaction.created
• transaction.processing
• transaction.succeeded
• transaction.failed
• transaction.refunded

See Webhooks Guide for setup instructions.

Code Examples

Node.js

import { Dimebia } from '@dimebia/node';

const client = new Dimebia({ apiKey: 'sk_live_...' });

// Create transaction
const transaction = await client.transactions.create({
  amount: 100000,
  currency: 'USD',
  channelId: 1,
  description: 'Premium subscription',
});

// Retrieve transaction
const retrieved = await client.transactions.retrieve(transaction.id);

// List transactions
const list = await client.transactions.list({
  status: 'SUCCESS',
  limit: 10,
});

Python

import dimebia

client = dimebia.Dimebia(api_key='sk_live_...')

# Create transaction
transaction = client.transactions.create(
    amount=100000,
    currency='USD',
    channel_id=1,
    description='Premium subscription',
)

# Retrieve transaction
retrieved = client.transactions.retrieve(transaction['id'])

# List transactions
transactions = client.transactions.list(status='SUCCESS', limit=10)

Best Practices

1. Idempotency: Use idempotency keys to prevent duplicate charges
2. Webhooks: Always verify webhook signatures
3. Error Handling: Implement retry logic with exponential backoff
4. Security: Never expose secret keys in client-side code