In this guide, we first break down the different types of events that can make up a disbursement and then how to group the disbursementEntries that make up the disbursement total to reconcile what was funded.

For more information on entries please review the entries event field in our API Documentation here: https://portal.payrix.com/docs/api#entriesResponse

Different Type of Events

Entries overall represent money movement in the Payrix system and are always associated with an event that indicates what triggered the entry or money movement. This is true for Disbursements AND Transaction Entries.

A disbursementEntry is a line-by-line item of what made up a disbursement total and will have an Event defining what triggered the creation entry and in turn the disbursementEntry.

NOTE: An event can relate to different types of entries. For example, a capture event of 7 can be associated with an entry recording a processed transaction and also associated with an entry related to a fee.

This guide is specific to Disbursement Entries, and will divide the activity breakdown into three sections:

  1. Transactional Events (associated with Disbursements)

  2. Fees (that are not associated with a transactional event)

  3. Other (chargebacks, rollovers, etc.)

Transactional Events

A Transactional Event is any instance where funds are credited or debited from the merchant balance as part of standard transaction processing.

These includes Events:

  • Credit Card Sales

    • disbursementEntries.event 7

  • Credit Card Refunds

    • disbursementEntries.event 8

  • eCheck Sales

    • disbursementEntries.event 21

  • eCheck Refunds

    • disbursementEntries.event 22

  • Chargebacks

    • disbursementEntries.event 11 & 20

  • eCheck Returns

    • disbursementEntries.event 23

For each of these events above we can find how much was credited/debited as part of the original triggering event (i.e - eCheck Sale transaction) in addition to how much was debited from the balance for fees incurred on that triggering event.

NOTE: Fees for a triggering event, such as a Credit Card Sale, may not all be included within the same disbursement.

A common example is an Auth fee on a Credit Card Sale being included in one disbursement and then the Credit Card Sale and a fee associated with the Capture of that transaction being included in the next disbursement when the transaction has funded.

This section only covers fees that are included in the same disbursement as the triggering event. If the event generated fees that affected a different disbursement (i.e - Auth fee), then those fees are discussed in the “Other Fees” section.

Event ID

Event Type

Event Amount

Txn ID

Txn Amount

Txn Cardholder

Fee Amount

Event Net

p1_txn_1

CC Sale

$100

p1_txn_1

$100

John Smith

$5

$95

p1_txn_2

eCheck Refund

-$50

p1_txn_2

$50

Jane Smith

$2

-$52

p1_chb_1

Chargeback

-$100

p1_txn_3

$100

John Smith

$30

-$130

NOTE: A record ID that begins with p1 = Production and one that begins with t1 = Sandbox.

Other Fees

This will be a list of all fees that were not included in the Transactional Events section.

A fee is excluded from the Transactional Events section for two possible reasons:

  1. The fee is not related to a transactional event such as a boarding fee or a scheduled fee (daily, weekly, monthly, annual fee).

  2. The fee is related to a transactional event but is in a different disbursement than other entries associated with that triggering event (or original event activity) such as an Auth fee.

Entry ID

Event Type

Event ID

Amount

Event Net

p1_etr_1

Boarding

p1_mer_1

$5

-$5

p1_etr_2

Auth

p1_txn_4

$1

-$1

Other

Any event that is not a Transactional Event or Other Fee event is covered in this section:

Other events are related to the activity that impacts what was funded to the merchant. This can include a Risk Decision putting a transaction on reserve, an adjustment to move funds from one entity account to another, fees being refunded, or a rollover.

There are various factors that can lead to a rollover event; however, the most common is a fractional penny. This is where a fee (percentage or interchange) does not equal a full penny and thus the fractional pennies are rolled over to the next disbursement until it equals $0.01 and can be funded.

Other factors that can lead to a rollover are typically related to activity impacting the balance negatively such as a pending event that hasn’t fully processed.

Event Type

Event Value Example

Adjustments (Event 18)

$50

Fee Refunds (Event 47)

$5

Reserve (Event 36)
Reserve Release (Event 37)

-$10
+$10

Rollover/Remainder (Event 40)
Rollover/Remainder Used (Event 41)

-$0.005
+$0.005

Reconciling a Disbursement

