Reconciliation

Automate bookkeeping.

When it comes to transactions, some things are just out of your hands. But that does not mean they need to be out of your control. Switch taps into the settlement information through the ingestion of transaction statements from providers and makes it accessible and operable for merchants. This means that, although Switch is not involved in the actual fund transfers, through our Reconciliation Application we match your transactions to the subsequent settlement batches, allowing you to monitor the applied fees and commissions.

With Reconciliation you can keep track of settlements, agreements and disputes. Matching provider requirements with customers' needs can be tricky. Reconciliation is here to bridge the gap.

  1. 1
    Create

    Set up the ground rules to your payment operation by creating Sources. This element can be originated from provider’s transaction statements, for example.

  2. 2
    Search

    Sift through settlements, disputes and agreements without fuss.

  3. 3
    Dispute

    Follow the entire plot of your disputes from the first notification to the final arbitration.

  4. 4
    Agreement

    Compare the commissions defined on the agreements set with the provider and make sure it all adds up.

There are three main steps to the inner workings of Reconciliation. This process is all about mediating the information supplied by providers, making it understandable and operable to merchants. Reconciliation draws from Processing to bridge the gap between the merchant and its providers of choice. It is the next step in your payment operation: understanding the sum of your transactions, balancing inconsistencies and tending to disagreements and disputes.

  1. 1
    Transaction Statement Conversion

    Reconciliation automatically ingests and processes the transaction statements produced by providers, in whichever format they might be presented.

  2. 2
    Settlement Lifecycle Events

    Drawing from the transaction statements, Reconciliation translates this information into detailed settlement lifecycle events (e.g. payment.settled; refund.settled; dispute.settled).

  3. 3
    Agreement Matching

    Through Reconciliation, merchants are able to verify the amounts in settlement batches generated from transaction statements, matching their expectations and detecting inconsistencies, namely when it comes to charged fees.

Settlements and Batches

A settlement signals the transfer of funds from a provider to a merchant. Settlements originate from transaction statements shared with Switch by providers. These statements describe all transactions in the settlement batch transferred to the merchant’s bank account. Transactions processed by Switch are settled automatically, and incorporated into the lifecycle events. This service can be used to get the existing settlements and batches.

GET /v1/reconciliation/settlements

PathMethodDescription

Sandbox https://merchant-api-test.switchpayments.com/v1/reconciliation/settlements
Production https://merchant-api.switchpayments.com/v1/reconciliation/settlements

GETFilter the available settlements by object id or date.
Request Parameters

pageNumber

Page number.


batch_idString

Filter by batch, using the corresponding batch ID.


charge_typeString

Filter by charge_type, a Parameters that stands for the different available payment methods.


object_idString

Filter by object_id, such as payment ID.


object_typeString

Filter by object_type, such as charge, instrument, and payment.


start_datedate

Filter by settlements beginning on the selected date.


end_datedate

Filter by Settlements ending on the selected date.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/reconciliation/settlements?merchant_id=accountId -u accountId:APIKey
Response Parameters

collectionArray

List of settlement objects.


filtersJSON Object

Provided filters.


paginationJSON Object

Pagination details.

RESPONSE: HTTP 200
{
"collection": [
"...",
{
"id": "bcc4f378718686c3b563be5d2dc4b8394d9b21ec5beb3555",
"amount": 38.0,
"batch_id": "2b33f091ab6fca5ebef37a31ab5ea1a9a21484b75ceef555",
"charge_type": "paypal",
"commissions": {
"acquirer_markup": null,
"arbitration_rate": null,
"card_scheme_rate": null,
"chargeback_rate": null,
"domestic_rate": null,
"flat_rate": 0.1,
"interchange_rate": null,
"interregional_rate": null,
"intraregional_rate": null,
"prearbitration_rate": null,
"refund_rate": null,
"retrieval_rate": null,
"second_chargeback_rate": null,
"three_ds_rate": null,
"total": 0.18,
"variable_rate": 0.08,
"vat": null
},
"created_at": "2018-11-13T20:13:02.827566+00:00",
"currency": "EUR",
"fx_rate": 1,
"metadata": null,
"object_id": "a4e23bb8e26b58cf4f60894afa9118280accce105beae555",
"object_type": "payment",
"processor": "acapture",
"settled_at": "2018-11-13T15:03:35.475000+00:00",
"transaction_amount": 38.18,
"transaction_currency": "EUR",
"updated_at": "2018-11-13T20:13:02.827611+00:00"
}
],
"filters": {},
"pagination": {
"page": 1,
"per_page": 20,
"total_pages": 1,
"total_items": 1
}
}

