Lifecycle Events are the best way to keep track of transactions' statuses 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.
| Path | Method | Description |
|---|---|---|
| https://api.switchpayments.com/v2/charges | POST | Add 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.
| Path | Method | Description |
|---|---|---|
| https://api.switchpayments.com/v2/events/{id} | GET | Gets 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.
| Event | Description |
|---|---|
| Charge created | Charge was initiated by the Merchant or Customer. |
| Charge confirmed | Charge was confirmed by the Merchant. |
| Charge error | Object with the unsuccessful response returned by chargesUrl. |
| Instrument authorized | An Instrument is ready to be used to create a Payment. |
| Instrument pending | Instrument is awaiting Customer input. |
| Instrument invalid | Instrument was not authorized, or was invalidated by the Merchant. |
| Instrument risk | Instrument 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 settled | Instrument has been settled by the Payment Provider. |
| Payment error | Payment attempt was unsuccessful. |
| Payment pending | Payment is pending approval by the Payment Provider. |
| Payment success | Payment was successfully created. |
| Payment settled | Payment has been settled by the Payment Provider. |
| Refund error | Refund attempt was unsuccessful. |
| Refund pending | Refund is pending approval by the Payment Provider. |
| Refund success | Refund was successfully created. |
| Refund settled | Refund has been settled by the Payment Provider. |
| Reversal success | Authorization was successfully voided. |
| Reversal pending | Authorization Reversal is pending approval by the Payment Provider. |
| Reversal error | Authorization was not possible to reverse. |
| Dispute created | Payment was disputed by the Customer. |
| Dispute settled | Dispute 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}}
| Availability | Result Parameter | Description |
|---|---|---|
| event.id | Lifecycle Event id. | |
| event.type | Lifecycle Event type. | |
| charge.id | Charge id. | |
| Result Parameters Available on All Events | charge_type | Payment method chosen by the Customer. |
| charge.amount | Charged amount. | |
| charge.currency | Processing currency. | |
| charge.metadata | Parameter 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.id | This is the id of the transaction authorization provided by your customer. It acts as a token in recurring Payments. | |
| instrument.failure_description | If the instrument failed, this field contains the description of the error. | |
| Result Parameters available on Instrument and Payment Events | instrument.request_log | Customer user agent, IP, and country. |
| instrument.recurring | Whether the Instrument allows multiple Payments to be created from this Customer authorization. | |
| instrument.captured_on_creation | Whether a Payment has been created automatically or if it needs to be captured in a separate operation. | |
| Result Parameters available on Payment Events | payment.id | Payment id used to create Refunds. |