Event Handling

Integrating with Switch

Lifecycle Events are the best way to keep track of Transactions' status on the server-side, and update your databases and systems accordingly.

In case you are having trouble finding a Payment, or need to dive deeper into a specific Transaction, it is possible to search Lifecycle Events and find your ground. You can perform customized searches for one or multiple Elements taking into account specified criteria, and consult technical details.

When analyzing your Payment Operation, every moment counts. Each of the Switch Plataform Elements come with their event sets. This means you can decompose the various Events related to a Transaction. Accessing the moment when it became successful, it failed, or it was settled.

Receive Events

To start receiving Events on your server, add an HTTPS events_url during the Charge creation.

PathMethodDescription
https://api.switchpayments.com/v2/chargesPOSTAdd events_url to Charge creation.
Parameter Descriptions

eventString

Lifecycle Event id.


event_typeString

Lifecycle Event type.

ADD EVENTS_URL
$ curl -vX POST https://api-test.switchpayments.com/v2/charges
-u accountId:privateKey
-d '{
"charge_type": "card_onetime",
"amount": 42,
"currency": "EUR",
"events_url": "https://merchant.com/events"
}

As a Transaction progresses its lifecycle, Switch will send a HTTPS POST request to your events_url with two parameters. The most important Event Type to listen to is the instrument.authorized Event, which happens when the Customer Payment data has been confirmed.

Event Details

GET /v2/events/{id}

To get the Event details, you can use the Event parameter as the {id}in the following request.

PathMethodDescription
https://api.switchpayments.com/v2/events/{id}GETGets the details of an Event element.
Response Parameter

event_idString

Lifecycle Event id.


event_typeString

Lifecycle Event type.


charge_idString

Charge id.


charge_typeString

Payment Method chosen by the Customer.


charge_amountFloat

Charged amount.


charge_currencyString

Processing currency.


charge_metadataString

Parameter sent during the creation of the Charge that identifies the Transaction in your system. It allows you to mark Transactions as successfully completed in your database.


instrument_idString

This is the id of the Transaction authorization provided by your Customer. Acts as a token in recurring Payments.


instrument_failure_descriptionString

If the instrument failed, this field contains the description of the error.


instrument_request_logString

Customer user agent, IP, and country.


instrument_recurringString

Whether the Instrument allows multiple Payments to be created from this Customer authorization.


instrument_captured_on_creationString

Whether a Payment has been created automatically or if it needs to be captured in a separate operation.

REQUEST
$ curl https://api-test.switchpayments.com/v2/events/{id}
-u accountId:privateKey
RESPONSE HTTP 200
{
"id":"f3be209e9ab06d7c2e4145f3be209e9fggab5c",
"type": "instrument.authorized",
"charge": {
"id": "06d7c2e4145f3be209e9ab5c6ed24da8b786f",
"type": "card",
"amount": 42,
"currency": "EUR",
"metadata": {"orderId":"1337"}
},
"instrument": {
"id": "4145f3be2094da8b786fe9ab5c6ed206d7c2e",
"failure_description": null,
"recurring": false,
"captured_on_creation": true
}
}

GET /v2/events/{id}

Result Parameter

idString

Unique event identifier


created_atString

The date when the event was created


object_idString

The unique identifier of the event related object (e.g. refund_id)


result_statusInteger

HTTP status of the event


retries_logArray

A list with all the retries


typeString

The event type (e.g. charge.created, instrument.created)


type_labelString

Pretty name for the event type


chargeJSON Object

The charge object (see Charges)


instrumentJSON Object

The instrument object (see Instruments)


paymentJSON Object

The payment object (see Payments)


refundJSON Object

The refund object (see Refunds)


dismissed_atString

The date when the event was marked as dismissed


settlementJSON Object

The settlement object