This section breaks down the disbursement data and how you can retrieve the necessary events to break-down what made up the disbursement total and what was funded. This section will discuss how to loop through the data and organize it into “buckets” that can be used to reconcile the disbursement amount.

Step 1 - Disbursement Data

To get data around how much was disbursed and when it was disbursed query the disbursements endpoint. This endpoint provides a summary of what was funded to the entity account.

GET /disbursements/<dbm id>
CODE
  • created : The timestamp when the disbursement was requested.

  • processed : The timestamp when the disbursement was sent for funding.

  • amount : The amount to be disbursed.

Step 2 - Disbursement Entry Data

To get data on the activity that made up the disbursement total, query the disbursementEntries endpoint.

NOTE: Our API returns 30 records by default; however, this can be expanded to return 100 records. Depending on the size of the disbursement use pagination to retrieve all the records until the query details page hasMore is false

For more information on pagination and how to increase the number of records returned in a query reference API Call Syntax

GET /disbursementEntries?expand[entry][]
Search: disbursement[equals]=<dbm id>
CODE

Once all the disbursementEntries associated with the disbursement has been pulled, loop through all the data to place each entry in the proper bucket based on the type of events outlined at the beginning of this guide.

Step 3 - Disbursement Entry Looping/Bucketing

1. Create Entry and Output Buckets

We will start by splitting our disbursemnetEntries into two “buckets”:

  1. EventEntries - This “bucket” will contain any disbursementEntry that is not associated with an entry (such as a rollover of funds) OR is an entry not associated with a fee and is tied to the triggering entry.

    1. Pull all disbursemnetEntries where disbursemnetEntry.entry is null ORdisbursemnetEntry.entry.isFee is 0. This can be done in a single API request or multiple:

      Multiple API Requests example:

      GET /disbursementEntries
      SEARCH entry[equals]=0
      
      OR
      
      GET /disbursementEntries
      SEARCH entry[isFee][equals]=0
      CODE


      Single API Request example:

      GET /disbursementEntries
      SEARCH or[0][entry][equals]=0&or[0][entry][isFee][equals]=0
      CODE

  2. FeeEntries - This “bucket” will contain any disbursementEntry that is associated with a fee that was triggered due to the originating event such as a fee related to a captured transaction.

    1. Pull all disbursemnetEntries where disbursemnetEntry.entry.isFee is 1

      GET /disbursementEntries
      SEARCH entry[isFee][equals]=1
      CODE

We will also initialize three output “buckets” based on the different type of events:

  1. OutputTxnEvents

  2. OutputOtherFees

  3. OutputOther

Examples to be provided

2. Loop through EventEntries

We will loop through the EventEntries obtained in step 1 and add them to their proper “bucket” based on the EventType. An entry is created and is a record of the movement of funds. In order to get details on the event itself such as the transaction that triggered the capture or refund fee we will want to reference the disbursementEntries.entry

The EventType will be based on the disbursemnetEntry.event.

In this example, we provide an example of how to get detailed event data.

EventType = 7 (Capture) or 21 (ECSale)

You can get the full transaction data by expanding the eventId within the entry or by querying the txns endpoint with the transaction associated with the disbursement.entry.txn.

Expanding the EventId:

GET /entries?expand[eventId][]
CODE


Querying Txn Endpoint:

GET txns
Search: id[equals]=<disbursementEntry.entry.txn>
CODE

Using the data collected from disbursementEntries in ‘1 EventEntries’ and the transaction data pulled above this will need to be pushed to an OutputTxnEvents “bucket”:

Entry

Description

Fields

Event ID

The event that triggered the movement of funds and is associated with the disbursementEntry.

disbursemnetEntry.eventId

Event Type

The type of event that triggered the event (i.e - Capture, ECSale, etc.)

disbursemnetEntry.event

Event Amount

The total amount of the disbursementEntry, this is displayed to the cent in the API. (e.g - 500 = $5.00)

disbursemnetEntry.amount

Txn ID

The transaction associated with the disbursementEntries.entry.txn that triggered the event.

txn.id

Txn Amount

The transaction approved amount. This can differ from the txn.total such as in the event of a partial approval or partial reversal.

txn.approved

Txn Cardholder

