Transactions Service

Transactions present in the Switch platform.

Transactions

The available operations for the transactions resource are:

GET /v1/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 in "search" (comma separated). Can be any of [charge_id, instrument_id, payment_id, refund_id, dispute_id, reversal_id, keyword, <event_type>]. Example: "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 to


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


requires_settlement (Required)Boolean

Whether the transaction requires settlement


result (Required)String

The transaction result (can be one of: [created, confirmed, risk, success, error, updated, pending, authorized, invalid, settled])


risk_resultString

The result of the risk checks (can be one of: [allowed, blocked, review, reviewed])


success (Required)Boolean

Whether the transaction is successful


type (Required)String

Type of the transaction (can be one of: [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 some 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
},
"..."
]
}

Charges

The available operations for the charges resource are:

GET /v1/transactions/charges/{id}

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 is always null


instrument_paramsJSON Object

The instrument parameters used to create the charge


failure_codeString

If the charge is not successful, this field has the error code


failure_descriptionString

If the charge is not successful, this field has 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: The 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"
}

Instruments

The available operations for the instruments resource are:

GET /v1/transactions/instruments/{id}

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: The 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"}
]
}
}

Payments

The available operations for the payments resource are:

GET /v1/transactions/payments/{id}

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: The country, ip_address, user_agent and the library_version


responseJSON Object

Technical information returned by the processors (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
}

Refunds

The available operations for the refunds resource are:

GET /v1/transactions/refunds/{id}

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: The 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 suffered an 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
}

Reversals

The available operations for the reversals resource are:

GET /v1/transactions/reversals/{id}

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

Disputes

The available operations for the disputes resource are:

GET /v1/transactions/disputes/{id}

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 (can be one of: [arbitration, chargeback, chargeback_reversal, pre_arbitration, retrieval, 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 suffered an update


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
}