GET /v1/reconciliation/settlements/{id}

PathMethodDescription

Sandbox https://merchant-api-test.switchpayments.com/v1/reconciliation/settlements{id}
Production https://merchant-api.switchpayments.com/v1/reconciliation/settlements{id}

GETGet the details of a specific settlement element.
Response Parameters

idString

The settlement ID.


amountFloat

The amount settled.


batch_idString

The corresponding Batch ID.


charge_typeString

The corresponding payment method.


commissionsJSON Object

The charged commissions.


created_atDate

The date in which the settlement was created.


currencyString

The currency of applied in the settlement.


fx_rateFloat

The exchange rate applied.


metadataJSON Object

Metadata fields.


object_idString

The ID of the object that was settled.


object_typeString

The type of object that was settled (e.g. "payment").


processorString

The provider considered in the transaction.


settled_atDate

The date in which the transaction was settled.


transaction_amountFloat

The amount of the original transaction.


transaction_currencyString

The currency of the original transaction.


updated_atDate

The date when the settlement was last updated.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/reconciliation/settlements/settlementID?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"id": "bcc4f378718686c3b563be5d2dc4b8394d9b21ec5beb3555",
"amount": 38.0,
"batch_id": "2b33f091ab6fca5ebef37a31ab5ea1a9a21484b75ceef555",
"charge_type": "paypal",
"commissions": {
"acquirer_markup": null,
"arbitration_rate": null,
"card_scheme_rate": null,
"chargeback_rate": null,
"domestic_rate": null,
"flat_rate": 0.1,
"interchange_rate": null,
"interregional_rate": null,
"intraregional_rate": null,
"prearbitration_rate": null,
"refund_rate": null,
"retrieval_rate": null,
"second_chargeback_rate": null,
"three_ds_rate": null,
"total": 0.18,
"variable_rate": 0.08,
"vat": null
},
"created_at": "2018-11-13T20:13:02.827566+00:00",
"currency": "EUR",
"fx_rate": 1,
"metadata": null,
"object_id": "a4e23bb8e26b58cf4f60894afa9118280accce105beae555",
"object_type": "payment",
"processor": "acapture",
"settled_at": "2018-11-13T15:03:35.475000+00:00",
"transaction_amount": 38.18,
"transaction_currency": "EUR",
"updated_at": "2018-11-13T20:13:02.827611+00:00"
}

GET /v1/reconciliation/batches

PathMethodDescription

Sandbox https://merchant-api-test.switchpayments.com/v1/reconciliation/batches{id}
Production https://merchant-api.switchpayments.com/v1/reconciliation/batches{id}

GETGet the details of a specific batch element.
Response Parameters

amountFloat

The total amount of the transactions in this batch.


batch_idString

The Batch ID.


balanceFloat

The total amount settled in this batch.


batch_dateDate

The date the batch was created.


currencyString

The currency considered in the batch.


filesArray

The files associated with this batch.


number_of_transactionsNumber

The number of transactions in this batch.


processorString

The provider associated with this batch.


total_commissionsFloat

The total sum of the transaction commissions.


total_disputesNumber

The number of dispute transactions.


total_paymentsNumber

The number of payment transactions.


total_refundsNumber