REQUEST
$ curl -vX GET https://api-test.switchpayments.com/v2/events/{id} -u accountId:privateKey
RESULT
{
"charge": {
"amount": 500,
"channels": null,
"charge_type": "card_onetime",
"charge_type_label": "Card One-Time",
"confirmed": true,
"created_at": "2018-06-21T14:15:00.428339+00:00",
"currency": "EUR",
"events_url": "https://merchant.com/events",
"expires_at": "2018-06-21T14:20:00.427572+00:00",
"external_ids": null,
"id": "544f96ca01446f04baa549e658212249f6af2d205b2bb2e4",
"instrument_params": {},
"metadata": {
"order_id": 1000
},
"redirect_url": "",
"request_log": {
"country": "PT",
"ip_address": "11.123.1.23",
"library_version": null,
"user_agent": "curl/7.54.0"
},
"updated_at": "2018-06-21T14:15:00.428377+00:00"
},
"created_at": "2018-07-10T12:09:21.244Z",
"id": "453207964a2f9e68a98905be963fb364fca70c465b44a1f1",
"instrument": {
"channel": {
"id": "9c62fb17a095f6dc32f3f36ea289f8a9473afcb95b1ead14",
"label": "card_onetime_example",
"processor": "example"
},
"created_at": "2018-06-21T14:15:05.606250+00:00",
"customer": null,
"external_ids": {
"descriptor": "4942.9439.7602 Switch CC",
"processor": "8a8294496421b8d3016422b2dfcd3750"
},
"failure_description": null,
"id": "95220f9ab78c811f4ffaa9e3c263bea296169b375b2bb2e9",
"params": {
"bank": "JPMORGAN CHASE BANK, N.A.",
"bank_phone": "1-212-270-6000",
"bank_website": "HTTP://WWW.JPMORGANCHASE.COM",
"bin": "411111",
"brand": "VISA",
"country": "UNITED STATES",
"country_isoa2": "US",
"country_isoa3": "USA",
"country_isonumber": "840",
"enable3ds": false,
"expiration_month": 6,
"expiration_year": 2018,
"fingerprint": "a1ccb846ceda84e80b91bee9025437b73784de262233a1bde39490bcb597fb69ef51d9dd3f67a2cb4ee85fb67410460f138f9bb1ee5d7de2f27291e7e895f7a8",
"last_4_digits": "1111",
"name": "John Doe",
"type": "CREDIT"
},
"redirect": null,
"request_log": {
"country": "PT",
"ip_address": "11.123.1.23",
"library_version": null,
"user_agent": "curl/7.54.0"
},
"status": "authorized",
"success": true,
"updated_at": "2018-06-21T14:15:05.606275+00:00"
},
"object_id": "d243e39cdf7f55f6a185235ac8ae8d67d469b29c5b44a1f0",
"payment": {
"amount": 500,
"created_at": "2018-06-21T14:15:05.799179+00:00",
"currency": "EUR",
"description": "",
"external_ids": {
"descriptor": "4942.9439.7602 Switch CC",
"processor": "8a8294496421b8d3016422b2dfcd3750",
"transaction_id": "7b6dfed71377d4065d873342422362121600fcef5b2bb2e9",
"transaction_id_trunc": "7b6dfed71377d4065d873342422362"
},
"failure_description": null,
"id": "6714eff97465d9bb5b323ebbb97185f7dcd43fa65b2bb2e9",
"metadata": {},
"params": null,
"request_log": {
"country": "PT",
"ip_address": "11.123.1.23",
"library_version": null,
"user_agent": "curl/7.54.0"
},
"success": true,
"updated_at": "2018-06-21T14:15:05.799206+00:00"
},
"refund": {
"amount": 1,
"created_at": "2018-07-10T12:09:21.227579+00:00",
"description": "",
"external_ids": {
"descriptor": "0957.6372.2914 Switch CC",
"processor": "8a829449646618a10164841895d1506c",
"transaction_id": "7b6dfed71377d4065d873342422362121600fcef5b2bb2e9",
"transaction_id_trunc": "7b6dfed71377d4065d873342422362"
},
"failure_description": null,
"id": "d243e39cdf7f55f6a185235ac8ae8d67d469b29c5b44a1f0",
"request_log": {
"country": "PT",
"ip_address": "11.123.1.23",
"library_version": null,
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36"
},
"success": true
},
"result_status": 404,
"retries_log": [
{
"created_at": "2018-07-10T12:14:13.870Z",
"result_status": 404
},
{
"created_at": "2018-07-10T12:11:13.351Z",
"result_status": 404
},
{
"created_at": "2018-07-10T12:10:12.888Z",
"result_status": 404
},
{
"created_at": "2018-07-10T12:09:42.539Z",
"result_status": 404
},
{
"created_at": "2018-07-10T12:09:27.211Z",
"result_status": 404
}
],
"type": "refund.success",
"type_label": "Refund Successful",
"dismissed_at": null,
"settlement": null
}

