Download the PHP package aliziodev/payid-transactions without Composer

PayID Transactions

Shared payment ledger package for PayID ecosystem.

Requirements

• PHP ^8.3
• Laravel ^12.0|^13.0 (illuminate/database, illuminate/support)

CI and Release

• CI workflow runs on push/PR to main:
  • composer validate --strict
  • composer lint-check
  • composer test
• Auto tag release workflow reads version from composer.json at:
  • extra.release.version
• On push to main (when composer.json changes), the workflow:
  • creates git tag v<version> if not exists
  • creates GitHub Release with generated notes

Release steps for maintainers:

1. Bump extra.release.version in composer.json.
2. Merge/push to main.
3. Workflow creates tag and GitHub release automatically.

Scope

• Persist payment transaction lifecycle (payment_transactions).
• Persist webhook delivery and processing trail (payment_webhook_events).
• Provide service contract for recording and updating transaction state.

Schema Notes

• Transaction identity is composite: provider + merchant_order_id.
• If idempotency_key is provided, transaction upsert identity becomes provider + idempotency_key.
• Optional polymorphic linkage is available via subject_type + subject_id.
• Webhook table stores replay-safe event_fingerprint and processing audit fields.

Terminology Glossary

This package uses gateway-neutral naming so one schema can serve multiple providers.

• provider: payment gateway identifier (midtrans, stripe, xendit, doku, paddle, etc).
• merchant_order_id: merchant-side business reference for the payment intent. Common equivalents in other systems: external_id, invoice_number, order_code.
• provider_transaction_id: gateway-side transaction/reference ID (pi_..., txn_..., etc).
• idempotency_key: client/service generated deduplication key for retry-safe writes.
• subject_type and subject_id: domain link (similar to polymorphic relation by convention). Examples: order, subscription, marketplace_order, wallet_topup.
• event_fingerprint: deterministic unique value to detect webhook replay/retry.

Naming Guidelines

Recommended conventions for production teams:

• Keep provider lowercase slug and stable (stripe, not Stripe/STRIPE).
• Keep merchant_order_id immutable after first successful write.
• Use idempotency_key for all external-call retries (charge, confirm, capture, etc).
• Use consistent subject_type vocabulary across services (document in one place).
• Put gateway-specific extras in metadata, keep core columns provider-agnostic.

Gateway Field Mapping (Practical)

• Midtrans: merchant_order_id <= order_id, provider_transaction_id <= transaction_id.
• Stripe: merchant_order_id <= invoice/external order reference, provider_transaction_id <= payment_intent/charge ID.
• Xendit: merchant_order_id <= external_id, provider_transaction_id <= payment/invoice transaction ID.
• DOKU: merchant_order_id <= merchant invoice/order number, provider_transaction_id <= DOKU transaction reference.
• Paddle: merchant_order_id <= merchant checkout/invoice reference, provider_transaction_id <= Paddle transaction ID.

Non-scope

• Invoice domain model.
• Subscription orchestration.
• Provider API adapter logic.

Install

Publish

Usage

Resolve ledger service from container:

Prune old webhook audit rows:

Real-World Scenarios

The same ledger structure can be used across local and global gateways for ecommerce, subscription billing, marketplace payouts, and digital products.

1) Midtrans - ecommerce checkout (one-time payment)

2) Stripe - SaaS subscription renewal

3) Paddle - digital product/license sale

4) DOKU - local VA payment

5) Xendit - online store with invoice lifecycle

Webhook Audit Example

Use webhook event store for retries/replay visibility and processing outcomes:

Suggested Subject Mapping

• ecommerce order: subject_type = order, subject_id = order_id
• subscription billing: subject_type = subscription, subject_id = subscription_id
• marketplace order: subject_type = marketplace_order, subject_id = marketplace_order_id
• digital goods/license: subject_type = license_order, subject_id = license_order_id
• wallet top-up: subject_type = wallet_topup, subject_id = topup_id