The number of refund transactions.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/reconciliation/batches?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"amount": 38.18,
"batch_id": "2b33f091ab6fca5ebef37a31ab5ea1a9a21484b75ceef555",
"balance": 38.0,
"batch_date": "2018-11-13T15:03:35.475000+00:00",
"currency": "EUR",
"files": null,
"number_of_transactions": 1,
"processor": "acapture",
"total_commissions": 0.18,
"total_disputes": 0,
"total_payments": 1,
"total_refunds": 0
}

Sources

Sources store the files which initiate a settlement process, namely transaction statements.

PathMethodDescription

Sandbox https://merchant-api-test.switchpayments.com/v1/reconciliation/sources
Production https://merchant-api.switchpayments.com/v1/reconciliation/sources

POSTAdd a new source element.
Request Parameters

processorStringRequired

Provider associated with this source.


source_typeStringRequired

Type of source being created. Possible source types include: provider statement, summary statement, webhook, fraud notification, retrieval notification, chargeback notification, chargeback reversal notification, representment notification, second chargeback notification, pre arbitration notification, and API.


fileRequired

Source file being added.


source_groupString

Group the source is part of. A group represents a set of sources that are processed at the same time since they share several dependencies.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/reconciliation/sources?merchant_id=accountId -u accountId:APIKey '{
"processor": "acapture"
"source_type": “provider_statement”
"file": (binary)
"source_group": “f960f941920a930d8978cd1b1f8a0396170d419e5f2ad27”
}'
Response Parameters

channelsString

Channels associated with this source.


created_atDate

Date and time in which the source was created (ISO 8601).


failure_codeNumber

For elements that failed to be created, this field will document the associated error code.


failure_descriptionString

Documents a user interface description of why this particular element failed to be created.


file

Source file being added.


filenameString

Designation given to the source file.


idString

Unique identifier for the source.


processorString

Provider associated with this source.


source_group_idString

Identification of the group the source is part of. A group represents a set of sources that are processed at the same time since they share several dependencies.


source_typeString

Type of source in question. Possible source types include: provider statement, summary statement, webhook, fraud notification, retrieval notification, chargeback notification, chargeback reversal notification, representment notification, second chargeback notification, pre arbitration notification, and API.


stateString

Documents the execution status for the source action. added: the source was successfully processed. error: the source could not be processed.

RESPONSE: HTTP 201
{
channels: []
created_at: "2020-08-05T15:38:09.415882+00:00"
failure_code: null
failure_description: null
file:[]
filename: "imaginary_source.pdf"
id: "364faa805c929c6ee08869658479ba1e3539940b5f2ad260"
processor: "acapture"
source_group_id: "f960f941920a930d8978cd1b1f8a0396170d419e5f2ad260"
source_type: "provider_statement"
state: "added"
}

Agreements

Agreements set the different rates applicable to your transactions. They include the fees contracted upon a merchant agreement set between a provider and a merchant. It is important to keep tabs on agreements, so you can make sure fees are being correctly deducted from settlement batches.

GET /v1/agreements/{id}

PathMethodDescription

Sandbox https://merchant-api-test.switchpayments.com/v1/reconciliation/merchants/{merchant_id}/agreements
Production https://merchant-api.switchpayments.com/v1/reconciliation/merchants/{merchant_id}/agreements

GETGet the list of existing agreements.
Response Parameters

agreement_idString

Unique identifier for the agreement in question.


charge_typeString

Payment method to which the agreement applies.


enabledFloat

Indicates whether the current agreement is active or not. true: the agreement is applicable. false: the agreement is not active at the moment.


processorDate

Provider associated with the agreement.


created_atDatetime

Date in which the agreement was added.


updated_atDatetime

Date in which the agreement was last updated.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/reconciliation/batches?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"agreement_id": "id",
"charge_type": "yandex",
"enabled": true,
"processor": "yandex",
"created_at": "2020-03-10 15:18:28",
"updated_at": "2020-03-10 15:18:28"
}

Disputes

A dispute occurs when a consumer questions a payment through their issuer. For instance, when it comes to card networks there are four different types of disputes: retrieval, chargeback, second chargeback/pre-arbitration, and arbitration. These are different stages of the dispute process, and each one represents a dispute element in the Switch Platform.

