Transactions

Overview

A "transaction" in the Synctera platform represents any movement of funds between accounts.

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 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:

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 and Posted Transactions 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 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):

{
  "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:

{
  "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 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 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, 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:

TypeSubtype
achincoming_credit
achincoming_credit_contested_return
achincoming_credit_dishonored_return
achincoming_credit_return
achincoming_credit_reversal
achincoming_debit
achincoming_debit_contested_return
achincoming_debit_dishonored_return
achincoming_debit_return
achincoming_debit_reversal
achoutgoing_credit
achoutgoing_credit_contested_return
achoutgoing_credit_dishonored_return
achoutgoing_credit_return
achoutgoing_credit_reversal
achoutgoing_debit
achoutgoing_debit_contested_return
achoutgoing_debit_dishonored_return
achoutgoing_debit_return
achoutgoing_debit_reversal
achtemp_hold
cardatm_withdrawal
cardatm_withdrawal_reversal
cardcard_transaction
cardcard_transaction_reversal
cardpos_cashback
cardpos_cashback_reversal
cardpos_purchase
cardpos_purchase_refund
cardpos_purchase_refund_reversal
cardpos_purchase_reversal
cardpos_refund
cardpos_refund_reversal
cardprovisional_credit
cardprovisional_credit_reversal
checkmobile_deposit
checkmobile_deposit_reversal
checkmobile_deposit_return
checkmobile_deposit_return_reversal
external_cardcard_funding
external_cardcard_funding_reversal
external_cardcard_send
external_cardcard_send_reversal
internal_transferaccount_decrease_limit
internal_transferaccount_decrease_limit_reversal
internal_transferaccount_increase_limit
internal_transferaccount_increase_limit_reversal
internal_transferaccount_to_account
internal_transferaccount_to_account_reversal
internal_transferach_credit_sweep
internal_transferach_credit_sweep_reversal
internal_transferach_debit_sweep
internal_transferach_debit_sweep_reversal
internal_transfercashback
internal_transfercashback_reversal
internal_transferfee
internal_transferfee_reversal
internal_transferincoming_wire
internal_transferincoming_wire_reversal
internal_transferinterest_payout
internal_transferinterest_payout_reversal
internal_transferjit_fund
internal_transferjit_fund_reversal
internal_transferloc_usage
internal_transferloc_usage_reversal
internal_transfermanual_adjustment
internal_transfermanual_adjustment_reversal
internal_transferoutgoing_international_remittance
internal_transferoutgoing_international_remittance_reversal
internal_transferprogram_decrease
internal_transferprogram_decrease_reversal
internal_transferprogram_expansion
internal_transferprogram_expansion_reversal
internal_transferpromotional_credit
internal_transferpromotional_credit_reversal
internal_transferrepayment
internal_transferrepayment_reversal
internal_transfersign_up_bonus
internal_transfersign_up_bonus_reversal
internal_transfersubscription_fee
internal_transfersubscription_fee_reversal
internal_transfertransfer_fee
internal_transfertransfer_fee_reversal
wireoriginated
wirereceived

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:

ScenarioWebhook event(s)Notes
A hold is placed on an accountTRANSACTION.PENDING.CREATED
Hold amount is increased or decreasedTRANSACTION.PENDING.UPDATEDFinal amount is reflected in total_amount.
Fraud service declines transactionTRANSACTION.PENDING.UPDATEDstatus field changes from PENDING to DECLINED to DECLINED. Additional risk data may be placed in user_data.
Fraud service accepts transactionTRANSACTION.PENDING.UPDATEDAdditional risk data may be placed in user_data.
Transaction expiresTRANSACTION.PENDING.UPDATEDstatus field changes from PENDING to EXPIRED.
Transaction is posted to accountTRANSACTION.PENDING.UPDATED, TRANSACTION.POSTED.CREATEDPending 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 retrieves all "pending" or
    "unsettled" transaction within a given time period
  2. List posted transactions returns all "posted" or "settled"
    transactions within a given time period

You can also take advantage of the TRANSACTION Webhook) events to build your own transaction feed tailored to your specific use case.