> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transactions
> A "transaction" in the Synctera platform represents any movement of funds between accounts.
## Overview
Transactions comes in 2 flavours:
* Pending transactions
* Posted transactions
A pending transaction represents a "hold" or "authorization" for the movement of funds in an account. Pending transactions are used whenever we need to guarantee the availability of funds for any multi-step payment flow. See [The Transaction Life-cycle](#the-transaction-life-cycle) below for an example.
A pending transaction is mutable, meaning that up to the point that the pending transaction is posted or expired, the amount of the hold may be increased, decreased, canceled, or declined. Note that this functionality is not typically exposed directly to integrator, but instead depends on the business logic of the specific payment rail.
Once a transaction is "posted", it is then considered immutable and cannot be changed. Any adjustments (such as a reversal, for example) requires the creation of a new transaction.
## Creating Transactions
Transactions can be initiated in a few different ways:
### Directly, via the Synctera payment APIs:
* Originating an ACH debit or credit ([ACH API Reference](/v2/reference/addtransactionout))
* An internal transfer between two Synctera accounts ([Internal Transfer API Reference](/v2/reference/createinternaltransfer)).
### Indirectly, via an external payment network:
* A card transaction at an ATM or point-of-sale.
* An incoming ACH debit or credit from another bank (such as a direct deposit).
An integrator can subscribe various `TRANSACTION` webhook events to be notified when a transaction is created or updated, even when the transactions aren't directly initiated by your application.
## Anatomy of a Transaction
The full spec for pending and posted transactions is documented in the API reference for [Pending Transactions](/v2/reference/getpendingtransactionbyid) and [Posted Transactions](/v2/reference/getpostedtransactionbyid) respectively, there are several fields worth describing in more detail:
### id
The `id` of a transaction is a unique identifier for a particular payment. This identifier is preserved through the entire life-cycle of a transaction. This means that a pending transaction and its final posted transaction will share the same id.
### type
The `type` of a transaction generally represents the "payment rail" that is being used. For ACH payments this will be `ach`, which debit card transactions will use `card`.
### subtype
The `subtype` field represents the specific operation that initiated the transaction. For example, for card transactions, the subtype might be could be `atm_withdrawal` for taking money out of an ATM, or `pos_purchase` for any purchase made at a Point-of-Sale system.
### effective\_date
The `effective_date` of a transaction represents the time that the transaction should be considered effective for the purposes of interest calculation.
### posted\_date
This value is specific to posted transactions.
This value represents the current banking day the transaction was initiated on, from the perspective of the sponsor bank. This doesn't always match up with the chronological time. Notably, "banking days" do not include weekends or bank holidays.
As an example, of a payment is made on Friday at 9PM, the `effective_date` would have the current date/time the transaction was created, while the `posted_date` would actually be the following Monday.
### user\_data
The `user_data` field represents key-value meta-data specific to a given payment rail. For example, transactions with type `ach` will have a `user_data` field containing ACH-specific meta-data (ACH return codes, trace numbers, or file names), which card transactions will have card-specific meta-data (merchant codes, etc...). This is **not** used for arbitrary metadata supplied by a Fintech, see [`external_data`](#externaldata) below.
This field is only populated by internal Synctera payment services.
Below is an example of a `user_data` from an ACH debit transaction that has been sent out to the ACH network (indicated by the `file_name` field being populated):
```json JSON theme={"system"}
{
"id": 1234,
"idemkey": "87a964a7-9191-488d-bbb8-b4f9a39578f6",
"exported": "2022-03-22T16:55:01.60644546Z",
"file_name": "20220322T165501.596_OUTBOUND.ach",
"account_id": "7b0ccc9f-957a-4e0b-bc4b-9a3d59c2eef6",
"account_no": "1234567890",
"customer_id": "226de0b5-e9b9-48f3-b562-c9bc3b35cd5b",
"description": "KandaBank",
"is_same_day": false,
"trace_number": "601282010001234",
"reference_info": "This is some reference info",
"source_account_id": "d23b541b-1fda-4c3f-b44e-3605f2095618",
"source_account_name": "Alberta Charleson"
}
```
### external\_data
The `external_data` field will include any arbitrary key-value meta-data that you as a Fintech would like to associate with the payment. This is only available for payments initiated directly via one of the Synctera payment APIs (for example, an outgoing ACH payment, or an internal transfer).
### risk\_info
The `risk_info` field is used to hold risk analysis details from Synctera's Risk/Fraud service.
This is an example of a `risk_info` payload where the fraud service has determined that the transaction is not fraudulent:
```json JSON theme={"system"}
{
"accept": true,
"reasons": ["TRANSACTION_ACCEPTED"],
"provider": "FEEDZAI",
"provider_info": {
"alert": false,
"score": 0,
"status": "ok",
"decision": "approve",
"action_codes": ["[Transfers-DR6]"],
"lifecycle_id": "c67c7799-f273-4318-8649-1378e42d64af",
"sca_required": false,
"sender_segment": "27",
"event_external_id": "c67c7799-f273-4318-8649-1378e42d64af",
"sender_bank_branch_id": "4",
"secondary_action_codes": []
},
"provider_reasons": ["Transfers-DR6"]
}
```
### lines
The `lines` field is specific to Posted Transactions.
The Synctera Ledger uses a concept called [Double-Entry Accounting](https://en.wikipedia.org/wiki/Double-entry_bookkeeping) to help ensure the integrity of all financial operation. This means that every debit or credit to an account must be offset by a corresponding credit or debit to another account. This is represented in the [Posted Transaction resource](/v2/reference/getpostedtransactionbyid) by the `data.lines` field. This field is an array of (primarily) two accounting entries: A debit from one account, and a credit from another account.
In many cases, only one side of a transaction will represent a real Synctera (customer) account. For example, consider an ACH payment to an external bank, or an ATM withdrawal.
In this case, Synctera uses an [internal account](/v2/reference/listinternalaccounts), called a *settlement account* as a proxy to offset the transaction.
## Transaction Types and Subtypes
Transactions (both pending and posted) are categorized using a combination of `type` and `subtype` fields, as mentioned above.
The set of types and subtypes currently supported by the Synctera ledger are documented below:
| Type | Subtype | D/C to originating party |
| ------------------- | -------------------------------------------- | ------------------------ |
| `ach` | `incoming_credit` | `Credit` |
| `ach` | `incoming_credit_contested_return` | `Credit` |
| `ach` | `incoming_credit_dishonored_return` | `Credit` |
| `ach` | `incoming_credit_return` | `Credit` |
| `ach` | `incoming_credit_reversal` | `Debit` |
| `ach` | `incoming_debit` | `Debit` |
| `ach` | `incoming_debit_contested_return` | `Debit` |
| `ach` | `incoming_debit_dishonored_return` | `Debit` |
| `ach` | `incoming_debit_return` | `Debit` |
| `ach` | `incoming_debit_reversal` | `Credit` |
| `ach` | `outgoing_credit` | `Debit` |
| `ach` | `outgoing_credit_contested_return` | `Debit` |
| `ach` | `outgoing_credit_dishonored_return` | `Debit` |
| `ach` | `outgoing_credit_return` | `Debit` |
| `ach` | `outgoing_credit_reversal` | `Credit` |
| `ach` | `outgoing_debit` | `Credit` |
| `ach` | `outgoing_debit_contested_return` | `Credit` |
| `ach` | `outgoing_debit_dishonored_return` | `Credit` |
| `ach` | `outgoing_debit_return` | `Credit` |
| `ach` | `outgoing_debit_reversal` | `Debit` |
| `ach` | `temp_hold` | `Debit` |
| `card` | `auth` | `Debit` |
| `card` | `auth_atm_withdrawal` | `Debit` |
| `card` | `auth_quasi_cash` | `Debit` |
| `card` | `pindebit_auth` | `Debit` |
| `card` | `auth_cashback` | `Credit` |
| `card` | `auth_incremental` | `Credit` |
| `card` | `auth_clearing` | `Debit` |
| `card` | `auth_clearing_atm_withdrawal` | `Debit` |
| `card` | `auth_clearing_quasi_cash` | `Debit` |
| `card` | `pindebit_auth_clearing` | `Debit` |
| `card` | `auth_advice` | `Debit` |
| `card` | `auth_reversal` | `Credit` |
| `card` | `pindebit_auth_reversal` | `Credit` |
| `card` | `oc_auth_reversal` | `Credit` |
| `card` | `refund_auth_reversal` | `Credit` |
| `card` | `refund` | `Credit` |
| `card` | `pindebit_refund` | `Credit` |
| `card` | `refund_auth_clearing` | `Credit` |
| `card` | `pindebit_reversal` | `Credit` |
| `card` | `balance_inquiry` | `Debit` |
| `card` | `pindebit_balance_inquiry` | `Debit` |
| `card` | `pindebit` | `Debit` |
| `card` | `pindebit_atm_withdrawal` | `Debit` |
| `card` | `pindebit_cashback` | `Credit` |
| `card` | `pindebit_quasi_cash` | `Debit` |
| `card` | `oc_auth` | `Debit` |
| `card` | `oc_auth_clearing` | `Debit` |
| `card` | `oc_auth_capture` | `Debit` |
| `card` | `pindebit_refund_reversal` | `Debit` |
| `card` | `refund_auth` | `Credit` |
| `card` | `card_transaction` | `Debit` |
| `card` | `pos_purchase` | `Debit` |
| `card` | `atm_withdrawal` | `Debit` |
| `card` | `pos_cashback` | `Credit` |
| `card` | `credit` | `Credit` |
| `card` | `pos_refund` | `Credit` |
| `card` | `pos_purchase_refund` | `Credit` |
| `card` | `provisional_credit` | `Credit` |
| `card` | `card_network_first_chargeback` | `Credit` |
| `card` | `card_network_final_chargeback` | `Credit` |
| `card` | `provisional_credit_reversal` | `Debit` |
| `check` | `mobile_deposit` | `Credit` |
| `check` | `mobile_deposit_reversal` | `Debit` |
| `check` | `mobile_deposit_return` | `Debit` |
| `check` | `mobile_deposit_return_reversal` | `Credit` |
| `external_card` | `card_funding` | `Credit` |
| `external_card` | `card_funding_reversal` | `Debit` |
| `external_card` | `card_send` | `Debit` |
| `external_card` | `card_send_reversal` | `Credit` |
| `internal_transfer` | `account_decrease_limit` | `Debit` |
| `internal_transfer` | `account_decrease_limit_reversal` | `Credit` |
| `internal_transfer` | `account_increase_limit` | `Credit` |
| `internal_transfer` | `account_increase_limit_reversal` | `Debit` |
| `internal_transfer` | `account_to_account` | `Debit` |
| `internal_transfer` | `account_to_account_reversal` | `Credit` |
| `internal_transfer` | `ach_credit_sweep` | `Debit` |
| `internal_transfer` | `ach_credit_sweep_reversal` | `Credit` |
| `internal_transfer` | `ach_debit_sweep` | `Credit` |
| `internal_transfer` | `ach_debit_sweep_reversal` | `Debit` |
| `internal_transfer` | `cashback` | `Debit` |
| `internal_transfer` | `cashback_reversal` | `Credit` |
| `internal_transfer` | `fee` | `Debit` |
| `internal_transfer` | `fee_reversal` | `Credit` |
| `internal_transfer` | `incoming_wire` | `Credit` |
| `internal_transfer` | `incoming_wire_reversal` | `Debit` |
| `internal_transfer` | `interest_payout` | `Credit` |
| `internal_transfer` | `interest_payout_reversal` | `Debit` |
| `internal_transfer` | `jit_fund` | `Debit` |
| `internal_transfer` | `jit_fund_reversal` | `Credit` |
| `internal_transfer` | `loc_usage` | `Debit` |
| `internal_transfer` | `loc_usage_reversal` | `Credit` |
| `internal_transfer` | `manual_adjustment` | `Debit` |
| `internal_transfer` | `manual_adjustment_reversal` | `Credit` |
| `internal_transfer` | `marketplace_bill_pay` | `Debit` |
| `internal_transfer` | `marketplace_bill_pay_reversal` | `Credit` |
| `internal_transfer` | `marketplace_event_tickets` | `Debit` |
| `internal_transfer` | `marketplace_event_tickets_reversal` | `Credit` |
| `internal_transfer` | `marketplace_gift_card` | `Debit` |
| `internal_transfer` | `marketplace_gift_card_reversal` | `Credit` |
| `internal_transfer` | `marketplace_mobile_top_up` | `Debit` |
| `internal_transfer` | `marketplace_mobile_top_up_reversal` | `Credit` |
| `internal_transfer` | `mastercard_gross_sweep` | `Debit` |
| `internal_transfer` | `mastercard_gross_sweep_reversal` | `Credit` |
| `internal_transfer` | `mastercard_interchange_sweep` | `Credit` |
| `internal_transfer` | `mastercard_interchange_sweep_reversal` | `Debit` |
| `internal_transfer` | `mastercard_net_sweep` | `Debit` |
| `internal_transfer` | `mastercard_net_sweep_reversal` | `Credit` |
| `internal_transfer` | `outgoing_international_remittance` | `Debit` |
| `internal_transfer` | `outgoing_international_remittance_reversal` | `Credit` |
| `internal_transfer` | `program_decrease` | |
| `internal_transfer` | `program_decrease_reversal` | |
| `internal_transfer` | `program_expansion` | |
| `internal_transfer` | `program_expansion_reversal` | |
| `internal_transfer` | `promotional_credit` | `Credit` |
| `internal_transfer` | `promotional_credit_reversal` | `Debit` |
| `internal_transfer` | `pulse_gross_sweep` | `Debit` |
| `internal_transfer` | `pulse_gross_sweep_reversal` | `Credit` |
| `internal_transfer` | `pulse_interchange_sweep` | `Credit` |
| `internal_transfer` | `pulse_interchange_sweep_reversal` | `Debit` |
| `internal_transfer` | `repayment` | `Credit` |
| `internal_transfer` | `repayment_reversal` | `Debit` |
| `internal_transfer` | `sign_up_bonus` | `Credit` |
| `internal_transfer` | `sign_up_bonus_reversal` | `Debit` |
| `internal_transfer` | `subscription_fee` | `Debit` |
| `internal_transfer` | `subscription_fee_reversal` | `Credit` |
| `internal_transfer` | `transfer_fee` | `Debit` |
| `internal_transfer` | `transfer_fee_reversal` | `Credit` |
| `wire` | `originated` | `Debit` |
| `wire` | `originated_reversal` | `Credit` |
| `wire` | `originated_return` | `Credit` |
| `wire` | `originated_return_reversal` | `Debit` |
| `wire` | `received` | `Credit` |
| `wire` | `received_reversal` | `Debit` |
## The Transaction Life-cycle
While specific details may differ slightly across different payment networks, most payments follow the same basic flow:
1. A hold is placed on an account for the requested amount. This is represented in the system as a pending transaction.
2. Synctera performs various account status, KYC, and fraud checks. If any of these checks fail, the pending transaction is declined.
3. The amount of the hold may be increased or decreased. This is mainly seen in the context of a card transaction. For example if you are at a gas station authorize $100 at the pump, but only end up filling up $50 worth.
4. At some point later the pending transaction either expires, is cancelled, or settles. When settled, this is represented as a new posted transaction.
Depending on the type of payment, the time between steps (1) and (3) may be anywhere from a few seconds, to several days (in the case of ACH payments).
Each time a transaction changes state, a webhook will be triggered. The exact events are described below:
| Scenario | Webhook event(s) | Notes |
| ------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| A hold is placed on an account | `TRANSACTION.PENDING.CREATED` | |
| Hold amount is increased or decreased | `TRANSACTION.PENDING.UPDATED` | Final amount is reflected in `total_amount`. |
| Fraud service declines transaction | `TRANSACTION.PENDING.UPDATED` | `status` field changes from `PENDING` to `DECLINED` to `DECLINED`. Additional risk data may be placed in `user_data`. |
| Fraud service accepts transaction | `TRANSACTION.PENDING.UPDATED` | Additional risk data may be placed in `user_data`. |
| Transaction expires | `TRANSACTION.PENDING.UPDATED` | `status` field changes from `PENDING` to `EXPIRED`. |
| Transaction is posted to account | `TRANSACTION.PENDING.UPDATED`, `TRANSACTION.POSTED.CREATED` | Pending transaction `status` changes from `PENDING` to `POSTED`. A new "posted" transaction is created. |
## Transaction History
Synctera provides 2 endpoints for viewing transactions:
1. [List pending transactions](/v2/reference/listpendingtransactions) retrieves all "pending" or "unsettled" transaction within a given time period
2. [List posted transactions](/v2/reference/listpostedtransactions) returns all "posted" or "settled" transactions within a given time period
You can also take advantage of the `TRANSACTION` [Webhook](/v2/docs/webhooks-guide)) events to build your own transaction feed tailored to your specific use case.