Search Transactions

Handling transactions is not always a linear process. When tapping into specific transactions becomes necessary you can use Search Transactions to find the specifics you are looking for.

1
Single Out Transactions
Looking for a specific transaction? You can use Transactions to find problematic payments and analyze them on a case by case basis.
2
Find Batches of Transactions
Sometimes your analysis depends on a set group of transactions. Understand the parameters of the data you are searching for and use Transactions to access it.

Only use Search Transactions sparsely.

Do not use Search Transactions to access all of your transaction data. Set up Processing to perform operations on charges, instruments, and payments. Search Transactions was built to be used sparsely and not systematically.

GET `/v1/transactions`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions` Production `https://merchant-api.switchpayments.com/v1/transactions`	List existing transactions.

Request Parameter

pageInteger

Page number.

settledString

Filter by settled/unsettled transactions.

searchString

Search values in the following fields: charge_id, instrument_id, payment_id, refund_id, dispute_id, reversal_id, keywords.value.

search_fieldsString

Fields in which to search the values under search. Can be any of the following: charge_id, instrument_id , payment_id, refund_id, dispute_id, reversal_id, keyword, <event_type> (e.g. search_fields=keyword.charge.metadata.order_id).

order_byString

Ordering of the results by field_name. Use "-" to invert the order.

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

Result Parameter

merchant_id (Required)String

The merchant ID the transaction refers to.

charge_id (Required)String

The charge ID the transaction refers to.

instrument_idString

The instrument ID the transaction refers t

payment_idString

The payment ID the transaction refers to.

refund_idString

The refund ID the transaction refers to.

dispute_idString

The dispute ID the transaction refers to.

reversal_idString

The reversal ID the transaction refers to.

amount (Required)Float

The transaction amount.

charge_type (Required)String

Payment method selected by the customer.

is_settled (Required)Boolean

Whether the transaction is settled or not.

requires_settlement (Required)Boolean

Whether the transaction requires settlement or not.

result (Required)String

The transaction result. It can be one of these: created, confirmed, risk, success, error, updated, pending, authorized, invalid, settled.

risk_resultString

The result of the risk check. It can be one of the following: allowed, blocked, review, reviewed.

success (Required)Boolean

Whether the transaction is successful or not.

type (Required)String

Type of the transaction. It can be charge, instrument, payment, refund, dispute, reversal.

externalBoolean

Whether the transaction is from an external source.

created_at (Required)String

The date when the transaction was created.

updated_at (Required)String

The date when the transaction suffered its last update.

settled_atString

The date when the transaction was settled.

keywordsArray

List of searchable fields.

chargeJSON Object

The charge the transaction refers to.

instrumentJSON Object

The instrument the transaction refers to.

paymentJSON Object

The payment the transaction refers to.

refundJSON Object

The refund the transaction refers to.

disputeJSON Object

The dispute the transaction refers to.

reversalJSON Object

The reversal the transaction refers to.

RESULT: HTTP 200
  {
    "pagination": {
      "per_page": 20,
      "min_remaining_pages": 0,
      "page": 1
    },
    "collection": [
      "...",
      {
        "merchant_id": "83216372132918dshdashdasi31232",
        "charge_id": "2b33f091ab6fca5ebef37a31ab5ea1a9a21484b75ceef738",
        "instrument_id": "7de0647e4e11dfb61fa5b0e55155d04b36fd52395ceef745",
        "payment_id": "f462c35f84714a3c5d43e3bf1fa91e2942576fa05ceef768",
        "refund_id": null,
        "dispute_id": null,
        "reversal_id": null,
        "amount": 5.0,
        "charge_type": "card_authorization",
        "is_settled": false,
        "requires_settlement": true,
        "result": "success",
        "risk_result": "success",
        "success": true,
        "type": "payment",
        "external": false,
        "created_at": "2019-05-29T21:19:38.696000+00:00",
        "updated_at": "2019-05-29T21:19:38.697000+00:00",
        "settled_at": null,
        "keywords": [],
        "charge": null,
        "instrument": null,
        "payment": null,
        "refund": null,
        "dispute": null,
        "reversal": null
      },
      "..."
    ]
  }