The cardholder name that initiated the transaction. This is only populated if supplied on the transaction or associated with a customer such as if a transaction.

txn.first + txn.last

Fee Amount

This is a placeholder for fees associated with the transaction, which will be retrieved in Step 3: Loop through FeeEntries.

0

Event Net

The net amount of the event that moved funds and created a disubursementEntry.

disbursemnetEntry.amount

A fee on a txn resource is only populated if the fee was submitted on the initial transaction. This field txns.fee is used for reporting purposes and is not charged on the transaction unless a Fee Listener is set up. For more information on a Fee Listener please reference this document: How to Create & Configure Custom Fees

Traditional fees set up in the system will always be represented as an entry associated with the txn.

EventType = 8 (Refund) or 22 (ECRefund)

Similar to above to get data for refunds you will get the transaction details associated with the entry by expanding the eventId or querying the txn endpoint using the transaction associated with the disbursementEntries.entry.txn. Additionally, we will expand the related transaction forTxn, which is the original transaction that is being refunded.

Expanding the EventId:

GET /entries?expand[eventId][fortxn][]
CODE


Querying Txn Endpoint:

GET txns?expand[fortxn][]
Search: id[equals]=<disbursemnetEntry.entry.txn>
CODE

Using the data collected from disbursementEntries in ‘1 EventEntries’ and the transaction data pulled above this will need to be pushed to the OutputTxnEvents bucket:

Entry

Description

Fields

Event ID

The event that triggered the movement of funds and is associated with the disbursementEntry.

disbursemnetEntry.eventId

Event Type

The type of event that triggered the event (i.e - Capture, ECSale, etc.)

disbursemnetEntry.event

Txn ID

The transaction associated with the disbursementEntries.entry.txn that triggered the event.

txn.id

Txn Amount

The total amount of the disbursementEntry, this is displayed to the cent in the API. (e.g - 500 = $5.00)

disbursemnetEntry.amount

Txn Cardholder

The cardholder name that initiated with the original transaction and is associated with the refund transaction. This is only populated if supplied on the transaction or associated with a customer such as if a transaction.

txn.first + txn.last or txn.fortxn.first + txn.fortxn.last

Fee Amount

This is a placeholder for fees associated with the transaction, which will be retrieved in Step 3: Loop through FeeEntries.

0

Event Net

The net amount of the event that moved funds and created a disubursementEntry.

disbursemnetEntry.amount

EventType = 11 (Chargeback) or 20 (Arbitration)

Similar to a transaction in order to get all the information related to a chargeback, and not just the details of the entry, we will expand the eventId or query the chargebacks endpoint using the chargeback associated with the disbursement.entry.chargeback.

Expanding the EventId:

GET /entries?expand[eventId][txn][]
CODE


Querying Txn Endpoint:

GET chargebacks?expand[txn][]
Search: id[equals]=<disbursementEntry.entry.chargeback>
CODE

Using the data collected from disbursementEntries in ''1 EventEntries and the chargeback data pulled above this will also need to be pushed to the OutputTxnEvents bucket:

Event

Description

Fields

Event ID

The event that triggered the movement of funds and is associated with the disbursementEntry.

disbursementEntry.eventId

Event Type

The type of event that triggered the event (i.e - Chargeback.)

disbursementEntry.event

Event Amount

The total amount of the disbursementEntry, this is displayed to the cent in the API. (e.g - 500 = $5.00)

disbursementEntry.amount

Txn ID

The transaction associated with the disbursementEntries.entry.chargeback that was issued a chargeback.

chargeback.txn.id

Txn Amount

The transaction approved amount for the original transaction issued the chargeback.

chargeback.txn.approved

Txn Cardholder

The cardholder name that initiated with the original transaction and is associated with the transaction that was issued the chargeback.

chargeback.txn.first + chargeback.txn.last

Fee Amount

This is a placeholder for fees associated with the chargeback, which will be retrieved in Step 3: Loop through FeeEntries.

0

Event Net

The net amount of the event that moved funds and created a disubursementEntry.

disbursemnetEntry.amount

Other EventType

For any EventType that is not listed within EventEntries above, we will push to an OutputOther “bucket”. These can be grouped by event type.

  • Event Type: disbursemnetEntry.event

  • Event Net: disbursemnetEntry.amount

