Reconciling a Disbursement
In this guide, we first break down the different types of events that can make up a disbursement and then how to group the Disbursement Entries (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
Warning: Certain Interchange Fees that amount to less than a full cent ($0.01) will be displayed under Not Disbursed on a Disbursement Summary, as an undisbursed amount rollover.
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>
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>
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”:
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.Pull all
disbursemnetEntries
wheredisbursemnetEntry.entry
isnull
ORdisbursemnetEntry.entry.isFee
is0
. This can be done in a single API request or multiple:Multiple API Requests example:
CODEGET /disbursementEntries SEARCH entry[equals]=0 OR GET /disbursementEntries SEARCH entry[isFee][equals]=0
Single API Request example:
CODEGET /disbursementEntries SEARCH or[0][entry][equals]=0&or[0][entry][isFee][equals]=0
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.Pull all
disbursemnetEntries
wheredisbursemnetEntry.entry.isFee
is1
CODEGET /disbursementEntries SEARCH entry[isFee][equals]=1
We will also initialize three output “buckets” based on the different type of events:
OutputTxnEvents
OutputOtherFees
OutputOther
Step 3.1 Loop through EventEntries
We will loop through the EventEntries obtained in step 1 and add them to their proper “bucket” based on the Event Type. 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 Event Type will be based on the disbursemnetEntry.event
.
In this example, we provide an example of how to get detailed event data.
Event Type = 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][]
Querying Txn
Endpoint:
GET txns
Search: id[equals]=<disbursementEntry.entry.txn>
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. |
|
Event Type | The type of event that triggered the event (i.e - Capture, ECSale, etc.) |
|
Event Amount | The total amount of the disbursementEntry, this is displayed to the cent in the API. (e.g - 500 = $5.00) |
|
Txn ID | The transaction associated with the |
|
Txn Amount | The transaction approved amount. This can differ from the |
|
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. |
|
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. |
|
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.
Event Type = 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][]
Querying Txn
Endpoint:
GET txns?expand[fortxn][]
Search: id[equals]=<disbursemnetEntry.entry.txn>
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. |
|
Event Type | The type of event that triggered the event (i.e - Capture, ECSale, etc.) |
|
Txn ID | The transaction associated with the |
|
Txn Amount | The total amount of the disbursementEntry, this is displayed to the cent in the API. (e.g - 500 = $5.00) |
|
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. |
|
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. |
|
Event Type = 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][]
Querying Txn Endpoint:
GET chargebacks?expand[txn][]
Search: id[equals]=<disbursementEntry.entry.chargeback>
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. |
|
Event Type | The type of event that triggered the event (i.e - Chargeback.) |
|
Event Amount | The total amount of the disbursementEntry, this is displayed to the cent in the API. (e.g - 500 = $5.00) |
|
Txn ID | The transaction associated with the |
|
Txn Amount | The transaction approved amount for the original transaction issued the chargeback. |
|
Txn Cardholder | The cardholder name that initiated with the original transaction and is associated with the transaction that was issued the chargeback. |
|
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. |
|
Other Event Type
For any Event Type 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
Step 3.2: 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.
Event Type = 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][]
Querying Assessments Endpoint:
GET assessments
Search: id[equals]=disbursemnetEntry.eventId
Finding Original Transaction:
GET txns
Search: id[equals]=<disbursementEntry.entry.originalEventId>
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. |
|
Event Type | The type of event that triggered the event (i.e - Fee.) |
|
Event ID | The ID of the event that triggered the assessment event. |
|
Amount | The negative amount that made up the assessment total that was incurred |
|
Event Net | The net amount of the event that moved funds and created a disubursementEntry. |
|
Event Type = 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. |
|
Event Type | The type of event that triggered the event (i.e - Transaction, Chargeback, etc.) |
|
Event ID | The ID of the event that triggered the fee event. |
|
Amount | The negative amount that made up the fee total that was incurred. |
|
Event Net | The net amount of the event that moved funds and created a disubursementEntry. |
|
Other Event Type
Any other fee not associated to the Event Types listed above should be pushed to the OutputOtherFees bucket:
Event | Description | Fields |
---|---|---|
Entry ID | The event that triggered the movement of funds and is associated with the disbursementEntry. |
|
Event Type | The type of event that triggered the event (i.e - boarding, NOC, etc.) |
|
Event ID | The ID of the event that triggered the fee event. |
|
Amount | The negative amount that made up the fee total that was incurred. |
|
Event Net | The net amount of the event that moved funds and created a disubursementEntry |
|