GET `/v1/transactions/charges/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions/charges/{id}` Production `https://merchant-api.switchpayments.com/v1/transactions/charges/{id}`	Get a specific charge.

Result Parameter

amount (Required)Float

Maximum amount set for the charge.

channelsArray

Channels to be used in the transaction.

charge_id (Required)String

The charge ID that can be used to create an instrument.

charge_type (Required)String

Identifier of the charge type.

confirmed (Required)Boolean

Indicates if the created charge was confirmed by the merchant using their private key.

currency (Required)String

The currency of the charge.

created_at (Required)String

The date when the charge was created.

events_url (Required)String

Endpoint to which notifications of all the lifecycle events related to this charge will be sent.

external_idsJSON Object

Processor IDs of the charge. Currently it is always null.

instrument_paramsJSON Object

The instrument parameters used to create the charge.

failure_codeString

If the charge is not successful, this field includes the error code.

failure_descriptionString

If the charge is not successful, this field includes details about the failure.

metadataJSON Object

Provided charge metadata.

redirect_urlString

Defined redirect url.

request_log (Required)JSON Object

Contains information on the origin of the request: country, ip_address, user_agent and the library_version.

requires_settlement (Required)Boolean

Whether the transaction requires settlement.

updated_at (Required)String

The date when the charge suffered some update.

used_atString

The date when the charge was used to create an instrument.

externalBoolean

Defines whether or not the charge was not processed by Switch.

merchant_id (Required)String

The merchant ID the charge refers to.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/transactions/charges/{id}?merchant_id=accountId -u accountId:APIKey

RESULT: HTTP 200
  {
    "amount": 10,
    "channels": null,
    "charge_id": "89b0c4406a37c531e87010ec30c89d87efdbcc375cf68db9",
    "charge_type": "card_onetime",
    "confirmed": true,
    "currency": "EUR",
    "created_at": "2019-06-04T15:26:49.457000+00:00",
    "events_url": "https://merchant.com/events",
    "external_ids": null,
    "instrument_params": null,
    "failure_code": null,
    "failure_description": null,
    "metadata": null,
    "redirect_url": null,
    "request_log": {
      "country": null,
      "ip_address": "172.22.0.1",
      "user_agent": "PostmanRuntime/7.11.0",
      "library_version": null
    },
    "requires_settlement": false,
    "updated_at": "2019-06-04T15:26:49.457000+00:00",
    "used_at": null,
    "external": false,
    "merchant_id": "83216372132918dshdashdasi31232"
  }

GET `/v1/transactions/instruments/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions/instruments/{id}` Production `https://merchant-api.switchpayments.com/v1/transactions/instruments/{id}`	Get a specific instrument.

Result Parameter

channel (Required)JSON Object

Channel used to create the instrument.

created_at (Required)String

The date when the instrument was created.

external_idsJSON Object

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

failure_codeString

If the instrument was not successful, this field has the error code.

failure_descriptionString

If the instrument was not successful there may be details in this field about the reasons for the error (e.g. from the processor).

fingerprintString

Instrument fingerprint.

instrument_id (Required)String

The instrument id that can be used to create a payment.

redirectJSON Object

Contains information on how to redirect the customer to complete the payment.

parametersJSON Object

Includes the instrument parameters and also the passed parameters in the charge.

referenceJSON Object

Information that should be passed to the customers for them to complete the payment (applicable only for payment methods with a push flow, such as Multibanco).

request_log (Required)JSON Object

Contains information on the origin of the request: country, ip_address, user_agent and the library_version.

requires_settlement (Required)Boolean

Whether the instrument requires settlement.

responseJSON Object

Technical information returned by the processors (e.g. Credit Card ECI code).

status (Required)String

Current status of the instrument. It could be pending, invalid or authorized.

success (Required)Boolean

Flag indicating whether the instrument was successfully created.

updated_at (Required)String

The date when the instrument suffered some update.

externalBoolean

Defines whether or not the instrument was not processed by Switch.

charge_id (Required)String

The ID of the charge used to create this instrument.

merchant_id (Required)String

The merchant ID the instrument refers to.

settlement_idString

The settlement ID.

settled_atString

The date of the settlement.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/transactions/instruments/{id}?merchant_id=accountId -u accountId:APIKey

