Transaction reconciliation

This topic describes how to manage transaction reconciliation.

Reconciliation ensures the accuracy and validity of financial information by comparing transactions and activity to supporting documentation. The process may also involve resolving any discrepancies that are discovered. A good reconciliation process ensures that unauthorized changes have not occurred on transactions during processing.

Amount and result are the two main types of discrepancies. An amount discrepancy may occur if someone uses another system to partially refund a transaction.

The result discrepancy is the most commonly occurring. This occurs when an approved transaction is unintentionally marked as declined, canceled, or abandoned. In the event of a result discrepancy, fulfill the customer's order, or in some cases, void the order — for example, if a subsequent duplicate order was placed.

Occasionally, a transaction request may time out or have a connection issue. When this occurs, the result may be out of sync with the payment processor data. In addition, transactions may be completed offsite, where they may take upwards of days to complete and will have an updated result. Adjust gateway account settings to define the length of time in which Rebilly must wait for the completion of a suspended offsite transaction. The default value is 1 hour (3600 seconds). If a transaction is not completed within this time frame, Rebilly abandons the transaction. When reconciling transactions, keep this time frame in mind. For example, rather than retrieving transactions each minute, you may want to retrieve them up to an hour ago, or more.

Discrepancies should account for under 1% of all transactions. Almost all discrepancies are false declines, not false approvals.

Source of truth

The sources of truth are the payment processors. Rebilly attempts to reconcile in order to maintain accurate data, so that Rebilly can be used a surrogate source of truth.

Rebilly queries transactions that timeout or encounter connection errors immediately, and again within hours if unsuccessful.

Additionally, each day, Rebilly attempts to download and reconcile transaction data from the previous day to assess it against Rebilly recorded data. When this process is complete, the isReconciled transaction field is set to true. If a discrepancy is found, the hadDiscrepancy transaction field is set to true. Both of these fields can be used to support your own unique reconciliation approach.

Reconciliation approach

This process describes an approach for transaction reconciliation.

Depending on your specific systems, and how you manage data, adapt or adjust this approach to suit your needs.

1. Request a data export of a resource

Use the Download resource data process to request data from the previous hour at 30 minute intervals.

This data is reliable but not reconciled yet. If your data structure can accommodate it, track reconciliations and discrepancies. An alternative is to receive webhooks with transaction data for each processed transaction. This approach is asynchronous and does not delay transactions.

2. Retrieve export data from the previous 2 days

After a request, before querying the status of the data export, allow 2 minutes for the data export to complete. For large files that contain tens of millions of records, you may need to wait up to 5 or 10 minutes.

Use the Download resource data process to request data from the previous 2 days at 08:00 every day.

By now, most of this data may already be reconciled, this step ensures that there are no outstanding discrepancies.

Requesting data each day from the previous 2 days creates duplicate data. For example, on Monday you request transaction data from Saturday and Sunday, and on Tuesday you request data from Sunday and Monday. To manage duplicate data, use the unique transaction ID value to identify and determine if your systems must update or insert a record.

3. Retrieve export data from the previous week

Before querying the status of the data export after a request, allow 2 minutes for the data export to complete. For large files that contain tens of millions of records, you may need to wait up to 5 or 10 minutes.

Use the Download resource data process to request data from the previous week at 08:00 every day.

There should be very few discrepancies in the export, and every payment method that is capable of reconciling should already be reconciled, with discrepancies identified. Use arguments to limit the export to transaction with discrepancies.

Download resource data

This process describes how to download resource data. To use resource data to reconcile discrepancies, see Reconciliation approach.

1. Request the data export

Execute the Request the data export of a resource operation. To configure parameters, see Date ranges, Fields, and Arguments.

Example request

curl -XPOST 'https://api-sandbox.rebilly.com/experimental/organizations/your-organization-id/data-exports' \
-H 'Accept-Encoding: gzip, deflate, br' \
-H 'REB-APIKEY: your-private-key' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json, text/plain, */*' \
-H 'User-Agent: your-console-library' \
--data-binary '{"name":"test-export-2018-01-12","format":"csv","resource":"transactions","dateRange":{"start":"yesterday", "end":"today"}}' --compressed

In the response:

• id: Use this unique value to identify the data export request.
• status: pending: Specifies that the request was received but is not being processing yet. The sequence of statuses is pending, queued,processing, and then completed.

In the response, expand the _links object, and locate the download link.

2. Retrieve the download link

Using the ID from the request in the previous step, execute the Retrieve a data export request operation.

In the response, expand the _links object to obtain the download URL.

Example request

curl 'https://api-sandbox.rebilly.com/experimental/organizations/your-organization-id/data-exports/55746043-2850-4ed7-bc1e-b295c7748405' \
-H 'Accept-Encoding: gzip, deflate, br' \
-H 'REB-APIKEY: your-private-key' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json, text/plain, */*' \
-H 'User-Agent: your-console-library'

3. Download the file

Using the download URL from the previous step, execute the Download a file operation.

Example request

curl 'https://api-sandbox.rebilly.com/organizations/your-organization-id/files/6ba65349-5839-4934-a443-557a0d5370a0/download' \
-H 'Accept-Encoding: gzip, deflate, br' \
-H 'REB-APIKEY: your-private-key' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/json, text/plain, */*' \
-H 'User-Agent: your-console-library'

Configuration

This section provides request configuration information.

Date ranges

Use date ranges to limit the export data to a specific time frame.

Relative date range examples

Export data from yesterday:

'dateRange': { 'start': 'yesterday', 'end': 'today' }

Export data from the previous month:

'dateRange': { 'start': 'first day of last month midnight', 'end': 'first day of this month midnight' }

Export data from the last three days, starting at midnight:

'dateRange': { 'start': '3 days ago midnight', 'end': 'now' }

Additional valid date inputs:

• yesterday
• midnight
• today
• now
• noon
• tomorrow
• back of
• front of
• first day of
• last day of
• ago
• dayname

Absolute date range examples

Do not use absolute date ranges to create a recurring schedule for a data export. If an absolute range is used, it will result in the same exact data exporting each period.

When supplying a start or end date in absolute format, use the ISO 8601 format.

From 2018-01-21 at 15:15:15 until now:

This example combines absolute and relative dates.

'dateRange': { 'start': '2018-01-21T15:15:15Z', 'end': 'now' }

From 2018-01-21 at 15:15:15 until 2018-02-21 at 15:15:15:

This example uses two absolute dates.

'dateRange': { 'start': '2018-01-21T15:15:15Z', 'end': '2018-02-21T15:15:15Z' }

Fields

By default, the date range applies to the time at which a transaction is processed. To select another field, use the field attribute.

The following example describes how to apply a date range filter to the time at which a transaction is created.

"dateRange": {
    "start": "yesterday",
    "end": "today"
    "field": "createdTime"
}

If you do not find a field that meets your data export requirements, create your own Custom fields.

Arguments

Use arguments to filter, search, and sort the data in your export request.

'arguments': { 'filter': 'string', 'sort': 'string', 'q': 'string' }

Filter by approved:

'arguments': { 'filter': 'result:approved' }

Filter voids and refunds:

To filter by multiple values, separate filter names using a comma.

'arguments': { 'filter': 'type:void,refund' }

Filter approved voids and refunds:

To filter by multiple values, separate filter names using a comma.

'arguments': { 'filter': 'result:approved;type:void,refund' }