Skip to main content

Webhooks

The Webhooks section allows you to configure webhooks, which are notifications sent automatically by Splitit to a URL of your choice when specific events occur.

Each installment plan event has a corresponding webhook event provided by Splitit. When you subscribe to an event, an asynchronous call is made to your predefined endpoint from the Splitit servers. This call will be fired to your endpoint every hour, for 24 hours, until you reply with HTTP code 200.

  • Viewing and Searching Webhooks: Use the Search Bar in the Hub to find specific webhooks by entering relevant keywords

  • Managing Webhooks: Use the toggle switches next to each webhook to turn it on or off

  • Updating Webhooks: If a webhook URL has changed, enter the new URL under the appropriate webhook and click Update

Webhook NameEvent in Response ObjectDescription
Bin data changedBinDataChangedshopper's bin data changed
Charge succeeded/charge failedChargeSucceeded/ChargeFailedscheduled monthly charge succeeded/failed
Customer credit card update succeededCustomerCreditCardUpdateSucceededcard update succeeded
Customer credit card update failedCustomerCreditCardUpdateFailedcard update failed
Customer details update succeeded/customer details update failedCustomerDetailsUpdateSucceeded, CustomerDetailsUpdateFailedcustomer details update succeeded/failed
Dispute openedDisputeOpenedsent upon dispute received notification from gateway
Dispute lostDisputeLostdispute lost notification
Dispute wonDisputeWondispute won notification
Dispute closedDisputeCloseddispute closed notification
Dispute pendingDisputePendingdispute pending notification
Dispute RFI receivedDisputeRFIReceiveddispute request for information received
Full capture failed/full capture succeededFullCaptureFailed, FullCaptureSucceededfull installment plan capture succeeded/failed
Merchant financedMerchantFinancedmoney is transferred to the merchant in a funded model
Plan approved failed/plan approved succeededPlanApprovedSucceeded, PlanApprovedFailedplan approval by shopper succeeded/failed
Plan cancelled succeeded/plan cancelled failedPlanCancelledSucceeded, PlanCancelledFailedplan cancellation succeeded/failed
Plan clearedPlanClearedplan outstanding amount = 0
Plan created succeeded/plan created failedPlanCreatedSucceeded/PlanCreatedFailedplan creation (and authorization) succeeded or failed
Plan delayedPlanDelayedplan entered delay for whatever reason
Plan deletedPlanDeletedplan successfully deleted
Plan recoveredPlanRecoveredplan recovered after delay
Plan secured auth reminder should be sentPlanSecuredAuthReminderShouldBeSentplan secured, send auth reminder
Plan updated succeeded/plan updated failedPlanUpdatedSucceeded, PlanUpdatedFailedplan update succeeded/failed
Refund completedRefundCompleteda successful refund was processed
Retry succeededRetrySucceededsuccessful retry
Retry failedRetryFailedfailed retry
Secure auth succeededSecureAuthSucceededsuccessful secure auth
Secure auth failedSecureAuthFailedfailed secure auth
Start installments succeeded/start installments failedStartInstallmentsSucceeded, StartInstallmentsFailedfirst installment succeeded/failed

Additional Webhooks Information​

Signature Validation for Added Security​

All outgoing webhooks have an idempotency key in their headers, "X-Splitit-IdempotencyKey," along with a signature, "X-Splitit-Signature." The signature is calculated by concatenating the idempotency key, a semicolon and the body of the webhook in the form KEY;BODY.

You can validate the signature with Python:

Signature Validation with Python
   import base64
   from cryptography.hazmat.primitives import hashes
   from cryptography.hazmat.primitives.asymmetric import padding
   from cryptography import x509

   # --- Splitit public certificate (PEM) --- (find here for prod: https://webhooks-v2.splitit.com/api/v1/auth/public-keys and find here for sandbox: https://webhooks-v2.sandbox.splitit.com/api/v1/auth/public-keys)
   CERT_PEM = """-----BEGIN CERTIFICATE-----
   MIIDBTCCAb2gAwIBAgIJAPSm5WApGIbtMD0GCSqGSIb3DQEBCjAwoA0wCwYJYIZI
   AWUDBAICoRowGAYJKoZIhvcNAQEIMAsGCWCGSAFlAwQCAqIDAgEwMBIxEDAOBgNV
   BAMTB1NwbGl0aXQwHhcNMjUwNTE0MTUwMTQ4WhcNMjYwNTE0MTUwMTQ4WjASMRAw
   DgYDVQQDEwdTcGxpdGl0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
   3x4hWL5PufM6BMSOStqwexC8Bx4AJnn9mQxbDWKw1qTNi6qJR2TDUiBxRlX9z8Ws
   X/zWNK4DPO+9wC6ZTYW2uUjbNHKSCYLgA8Nc7Zg4Zg165MtrBhZwd5Ot0vkI1DLI
   wO++RzBLyb7QeISK2NRz4I9c17U0Weqk5n4KVv8Qecmhyeeoe8U1tb4NR/x256Mf
   JMOHvKMDy9I0p8HjIYuFXzQoQCoEjVuyk78amyAz+mrKO1RUzZlZCRx0mbQK9Sir
   9X2Tpe6A4XH/r2K1JHDgTHM7+f4ZPN4lO0PQQGFvwTify7DVHxRnRaEJ473vdAXU
   SBG8CFw7Mm+qwtwShIl+GQIDAQABMD0GCSqGSIb3DQEBCjAwoA0wCwYJYIZIAWUD
   BAICoRowGAYJKoZIhvcNAQEIMAsGCWCGSAFlAwQCAqIDAgEwA4IBAQBLXw+MsR0V
   PBaA9O/3DT8qAM7CDNuF59RRBd6XOWanIEwqz14Dxp2qodn1cjr0iUKvLe9g2WJH
   lEsTYbfxiL57KAGeue9UrZtjoPfOaOYtGu/x55DC0wUSDORl03vOZUiOE0dns0HA
   m5GMvM9jJisn71B+wjqHcn2IH3B3PPKNx6iZC7/eJgIt7xstX1k0DIP6/lSLGSaT
   rzCLmliRqjCV+WGEl/m4eNXsA0bbdYsFGj2qcqWqOWZWJTykwFnoDrpcyit0OMag
   2DPpTFirR7NVpp45IP0E6X6YHvOLUUcAd6tztFlWt7dc1yuXStbmlTMM/qQhPhbe
   0ymn5Fao4bfX
   -----END CERTIFICATE-----"""

   # --- Example inputs ---
   IDEMPOTENCY_KEY = "6b3ef735844f4fac9c53b131b770af9a6388575177543093588e459a8139d64e6cbf985fd3b6462d2a"
   BODY = (
   '{"InstallmentPlanEventType":"PlanCreatedSucceeded","InstallmentPlan":{"InstallmentPlanNumber":"0XJS76G9N73GQU49E3E0","InstallmentPlanStatus":{"Id":3,"Code":"InProgress","Description":"In Progress"},"Amount":{"Value":1593.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"OutstandingAmount":{"Value":1593.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"NumberOfInstallments":2,"NumberOfProcessedInstallments":0,"OriginalAmount":{"Value":1593.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"RefundAmount":{"Value":0.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"Consumer":{"Id":"525c332c-4742-45a5-bf54-2db47935c548","UniqueId":"525c332c-4742-45a5-bf54-2db47935c548","UserName":"aASAS@sada.com","FullName":"adasd dads","Email":"aASAS@sada.com","PhoneNumber":"8457656","CultureName":"pt-PT","RoleName":null,"IsLocked":false,"IsDataRestricted":false,"IsDataPrivateRestricted":false},"ActiveCard":{"CardId":"WdCexD3eTJelpBgvOLomwk95DDYlJfJO9EJ","CardNumber":"************1111","CardExpMonth":null,"CardExpYear":null,"CardBrand":{"Id":2,"Code":"Visa","Description":"VISA"},"CardType":{"Id":1,"Code":"Credit","Description":"CREDIT"},"Bin":"411111","CardHolderFullName":"a**** d***","CardCvv":"[Filtered]","Address":{"AddressLine":"qweqweqw","AddressLine2":null,"City":"portimao","Country":"PT","State":null,"Zip":"8500-112","FullAddressLine":"qweqweqw,portimao,PT"},"Token":null,"FpanLast4Digits":null},"FraudCheck":{"FraudCheckResult":{"Id":3,"Code":"NotReviewed","Description":"Not Reviewed"}},"Terminal":{"NewId":"SPL_000054742","ApiKey":"0859bab9-3ce9-4568-9353-b623fb53280f","Id":-1,"Code":"SPL_000054742","Description":"BlueSnapDirect"},"Merchant":{"Name":"Emma Sleep Test","NewId":"SPL_000054742","MerchantFacingName":"Emma Sleep Test","Id":-1,"Code":"SPL_000054742","Description":"Emma Sleep Test"},"RefOrderNumber":"0015-VBW59J","PurchaseMethod":{"Id":3,"Code":"ECommerce","Description":"E-Commerce"},"Strategy":{"Id":1,"Code":"SecuredPlan","Description":"Secured"},"DelayResolution":null,"ExtendedParams":{"userAgent":"node","ipAdd'+'ress":"..f'+'fff.1'+'27.'+'0.0.6"},"IsFullCaptured":false,"IsChargedBack":false,"ArePaymentsOnHold":false,"ScpFundingPercent":0.0,"FundingStatus":"NotDetermined","TestMode":"None","CreationDateTime":"2025-06-17T10:09:34.867","LifeTimeUrlExpirationTime":"2025-06-24T10:09:34.867","Installments":[{"InstallmentId":"14688634","InstallmentNumber":1,"Amount":{"Value":796.50,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"OriginalAmount":{"Value":796.50,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"RefundAmount":{"Value":0.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"ProcessDateTime":"2025-06-17T10:09:45.167","IsRefund":false,"RequiredCredit":{"Value":1593.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"CreatedDateTime":"2025-06-17T10:09:34.997","Status":{"Id":2,"Code":"WaitingForProcessDate","Description":"Waiting for process date"},"TransactionResults":[{"GatewayTransactionId":"1113035925","SplititTransactionId":0,"SplititGatewayTransactionId":"7736aac1-b5ee-4fca-94f9-0ad17902d41f","GatewayResultCode":"AUTH_ONLY","GatewayResultMessage":"AUTH_ONLY","OperationType":{"Id":1,"Code":"Authorize","Description":"Approved"},"GatewayResult":true,"GatewayTransactionDate":"2025-06-17T10:09:34.833Z","IsChargeback":false,"AVSResult":{"Code":null,"Description":null},"CVCResult":{"Code":null,"Description":null}}],"CardDetails":{"CardId":"WdCexD3eTJelpBgvOLomwk95DDYlJfJO9EJ","CardNumber":"************1111","CardExpMonth":null,"CardExpYear":null,"CardBrand":{"Id":2,"Code":"Visa","Description":"VISA"},"CardType":{"Id":1,"Code":"Credit","Description":"CREDIT"},"Bin":"411111","CardHolderFullName":"a**** d***","CardCvv":"[Filtered]","Address":{"AddressLine":"qweqweqw","AddressLine2":null,"City":"portimao","Country":"PT","State":null,"Zip":"8500-112","FullAddressLine":"qweqweqw,portimao,PT"},"Token":null,"FpanLast4Digits":null},"Result":true,"PaymentMethod":"CreditCard","ConsumerFeeAmount":0.0,"OriginalConsumerFeeAmount":{"Value":0.0,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}}},{"InstallmentId":"14688635","InstallmentNumber":2,"Amount":{"Value":796.50,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"OriginalAmount":{"Value":796.50,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"RefundAmount":{"Value":0.00,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"ProcessDateTime":"2025-07-17T10:09:45.167","IsRefund":false,"RequiredCredit":{"Value":796.50,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"CreatedDateTime":"2025-06-17T10:09:34.997","Status":{"Id":2,"Code":"WaitingForProcessDate","Description":"Waiting for process date"},"TransactionResults":[],"CardDetails":{"CardId":"WdCexD3eTJelpBgvOLomwk95DDYlJfJO9EJ","CardNumber":"************1111","CardExpMonth":null,"CardExpYear":null,"CardBrand":{"Id":2,"Code":"Visa","Description":"VISA"},"CardType":{"Id":1,"Code":"Credit","Description":"CREDIT"},"Bin":"411111","CardHolderFullName":"a**** d***","CardCvv":"[Filtered]","Address":{"AddressLine":"qweqweqw","AddressLine2":null,"City":"portimao","Country":"PT","State":null,"Zip":"8500-112","FullAddressLine":"qweqweqw,portimao,PT"},"Token":null,"FpanLast4Digits":null},"Result":null,"PaymentMethod":"CreditCard","ConsumerFeeAmount":0.0,"OriginalConsumerFeeAmount":{"Value":0.0,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}}}],"SecureAuthorizations":[{"ProcessingDate":"2025-06-17T10:09:35.07","Amount":{"Value":796.50,"Currency":{"Symbol":"€","Id":4,"Code":"EUR","Description":"Euro"}},"TransactionResults":[{"GatewayTransactionId":"1113036103","SplititTransactionId":0,"SplititGatewayTransactionId":null,"GatewayResultCode":"AUTH_ONLY","GatewayResultMessage":"AUTH_ONLY","OperationType":{"Id":1,"Code":"Authorize","Description":"Approved"},"GatewayResult":true,"GatewayTransactionDate":"2025-06-17T10:09:33.338Z","IsChargeback":false,"AVSResult":{"Code":null,"Description":null},"CVCResult":{"Code":null,"Description":null}}],"CardDetails":{"CardId":"WdCexD3eTJelpBgvOLomwk95DDYlJfJO9EJ","CardNumber":"************1111","CardExpMonth":null,"CardExpYear":null,"CardBrand":{"Id":2,"Code":"Visa","Description":"VISA"},"CardType":{"Id":1,"Code":"Credit","Description":"CREDIT"},"Bin":"411111","CardHolderFullName":"a**** d***","CardCvv":"[Filtered]","Address":{"AddressLine":"qweqweqw","AddressLine2":null,"City":"portimao","Country":"PT","State":null,"Zip":"8500-112","FullAddressLine":"qweqweqw,portimao,PT"},"Token":null,"FpanLast4Digits":null},"Result":true}],"LogoU'+'rl":null,"IsInAutoRetry":false,"PaymentMethod":"CreditCard","AllowCardUpdateOnSplititPortals":true,"OnHoldLastOpenDate":null,"OnHoldLastOpenUserId":null,"InstallmentsScheduleInterval":0,"ExternalPaymentProvider":null,"TerminalApiKey":null,"AmountData":null,"IsPlanWithConsumerFees":false,"NextAuthorization":null,"AnnualPercentageRate":null}}'
   )
   SIGNATURE_B64 = (
   "NC7LOhvRK4JSx0Weibp4gob2L27KSqUg7DHDGaJrRk8PQL+kCCASyvo6f5PjHa0ehJg5eODkWmnOMPpXGVjsvI47A7/L0uxwu/TBWQwo3oLWFYAcSoDwFk6Qbkbh1PrpgI9oRbOtkfLkbVOfdJiubbrFE2kVIgRk7iGdVGZDMh3f17Frqs/57nP0j8qjyFvNmZdO36njKiIbMzVkc6AShCMMOXaI7BP4doUQJIhFQNihsZFC02PpYB5KbKGGiVntEAMyF8//KNyfcgG3ijd8Zjx+gT9/x2/aVZdqTsq9pNWvUApngZVUwPFg7v5dCEhBFf/PsF5LvTqMN8sjxUe/Sw=="
   )

   def verify_signature(message: bytes, signature_b64: str) -> bool:
   """Verify RSA‑PSS SHA‑256 signature using the public key from the certificate."""

   cert = x509.load_pem_x509_certificate(CERT_PEM.encode())
   public_key = cert.public_key()
   signature = base64.b64decode(signature_b64)

   try:
   public_key.verify(
   signature,
   message,
   padding.PSS(
   mgf=padding.MGF1(hashes.SHA256()),
   salt_length=hashes.SHA256().digest_size,  # 32‑byte salt matches .NET default
   ),
   hashes.SHA256(),
   )
   return True
   except Exception:
   return False


   if __name__ == "__main__":
   message = f"{IDEMPOTENCY_KEY};{BODY}".encode()
   if verify_signature(message, SIGNATURE_B64):
   print("✔ Signature is VALID (RSA‑PSS/SHA‑256)")
   else:
   print("✖ Signature is INVALID")