RESULT: HTTP 200
  {
    "channel": {
      "processor": "payu",
      "id": "5db580ed2bd8a283602928d77fd369645e9e4ef75cb5e858",
      "label": "card_authorization_payu"
    },
    "created_at": "2019-05-29T21:23:12.493000+00:00",
    "external_ids": {
      "provider_transaction_id": "19150AXND18504",
      "authorization_id": "27743631-5c5d-441e-8649-3968f502d34e"
    },
    "failure_code": null,
    "failure_description": null,
    "fingerprint": "4be70fe3c5814ec4fed8171efc0c0f512c234645644d5e3e9eb2be633eee75850f037b6884f109eb39f9eb191710712eb6bc2108d24c55e88fe5db81e4a8ca3a",
    "instrument_id": "318fbb6b4580340f032033b100f0e6cf20e5b9265ceef83a",
    "redirect": null,
    "parameters": {
      "bin": "453144",
      "expiration_month": 12,
      "name": "John Doe",
      "expiration_year": 2019,
      "last_4_digits": "2283"
    },
    "reference": null,
    "request_log": {
      "country": null,
      "ip_address": "172.22.0.1",
      "user_agent": "PostmanRuntime/7.11.0",
      "library_version": null
    },
    "requires_settlement": false,
    "response": null,
    "status": "authorized",
    "success": true,
    "updated_at": "2019-05-29T21:23:24.955000+00:00",
    "external": false,
    "charge_id": "6c3dc38318b7115010554d7660608c6b0830248e5ceef831",
    "merchant_id": "83216372132918dshdashdasi31232",
    "settlement_id": null,
    "settled_at": null
  }

In the case of an instrument with a push flow, the reference will be populated with a structure such as below (the example shows a Multibanco reference example).


  {
    "reference": {
      "fields": [
        {"field": "entity", "value": "815412", "label": "Entity"},
        {"field": "reference", "value": "412523632", "label": "Reference"},
        {"field": "value", "value": "10", "label": "Value"}
      ]
    }
  }

GET `/v1/transactions/payments/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions/payments/{id}` Production `https://merchant-api.switchpayments.com/v1/transactions/payments/{id}`	Get a specific payment.

Result Parameter

amount (Required)Float

The payment amount.

created_at (Required)String

The date when the payment was created.

currency (Required)String

The currency of the payment.

descriptionString

Payment description.

external_idsJSON Object

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

failure_codeString

If the payment is not successful, this field has the error code.

failure_descriptionString

If the payment is not successful, this field has details about the failure.

metadataJSON Object

Metadata specified in the request.

paramsJSON Object

The payment parameters.

payment_id (Required)String

Unique identifier of the payment.

refundable (Required)Boolean

Defines whether or not the payment allows refunds.

requires_settlement (Required)Boolean

Whether the payment requires settlement.

request_log (Required)JSON Object

Contains information on the origin of the request: country, ip_address, user_agent and the library_version.

responseJSON Object

Technical information returned by the processor (e.g. Credit Card ECI code).

statusString

Current status of the payment. It could be pending, error or success.

success (Required)Boolean

Flag indicating whether the payment is successful.

settled_atString

The date of the settlement.

updated_at (Required)String

Last date when the payment suffered an update.

externalBoolean

Defines whether or not the payment was not processed by Switch.

charge_id (Required)String

The ID of the charge.

instrument_id (Required)String

The instrument ID used to create the payment.

merchant_id (Required)String

The merchant ID the payment refers to.

settlement_idString

The settlement ID.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/transactions/payments/{id}?merchant_id=accountId -u accountId:APIKey

RESULT: HTTP 200
  {
    "amount": 5,
    "created_at": "2019-05-30T14:43:47.524000+00:00",
    "currency": "EUR",
    "description": "",
    "external_ids": {
      "capture_id": "d7fbd93f-8d07-4a78-847d-2e9beb496cdb",
      "provider_transaction_id": "19150RrrA12646"
    },
    "failure_code": null,
    "failure_description": null,
    "metadata": null,
    "params": {},
    "payment_id": "4bff9a7afdf7017df1e6386a403e5cd6adcc1a705cefec1b",
    "refundable": true,
    "requires_settlement": true,
    "request_log": {
      "country": null,
      "ip_address": "172.22.0.1",
      "user_agent": "PostmanRuntime/7.11.0",
      "library_version": null
    },
    "response": null,
    "status": "success",
    "success": true,
    "settled_at": null,
    "updated_at": "2019-05-30T14:43:47.525000+00:00",
    "external": false,
    "charge_id": "022156f0ee356507d9beeb7768b2ef8b573cf7135cefeb4a",
    "instrument_id": "0317b1b7150bde7d50f0f95f540ee7b03e0253c45cefeb80",
    "merchant_id": "83216372132918dshdashdasi31232",
    "settlement_id": null
  }