Events have many parameters, corresponding to every detail available on the Transaction at that moment. In the previous example you can find some of the most important ones. On an instrument.authorized Event, the transaction corresponding to the charge.metadata can be marked as successfully completed in the database.

Event Types and Parameters

It is possible to configure independent Webhooks to handle each Event Type or to handle all of them in the same endpoint. The different Lifecycle Events that are communicated to the Merchant Server and can be browsed on the Dashboard or through the Lifecycle API are the following.

EventDescription
Charge createdCharge was initiated by the Merchant or Customer.
Charge confirmedCharge was confirmed by the Merchant.
Instrument authorizedAn Instrument is ready to be used to create a Payment.
Instrument pendingInstrument is awaiting Customer input.
Instrument invalidInstrument was not authorized, or was invalidated by the Merchant.
Instrument riskInstrument was tagged by the Risk management. Every instrument which triggers a Risk rule, be it allow, block, review or enable 3DS, generates this lifecycle event.
Instrument settledInstrument has been settled by the Payment Provider.
Payment errorPayment attempt was unsuccessful.
Payment pendingPayment is pending approval by the Payment Provider.
Payment successPayment was successfully created.
Payment riskPayment was tagged by the Risk management.
Payment settledPayment has been settled by the Payment Provider.
Refund errorRefund attempt was unsuccessful.
Refund pendingRefund is pending approval by the Payment Provider.
Refund successRefund was successfully created.
Refund settledRefund has been settled by the Payment Provider.
Reversal successAuthorization was successfully voided.
Reversal pendingAuthorization Reversal is pending approval by the Payment Provider.
Reversal errorAuthorization was not possible to reverse.
Dispute createdPayment was disputed by the Customer.
Dispute settledDispute has been settled by the Payment Provider.
EVENT PARAMETERS EXAMPLE
{
"id":"f3be209e9ab06d7c2e4145f3be209e9fggab5c",
"type": "instrument.authorized",
"charge": {
"id": "06d7c2e4145f3be209e9ab5c6ed24da8b786f",
"type": "card",
"amount": 42,
"currency": "EUR",
"metadata": {"orderId":"1337"}
},
"instrument": {
"id": "4145f3be2094da8b786fe9ab5c6ed206d7c2e",
"failure_description": null,
"recurring": false,
"captured_on_creation": true
}
}
AvailabilityResult ParameterDescription
event.idLifecycle Event id.
event.typeLifecycle Event type.
charge.idCharge id.
Result Parameters Available on All Eventscharge_typePayment method chosen by the Customer.
charge.amountCharged amount.
charge.currencyProcessing currency.
charge.metadataParameter sent during the creation of the charge, that identifies the Transaction in your system, allowing you to mark it as successfully completed in your database.
instrument.idThis is the id of the transaction authorization provided by your customer. It acts as a token in recurring Payments.
instrument.failure_descriptionIf the instrument failed, this field contains the description of the error.
Result Parameters available on Instrument and Payment Eventsinstrument.request_logCustomer user agent, IP, and country.
instrument.recurringWhether the Instrument allows multiple Payments to be created from this Customer authorization.
instrument.captured_on_creationWhether a Payment has been created automatically or if it needs to be captured in a separate operation.
Result Parameters available on Payment Eventspayment.idPayment id used to create Refunds.