Webhooks
Webhooks can be used as alerts to keep your systems and partner applications in sync with actions in Skipify
Overview
Skipify can send outbound webhooks to any publicly accessible server. When an event is triggered (e.g. a PayLink URL has become inactive), Skipify will send a webhook notification to the endpoint(s) you specify in your configuration and await a response from your server(s) confirming receipt. The payload from the webhook will contain the unique orderId or paylinkId so that you can lookup PayLink and update your records as necessary.
Implementation Tip
If you would like to generate a test server URL, you can do this using RequestBin or Mockbin. We do not recommend using this for production traffic
Merchant Portal Setup
In order to configure webhooks within Skipify, you will need to specify the following information to your friendly Skipify implementation manager:
- The endpoint to which you'd like the webhook sent
- The event(s) to which you would like to subscribe
- The email to notify when a webhook has not been sent successfully
- A description of the purpose of this integration
- [Optional] An encryption secret which you can specify to trust that the webhook came from Skipify
- [Optional] custom header key/value pair (i.e. - x-api-key) can be set to trust that the webhook came from Skipify
Event Types
Skipify can send the following notifications to your systems:
- ORDER_PAYMENT_SUCCEEDED - sent when a customer has a successful authorization on an order (applicable to any use case)
- ORDER_PAYMENT_FAILED - sent when a customer has a failed payment authorization (applicable to any use case)
- PAYMENT_REQUEST_EXPIRED - sent when a customer clicks on a PayLink payment request that has expired where the customer can no longer make a purchase
Implementing Webhooks
After you set up your webhook endpoint, reach out to your favorite implementation manager! They'll be happy to check it over and confirm that it's receiving messages as expected.
Webhook Request and Response
Webhook event requests are sent via POST requests to the URL(s) you specify. When a webhook event is triggered, you will receive a request with the event details.
Below are example request bodies for ORDER_PAYMENT_SUCCEEDED, ORDER_PAYMENT_FAILED, and PAYMENT_REQUEST_EXPIRED events:
// Sample for ORDER_PAYMENT_SUCCEEDED:
{
"eventName": "ORDER_PAYMENT_SUCCEEDED", //The Event that triggered the webhook
"merchantId": "c1brc8b60-6dd4-4136-88e1-c9e5b670f1ca0",//The MerchantId that the event was triggered for
"payload": {//Specific info for this event
"pspTransactionId": "35472160", //The TransactionId from the PSP for this event
"merchantInvoiceId": "MYumberABC123 20240130",//The merchantInvoiceId for this event (merchantReference field from SDK)
"paylinkId": "70ca1c7c-f483-42a5-9147-99ea858f8568",//The Skipify paylinkId for this event
"completedAt": "2024-01-31T18:24:00.000Z",//The Time in UTC when the payment succeeded for this event
"pspRawResponse": "<CreditSaleResponse.....",//Raw JSON/XML payload returned from PSP for you to parse as needed
"transactionAmount":112,//Amount authorized for this transaction
"charges": [ // Charges (fees) inclded on the order. Note: these amounts are already included in orderAmount.
//If no Charges(fees) were applied on an order, this will be formatted as "charges": null,
{ "type": "SURCHARGE_FEE", "amount": 10 },
{ "type": "GENERAL_FEE", "amount": 12 }
],
"skipifyTransactionId": "27c3ac7c-db62-4661-9ccc-287573e50568",//Skipify's internal id for this transaction
"isPartialAuthorization": false,//Indicates if the amount authorized for this transaction was for only part of the order amount
"cardBrand": "amex",//Brand of the card used for payment. Possible values: amex, mastercard, visa, discover, unknown(if not recognized by PSPs)
"cardLastFour": "0005",//Last four digits of card used for payment
"isSplitPayment": false,
"orderId": "65b8259b0cd7e1fc5eaf92ba",//The Skipify unique orderId for this event
"orderAmount": 112,//The amount of the order
},
"manualRetryId": null,//Reserved for future use
"merchantSet": {//Information about the merchant this event was for
"merchantId": "c1brc8b60-6dd4-4136-88e1-c9e5b670f1ca0",
"merchantName": "THE BEST MERCHANT",//The Merchant's Business name in the Skipify system for this event
"merchantIndustry": "RESTAURANT",//The Industry set on this merchant's profile in the Skipify system
"topLevelMerchantId": null,//Reserved for future use
"parentMerchant": null,//Parent Merchant if applicable
"directLineage": ["c1df84e3-3a1b-489a-9758-e071ad61e8ea","45961295-3540-43cd-82d1-0f09d0aec192"]//lists all merchants associate with hierarchy of this merchant
},
"secret": "abd12345"
}
// Sample for ORDER_PAYMENT_FAILED:
{
"eventName": "ORDER_PAYMENT_FAILED", //The Event that triggered the webhook
"merchantId": "c1brc8b60-6dd4-4136-88e1-c9e5b670f1ca0",//The MerchantId that the event was triggered for
"payload": {//Specific info for this event
"pspTransactionId": "35472160", //The TransactiondId from the PSP for this event
"merchantInvoiceId": "MYMerchantOrderNumberABC123 20240130",//The merchantInvoiceId for this event
"paylinkId": "70ca1c7c-f483-42a5-9147-99ea858f8568",//The Skipify paylinkId for this event
"pspRawResponse": "<CreditSaleResponse.....",//Raw JSON/XML payload returned from PSP for you to parse as needed
"transactionAmount":112,//Amount attempted to be authorized
"charges": [ // Charges (fees) inclded on the order. Note: these amounts are already included in orderAmount.
//If no Charges(fees) were applied on an order, this will be formatted as "charges": null,
{ "type": "SURCHARGE_FEE", "amount": 10 },
{ "type": "GENERAL_FEE", "amount": 12 }
],
"skipifyTransactionId": "27c3ac7c-db62-4661-9ccc-287573e50568",//Skipify's internal id for this transaction
"orderId": "65b8259b0cd7e1fc5eaf92ba",//The Skipify unique orderId for this event
"cardBrand": "amex",//Brand of the card used for payment. Possible values: amex, mastercard, visa, discover, unknown(if not recognized by PSPs)
"cardLastFour": "0005",//Last four digits of card used for payment
"isSplitPayment": false,
"orderAmount": 112,//The amount of the order
},
"manualRetryId": null,//Reserved for future use
"merchantSet": {//Information about the merchant this event was for
"merchantId": "c1brc8b60-6dd4-4136-88e1-c9e5b670f1ca0",
"merchantName": "THE BEST MERCHANT",//The Merchant's Business name in the Skipify system for this event
"merchantIndustry": "RESTAURANT",//The Industry set on this merchant's profile in the Skipify system
"topLevelMerchantId": null,//Reserved for future use
"parentMerchant": null,//Parent Merchant if applicable
"directLineage": ["c1df84e3-3a1b-489a-9758-e071ad61e8ea","45961295-3540-43cd-82d1-0f09d0aec192"]//lists all merchants associate with hierarchy of this merchant
},
"secret": "abd12345"
}
// Sample for PAYMENT_REQUEST_EXPIRED:
{
"eventName": "PAYMENT_REQUEST_EXPIRED",//The Event that triggered the webhook
"merchantId": "c1brc8b60-6dd4-4136-88e1-c9e5b670f1ca0",//The MerchantId that the event was triggered for
"payload": {//Specific info for this event
"paylinkId": "70ca1c7c-f483-42a5-9147-99ea858f8568",//The Skipify paylinkId for this event
"merchantInvoiceId": "MYMerchantOrderNumberABC123 20240129 150335",//The merchantInvoiceId for this event
"total": 51,//The Total Amount of the expired Paylink
"expiration": "2024-01-31T18:24:00.000Z"//The Time in UTC that the Paylink expired
},
"manualRetryId": null,//Reserved for future use
"merchantSet": {//Information about the merchant this event was for
"merchantId": "c1brc8b60-6dd4-4136-88e1-c9e5b670f1ca0",
"merchantName": "THE BEST MERCHANT",//The Merchant's Business name in the Skipify system for this event
"merchantIndustry": "RESTAURANT",//The Industry set on this merchant's profile in the Skipify system
"topLevelMerchantId": null,//Reserved for future use
"parentMerchant": "b2sd60-6dd4-4136-88e1-c9e5b670f1ca0",//Parent Merchant if applicable
"directLineage": ["c1df84e3-3a1b-489a-9758-e071ad61e8ea","45961295-3540-43cd-82d1-0f09d0aec192"]//lists all merchants associate with hierarchy of this merchant
},
"secret": "abd12345"
}
Skipify only considers a notification delivered if it receives a timely response with a successful status code. The following conditions must be met:
- Your endpoint must be reachable at port 443 (HTTPS) (Skipify does not support other ports at this time)
- Your endpoint must respond within 5 seconds
- Your endpoint must respond with a 2XX status code (200, 201, 204, etc). Skipify does not follow redirects or consider them successful responses.
Failures and Retries
Each failed webhook attempt will be retried 3 times over the course of 12 hours. Administrators on the Skipify merchant account will receive an email notification each time a webhook fails to send (at the end of the 12 hour retry window).
Updated 25 days ago