3: Loop through FeeEntries

Now we will loop through the disbursementEntries collected from Step 2 FeeEntries and add them to the proper “bucket” based on the disbursemnetEntry.event. In order to get information such as the txn that triggered the interchange or associated with the chargeback we will want to reference the disbursementEntry.entry.originalEventId.

The originalEventID associated with an entry is a reference to the underlying event that triggered the money movement. These are primarily used for events where the entry.eventId points to a related record (such as an assessment for an interchange entry) but does not indicate the original event that triggered the assessment (i.e - The transaction that triggered the assessment and then the interchange fee schedule).

These will be events 13 (assessments), 26 (profit share), & 47 (entry refund).

In this example, we provide an example on how to get detailed event data.

In the future adding ?expand[originalEventId][] to the request will get all the details in a single API call. At this time you will need to obtain the originalEventId and then query the associated endpoint.

EventType = 13 (Interchange)

In order to get data on assessments and find the original transaction, you will reference the disbursement.entry.originalEventId. You can also expand the eventId to get information on the assessment.

Getting Data on the Assessment:

Expanding the EventId:

GET /entries?expand[eventId][]
CODE


Querying Assessments Endpoint:

GET assessments
Search: id[equals]=disbursemnetEntry.eventId
CODE


Finding Original Transaction:

GET txns
Search: id[equals]=<disbursementEntry.entry.originalEventId>
CODE

In the assessments endpoint if the entry.originalEventId or assessment.eventId matches a transaction ID obtained when creating the OutputTxnEvent bucket, then you should increment the FeeAmount and EventNet for the record created by the disbursementEntry.amount.

If the assessments.eventId does not equal a transactional event retrieved in Step 2 then this should be pushed to the OutputOtherFees “bucket”.

Entry

Description

Fields

Entry ID

The event that triggered the movement of funds and is associated with the disbursementEntry.

disbursemnetEntry.entry.id

Event Type

The type of event that triggered the event (i.e - Fee.)

disbursemnetEntry.event

Event ID

The ID of the event that triggered the assessment event.

assessment.eventId

Amount

The negative amount that made up the assessment total that was incurred

disbursemnetEntry.amount

Event Net

The net amount of the event that moved funds and created a disubursementEntry.

disbursemnetEntry.amount

EventType = 6 (Auth), 7 (Capture), 8 (Refund), 11 (Chargeback), 20 (Arbitration), 21 (ECSale), 22 (ECRefund), 23 (ECReturn), 24 (Settlement)

Similar to the above if any of the fees associated to these events match a transaction ID obtained when creating the OutputTxnEvents bucket, then increment If disbursemnetEntry.eventId matches the EventId of an element in the OutputTxnEvents bucket, then you should increment the FeeAmount and EventNet for the record created by the disbursementEntry.amount.

If not the fees do not equal a transactional event retrieved in Step 2 then this should be pushed to the OutputOtherFees bucket.

Event

Description

Fields

Entry ID

he event that triggered the movement of funds and is associated with the disbursementEntry.

disbursemnetEntry.entry.id

Event Type

The type of event that triggered the event (i.e - Transaction, Chargeback, etc.)

disbursemnetEntry.event

Event ID

The ID of the event that triggered the fee event.

disbursemnetEntry.eventId

Amount

The negative amount that made up the fee total that was incurred.

disbursemnetEntry.amount

Event Net

The net amount of the event that moved funds and created a disubursementEntry.

disbursemnetEntry.amount

Other EventType

Any other fee not associated to the EventTypes listed above should be pushed to the OutputOtherFees bucket:

Event

Description

Fileds

Entry ID

The event that triggered the movement of funds and is associated with the disbursementEntry.

disbursemnetEntry.entry.id

Event Type

The type of event that triggered the event (i.e - boarding, NOC, etc.)

disbursemnetEntry.event

Event ID

The ID of the event that triggered the fee event.

disbursemnetEntry.eventId

Amount

The negative amount that made up the fee total that was incurred.

disbursemnetEntry.amount

Event Net

The net amount of the event that moved funds and created a disubursementEntry

disbursemnetEntry.amount