Parameterized Webhooks​

You can request that Splitit support enable parameterized webhooks for you, which will enable you to receive certain plan parameters either directly in your webhook's querystring or in its URL. Available parameters include installment plan number, terminal id, terminal api key, and merchant id.

Querystring Parameters​

Request that parameters be returned directly in your webhook's querystring. So, for example, if you request to receive installment plan number, terminal id, terminal api key, and merchant id in your querystring, the following webhook structure will be returned:

https://webhook.site/{__webhook number__}?ipn={__INSTALLMENTPLANNUMBER__}&terminalId={__TERMINALID__}&terminalapikey={__TERMINALAPIKEY__}&merchantId={__MERCHANTID__}**

e.g.:

https://webhook.site/c72da947-52c8-4809-91d1-41f0c85f35bb?ipn=004FANS65QE9LU4D9O90&terminalId=39817&terminalapikey=b127c9a4-4c22-4791-97c4-c9f8da665a60&merchantId=91157

URL Parameters​

Request that parameters be returned in the URLs of your webhooks. So, for example, if you request to receive installment plan number, terminal id, terminal api key, and merchant id in your URLs, the following webhook structure will be returned:

https://webhook.site/{__webhook number__}/{__INSTALLMENTPLANNUMBER__}/{__TERMINALID__}/{__TERMINALAPIKEY__}/{__MERCHANTID__}/

e.g.:

https://webhook.site/c72da947-53c8-4809-90d1-41f0c85f35bb/54443224184238313683/30817/b628b9a4-4c21-4691-97c4-c9f8da665a60/01657/