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
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
Search
Sift through settlements, disputes and agreements without fuss.
- 3
Dispute
Follow the entire plot of your disputes from the first notification to the final arbitration.
- 4
Agreement
Compare the commissions defined on the agreements set with the provider and make sure it all adds up.
Settlements and Batches
A settlement signals the transfer of funds from a provider to a merchant.
Sources
Sources stores the files which initiate a settlement process, namely transaction statements.
Agreements
Agreements set the different rates applicable to your transactions.
Disputes
A dispute occurs when a consumer questions a payment through their issuer.
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
Transaction Statement Conversion
Reconciliation automatically ingests and processes the transaction statements produced by providers, in whichever format they might be presented.
- 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
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
| Path | Method | Description |
|---|---|---|
Sandbox | GET | Filter 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 parameter 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}
| Path | Method | Description |
|---|---|---|
Sandbox | GET | Get 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
| Path | Method | Description |
|---|---|---|
Sandbox | GET | Get 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.
| Path | Method | Description |
|---|---|---|
Sandbox | POST | Add 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: nullfailure_description: nullfile:[]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}
| Path | Method | Description |
|---|---|---|
Sandbox | GET | Get 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}
| Path | Method | Description |
|---|---|---|
Sandbox | GET | Gets 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
Learn how to use Dynamic Routing to optimize your payment operations.