GET `/v1/transactions/refunds/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions/refunds/{id}` Production `https://merchant-api.switchpayments.com/v1/transactions/refunds/{id}`	Get a specific refund.

Result Parameter

amount (Required)Float

The refund amount.

paramsJSON Object

The refund parameters.

created_at (Required)String

The date when the refund was created.

descriptionString

Refund description.

external_idsJSON Object

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

failure_codeString

If the refund is not successful, this field has the error code.

failure_descriptionString

If the refund is not successful, this field has details about the failure.

payment_id (Required)String

The payment ID the refund refers to.

refund_id (Required)String

The refund ID.

request_log (Required)JSON Object

Contains information on the origin of the request: country, ip_address, user_agent and the library_version.

requires_settlement (Required)Boolean

Whether the refund requires settlement.

settled_atString

The date of the settlement.

statusString

Current status of the refund. It could be pending, error or success.

success (Required)Boolean

Flag indicating whether the refund is successful.

sourceJSON Object

The source of the refund.

externalBoolean

Defines whether or not the refund was not processed by Switch.

updated_at (Required)String

Last date when the refund was last update.

merchant_id (Required)String

The merchant id the refund refers to.

charge_id (Required)String

The charge ID the refund refers to.

instrument_id (Required)String

The instrument ID the refund refers to.

settlement_idString

The settlement ID.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/transactions/refunds/{id}?merchant_id=accountId -u accountId:APIKey

RESULT: HTTP 200
  {
    "amount": 0.1,
    "params": null,
    "created_at": "2019-05-20T11:59:23.427000+00:00",
    "description": "description",
    "external_ids": {
      "transaction_id": "80fe1f5ce4b1c9f6582df5efe6b0f5895cd2745b5ce294ad"
    },
    "failure_code": null,
    "failure_description": null,
    "payment_id": "b432095219a6bd2ecf63ea609be4e5fe7079bbcc5ce294ad",
    "refund_id": "5a1ec7423d6ddb829959b276d9802b1025ece73e5ce2969a",
    "request_log": {
      "country": null,
      "ip_address": "172.22.0.1",
      "user_agent": "PostmanRuntime/7.11.0",
      "library_version": null
    },
    "requires_settlement": true,
    "settled_at": null,
    "status": "success",
    "success": true,
    "source": null,
    "external": false,
    "updated_at": "2019-05-20T11:59:23.427000+00:00",
    "merchant_id": "83216372132918dshdashdasi31232",
    "charge_id": "e387c7a3c0d4b2f0c6d29a46daa73fcb704fcdc05ce29480",
    "instrument_id": "33357e630b7968d8a7f30e75711efed256592c8a5ce29488",
    "settlement_id": null
  }

GET `/v1/transactions/reversals/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions/reversals/{id}` Production `https://merchant-api.switchpayments.com/v1/transactions/reversals/{id}`	Get a specific reversal.

Result Parameter

reversal_id (Required)String

The reversal ID.

external_idsJSON Object

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

object_id (Required)String

The ID of the object the reversal refers to (e.g. instrument_id).

object_type (Required)String

The type of the object the reversal refers to (e.g. instrument).

amount (Required)Float

The reversal amount.

initiated_by (Required)String

Who initiated the reversal (customer, merchant, processor).

statusString

Current status of the reversal. It could be pending, error or success.

success (Required)Boolean

Flag indicating whether the reversal is successful.

failure_codeString

If the reversal is not successful, this field has the error code.

failure_descriptionString

If the reversal is not successful, this field has details about the failure.

requires_settlement (Required)Boolean

Whether the reversal requires settlement.

request_log (Required)JSON Object

Contains information on the origin of the request: country, ip_address, user_agent and the library_version.

