Transaction

A Transaction in the Paylias network represents a double-entry ledger record that captures both the debit and credit entries of a payment between participating partners. Each transaction ensures accurate accounting by maintaining balanced entries across all parties involved in the payment flow.

Overview

Each Transaction:

Contains paired debit and credit entries
Links to a specific payment
Tracks processing status
Maintains settlement timing
Records approval details

API Resource

Property	Type	Description	Notes
`token`	string	Unique identifier for transaction	Auto-generated upon creation
`transaction_id`	string	Business identifier	Used for reference
`payment_id`	string	Associated payment identifier	Links to Payment
`status`	enum	Current transaction status	See Status Types
`transaction_lines`	array	Debit and credit entries	See Transaction Lines
`response_code`	string	Processor response code	Optional
`approval_code`	string	Authorization code	Optional
`initiated_on`	integer	Start timestamp	Unix timestamp in seconds
`processed_on`	integer	Processing timestamp	Unix timestamp in seconds
`settled_on`	integer	Settlement timestamp	Unix timestamp in seconds
`expires_on`	integer	Expiration timestamp	Unix timestamp in seconds
`created_on`	integer	Creation timestamp	Unix timestamp in seconds
`updated_on`	integer	Last update timestamp	Unix timestamp in seconds

Transaction Lines

Property	Type	Description	Notes
`token`	string	Line identifier	Auto-generated
`transaction_id`	string	Parent transaction	Links to Transaction
`partner_id`	string	Associated Domain	Links to Domain
`direction`	enum	Debit or Credit	See Direction Types
`transaction_type`	enum	Type of transaction	See Transaction Types
`amount`	object	Transaction amount	Currency and value

Status Types

Status	Value	Description
`TS_UNKNOWN`	0	Status not determined
`TS_INITIATED`	1	Transaction started
`TS_PROCESSING`	2	In progress
`TS_COMPLETED`	3	Successfully completed
`TS_FAILED`	4	Transaction failed
`TS_REVERSED`	5	Transaction reversed
`TS_EXPIRED`	6	Transaction timed out
`TS_RECOVERED`	7	Recovered from error

Direction Types

Direction	Value	Description
`TD_None`	0	No direction specified
`TD_Credit`	1	Incoming funds
`TD_Debit`	2	Outgoing funds

Transaction Types

Type	Value	Description
`TT_UNKNOWN`	0	Type not specified
`TT_PAYMENT`	1	Standard payment
`TT_REFUND`	2	Payment refund
`TT_REVERSAL`	3	Payment reversal
`TT_FEE`	4	Service fee

Authentication

All Transaction operations require:

API Key in the X-Sfpy-Api-Key header
Organization ID in the X-Org-ID header
Domain ID in the X-Partner-ID header

API Endpoints

Find Transaction

Retrieves details of a specific transaction.

Path Parameters

Parameter	Type	Required	Description
`paymentId`	string	Yes	Payment identifier
`transactionId`	string	Yes	Transaction identifier

`GET /api/v1/csp/payments/{paymentId}/transactions/{transactionId}`

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/payments/cjes76vsemvj3obsnc50/transactions/ct2504s20or30kh8if00' \
--header 'X-Org-ID: org_ct239n420or249k5bo90' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'X-Sfpy-Api-Key: <api_key>'

Example Response

{
    "ok": true,
    "data": {
        "token": "txn_ct2505420or2o5qk438g",
        "transaction_id": "ct2504s20or30kh8if00",
        "payment_id": "cjes76vsemvj3obsnc50",
        "status": 3,
        "transaction_lines": [
            {
                "token": "line_ct2505420or2o5qk4390",
                "transaction_id": "txn_ct2505420or2o5qk438g",
                "partner_id": "part_ct23c1420or249k5bocg",
                "direction": 2,
                "transaction_type": 1,
                "amount": {
                    "currency": "USD",
                    "total": "10000"
                }
            },
            {
                "token": "line_ct2505420or2o5qk43a0",
                "transaction_id": "txn_ct2505420or2o5qk438g",
                "partner_id": "part_ct23b6420or249k5boag",
                "direction": 1,
                "transaction_type": 1,
                "amount": {
                    "currency": "USD",
                    "total": "10000"
                }
            }
        ],
        "approval_code": "HY7QIA",
        "initiated_on": 1732530196,
        "created_on": 1732530196,
        "updated_on": 1732530196
    }
}

Common Error Codes

Error Code	Description
`error.bad_request`	Invalid or missing required parameters
`error.resource_not_found`	Transaction not found
`error.unauthorized_access`	Invalid or missing authentication
`500`, `502`, `503`, `504`	Server-side errors