Disputes are automatically generated from sources in the Switch Platform, therefore it is not possible to create a dispute element. Nonetheless, you are still able to consult specific disputes using their respective IDs. This task can be accomplished through the Transactions API as follows.

GET /v1/transactions/disputes/{id}

PathMethodDescription

Sandbox https://merchant-api-test.switchpayments.com/v1/sources/refunds
Production https://merchant-api.switchpayments.com/v1/sources/refunds

GETGets the details of a dispute element.
Response Parameters

dispute_idString

The dispute ID.


payment_idString

The payment ID the dispute refers to.


processorString

The provider the dispute refers to.


sourceJSON Object

The source of the dispute.


typeString

Type of the dispute. Possible values include: arbitration, chargeback, chargeback_reversal, pre_arbitration, retrieval, 2nd_chargeback.


amountFloat

The dispute amount.


currencyString

The currency of the dispute.


descriptionString

Dispute description.


fx_rateFloat

Exchange rate.


metadataJSON Object

Arbitrary information included in the dispute source.


external_idsJSON Object

Useful external IDs (e.g. IDs from the processing channel).


requires_settlementBoolean

Whether the dispute requires settlement.


created_atString

The date when the dispute was created.


disputed_atString

The date when the dispute was initiated.


updated_atString

Date when the dispute was last updated.


merchant_idString

The merchant ID the dispute refers to.


charge_idString

The charge ID the dispute refers to.


instrument_idString

The instrument ID the dispute refers to.


settlement_idString

The settlement ID.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/transactions/disputes/{id}?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"dispute_id": "463c1e0f24c584ce6d7088f8f18f5cde92013b6d5cf7d97a",
"payment_id": "adda6c8da9d9fa644332f7dbb7e3e6fed7983af95cf7d946",
"processor": "acapture",
"source": {
"interface": "chargeback_notification",
"producer": "com.switchpayments.reconciliation-api"
},
"type": "chargeback",
"amount": 5,
"currency": "EUR",
"description": "Cardholder Dispute—Defective Merchandise/Not as Described",
"fx_rate": 1,
"metadata": {
"Member ID": "5014811",
"Reason Code": "4853",
"Processed Transaction ID": "1492110123",
"Original Transaction Amount": "297.36",
"Processed Transaction Guid": "6faec70d-5159-4504-a1d4-fcaea5e291b1",
"Card Type": "Mastercard",
"Issuers Message": "SERVICES NOT RENDERED",
"Card Holder": "MARCIA D F RUNGE",
"MID": "75056333",
"First Chargeback Date": "22-June-2018",
"Currency": "EUR",
"Amount": "5",
"Original Transaction Currency": "CHF",
"Deadline": "02-July-2018",
"Original Transaction Date": "30-May-2018 10:13:56 PM",
"Reason Description": "Cardholder Dispute—Defective Merchandise/Not as Described",
"Tracking Member Code": "8ac7a4a06b2284a6016b2828c1e24aab",
"Card Last 4 Digits": "5190",
"Member Name": "MMM Investments",
"Acquirer Name": "Payvision",
"ARN": "85101578150821331281973"
},
"external_ids": {
"Processed Transaction Guid": "6faec70d-5159-4504-a1d4-fcaea5e291b1",
"Tracking Member Code": "8ac7a4a06b2284a6016b2828c1e24aab",
"Processed Transaction ID": "1492110123",
"ARN": "85101578150821331281973"
},
"requires_settlement": true,
"created_at": "2019-06-05T15:02:18.755000+00:00",
"disputed_at": "2018-06-22T00:00:00+00:00",
"updated_at": "2019-06-05T15:02:18.755000+00:00",
"merchant_id": "83216372132918dshdashdasi31232",
"charge_id": "0a7367c85f0743bd11a48a8ee8e4d97cfd37a4995cf7ce2a",
"instrument_id": "62427662820c880db073752fc82c3e72b16f91895cf7ce31",
"settlement_id": null
}

Next Steps

Get to know more about how to detect and block fraud. Check out our Risk Application.