external (Required)Boolean

Defines whether or not the reversal was not processed by Switch.

created_at (Required)String

The date when the reversal was created.

updated_at (Required)String

Last date when the reversal suffered an update.

charge_id (Required)String

The charge ID the reversal refers to.

instrument_idString

The instrument ID the reversal refers to.

payment_idString

The payment ID the reversal refers to.

refund_idString

The refund ID the reversal refers to.

merchant_id (Required)String

The merchant ID the reversal refers to.

settlement_idString

The settlement ID.

settled_atString

The date of the settlement.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/transactions/reversals/{id}?merchant_id=accountId -u accountId:APIKey

RESULT: HTTP 200
  {
    "reversal_id": "b4af494e317c8629a0dd8bc3cd6bfd3ac9a2c6b65c9a1742",
    "external_ids": {
      "authorization_id": "82925393395140931",
      "reversal_id": "82925393395140931",
      "processor": "82925393396613688"
    },
    "object_id": "9a04229fc073cd7412176ce62ae908a37d4e24105c9a1730",
    "object_type": "instrument",
    "amount": 300.3,
    "initiated_by": "merchant",
    "status": "success",
    "success": true,
    "failure_code": null,
    "failure_description": null,
    "requires_settlement": true,
    "request_log": {
      "country": null,
      "ip_address": "172.22.0.1",
      "user_agent": "PostmanRuntime/7.6.1",
      "library_version": null
    },
    "external": false,
    "created_at": "2019-03-26T12:12:51.384000",
    "updated_at": "2019-05-20T11:59:23.427000+00:00",
    "charge_id": "e387c7a3c0d4b2f0c6d29a46daa73fcb704fcdc05ce29480",
    "instrument_id": "33357e630b7968d8a7f30e75711efed256592c8a5ce29488",
    "payment_id": "33357e630b7968d8a7f30e75711efed256592c8a5ce29488",
    "refund_id": "33357e630b7968d8a7f30e75711efed256592c8a5ce29488",
    "merchant_id": "83216372132918dshdashdasi31232",
    "settlement_id": null,
    "settled_at": null
  }

GET `/v1/transactions/disputes/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/transactions/disputes/{id}` Production `https://merchant-api.switchpayments.com/v1/transactions/disputes/{id}`	Get a specific dispute.

Result Parameter

dispute_id (Required)String

The dispute ID.

payment_id (Required)String

The payment ID the dispute refers to.

processor (Required)String

The processor the dispute refers to.

sourceJSON Object

The source of the dispute.

type (Required)String

Type of the dispute. It can be arbitration, chargeback, chargeback_reversal, pre_arbitration, retrieval, or 2nd_chargeback.

amount (Required)Float

The dispute amount.

currency (Required)String

The currency of the dispute.

descriptionString

Dispute description.

fx_rateFloat

Forex rate.

metadataJSON Object

Arbitrary information included in the dispute source.

external_idsJSON Object

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

requires_settlement (Required)Boolean

Whether the dispute requires settlement.

created_at (Required)String

The date when the dispute was created.

disputed_at (Required)String

The date when the dispute was initiated.

updated_at (Required)String

Last date when the dispute was last updated.

merchant_id (Required)String

The merchant ID the dispute refers to.

charge_id (Required)String

The charge ID the dispute refers to.

instrument_id (Required)String

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

RESULT: 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
  }

Search Transactions

Single Out Transactions

Find Batches of Transactions

Only use Search Transactions sparsely.

GET /v1/transactions

Request Parameter

Result Parameter

GET /v1/transactions/charges/{id}

Result Parameter

GET /v1/transactions/instruments/{id}

Result Parameter

GET /v1/transactions/payments/{id}

Result Parameter

GET /v1/transactions/refunds/{id}

Result Parameter

GET /v1/transactions/reversals/{id}

Result Parameter

GET /v1/transactions/disputes/{id}

Result Parameter

GET `/v1/transactions`

GET `/v1/transactions/charges/{id}`

GET `/v1/transactions/instruments/{id}`

GET `/v1/transactions/payments/{id}`

GET `/v1/transactions/refunds/{id}`

GET `/v1/transactions/reversals/{id}`

GET `/v1/transactions/disputes/{id}`