Webhooks Overview

Webhooks are a key feature of Jupico that allow you to receive real-time notifications about critical events in your system. By setting up webhooks, you can stay informed about the status of onboarding, disputes, and payouts without needing to constantly check for updates manually.

This section will guide you through setting up and configuring webhooks, as well as handling webhook events and payloads.

Onboarding Webhooks

onApplicationInitiated: Triggered when an application is initiated.
onMerchantSubmit: Triggered when a merchant submits their application.
onMerchantActivation: Triggered when a merchant is activated.

{
  "event": "onApplicationInitiated",
  "datetime": "2024-02-05T13:56:56.148Z",
  "data": {
    "onboardingId": "<hash>", 
    "applicationId": "<hash>",
    "subMerchantId": "<hash>",
    "applicant": {
      "name": "..",
      "email": "..", 
      "mobile": ".." 
    },
    invite: { (optional, if invited then must be included)
        inviteId: "<hash>"
        "reference": "ref provided by sp" 
    }
    "templates": {
        "feesTemplateId: "<hash>"
        "onboardingFlowTemplateId": "<hash>"
    }
  }
}

        "onboardingId": "<hash>", 
        "applicationId": "<hash>",
        "subMerchantId": "<hash>",
        "applicant": {
            "name": "..",
            "email": "..", 
            "mobile": ".." 
          },
        "identity": { 
            "business": {
                "legalName": "..",
                "dbaName": "..",
                "websiteUrl": "https://..",
                "address": {
                    "streetNum": "123",
                    "streetName": "main street",
                    "city": "ny",
                    "state": "NY",
                    "postalCode": "10001"
                }
            }
        },
        invite: { (optional, if invited then must be included)
            inviteId: "<hash>"
            "reference": "ref provided by sp" 
        }

        "templates": {
            "feesTemplateId: "<hash>"
            "onboardingFlowTemplateId": "<hash>"
        }
    }
}

{
    "event": "onMerchantActivation",
    "datetime": "2024-02-05T13:57:17.897Z",
    "data": {
        "onboardingId": "<hash>", 
        "applicationId": "<hash>",
        "subMerchantId": "<hash>",
        "applicant": {
            "name": "..",
            "email": "..", 
            "mobile": ".." 
          },
        "identity": { 
            "business": {
                "legalName": "..",
                "dbaName": "..",
                "websiteUrl": "https://..",
                "address": {
                    "streetNum": "123",
                    "streetName": "main street",
                    "city": "ny",
                    "state": "NY",
                    "postalCode": "10001"
                }
            }
        },
        invite: { (optional, if invited then must be included)
            inviteId: "<hash>"
            "reference": "ref provided by sp" 
        }

        "templates": {
            "feesTemplateId: "<hash>"
            "onboardingFlowTemplateId": "<hash>"
        }
        "tokenization": {
            "publicKey": "<hash>"
        },
        
    }
}

Dispute Webhooks

onDisputeInitiated: Triggered when a new dispute is created.
onDisputeUpdated: Triggered when a dispute is updated.

{
        "event": "onDisputeInitiated",
        "datetime": "2024-05-21T13:33:52.727Z",
        "data": {
            "submerchantId": "jpt-sim-md-1",
            "txId": "95aee3b1-b6a6-481c-ba02-f63eab1e1113",
            "disputeId": "115710100701",
            "disputeDate": "2021-06-21T00:00:00.000Z",
            "txAmount": 99.99,
            "disputeAmount": 99.99,
            "cardBrand": "<cardBrand>",
            "ccLast4Digits": "1234"
        }   
}

{
    "event": "onDisputeUpdated",
    "datetime": "2024-05-21T13:56:11.531Z",
    "data": {
        "submerchantId": "jpt-sim-md-1",
        "txId": "95aee3b1-b6a6-481c-ba02-f63eab1e1113",
        "disputeId": "115710100701",
        "disputeDate": "2021-06-06T00:00:00.000Z",
        "txAmount":  99.99,
        "disputeAmount": 99.99,
        "cardBrand": "<cardBrand>",
        "ccLast4Digits": "1234"
    }
}

Payouts & Bank Account Webhooks

onPayoutInitiated : Triggered when a new payout is created.
onMerchantBankAccountActivation: Triggered when a merchant's bank account is activated.

{
        "event": "onPayoutInitiated",
        "datetime": "2024-05-21T13:33:52.727Z",
        "data": {
            subMerchantId: payout.subMerchantId,
            amount: payout.amount,
            type: payout.type,
            payoutId: payout.payoutId,
            transactionType: payout.transactionType,
            batchPayoutId: payout.batchPayoutId,
            bankAccountRoutingNum: payout.accRoutingNum,
			bankAccountLast4Number
            bankAccountType: payout.accountType,
        }   
}

{
        "event": "onMerchantBankAccountActivation",
        "datetime": "2024-05-21T13:33:52.727Z",
        "data": {
				subMerchantId: subMerchantId
				bankAccountToken: payoutBankAccount.bankAccountToken,
    			accountRouting: payoutBankAccount.accountRouting,
    			accountNumber: payoutBankAccount.accountNumber,
    			accountType: payoutBankAccount.accountType,
    			nameOnAccount: payoutBankAccount.nameOnAccount,
    			status: payoutBankAccount.status,
  }
}

Subscription Webhooks

onSubscriptionCreated : Triggered when a subscription is created.
onSubscriptionActivated: Triggered when a subscription becomes active.
onSubscriptionDeactivated: Triggered when a subscription becomes inactive.
onSubscriptionCanceled: Triggered when a subscription is canceled.
onSubscriptionPaused: Triggered when a merchant's bank account is activated.

{
  "event": "onSubscriptionCreated",
  "datetime": "2025-09-16T18:55:53.882Z",
  "data": {
    "subscription": {
      "subMerchantId": "jpt-sim-md-1",
      "subscriptionId": "2dd0c808-9f86-4ca6-a88f-5f1c64a5ac59",
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "status": "active"
    },
    "plan": {
      "planId": "d490a96b-abe3-4168-8927-58b7f5c909eb",
      "name": "Per Usage Tiered Jewelry"
    },
    "customer": {
      "customerId": "606c0e63-b2ae-433c-b0c2-f7b6b793aa74",
      "name": "John Doe",
      "email": "",
      "phone": ""
    },
	  submerchant: {
      subMerchantId: "jpt-sim-md-1",
      dbaName: "JPT Kilback - Prohaska"
  	}
  }
}

{
  "event": "onSubscriptionActivated",
  "datetime": "2025-09-16T19:13:05.224Z",
  "data": {
    "subscription": {
      "subMerchantId": "jpt-sim-md-1",
      "subscriptionId": "2dd0c808-9f86-4ca6-a88f-5f1c64a5ac59",
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "status": "active"
    },
    "plan": {
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "name": "Flat"
    },
    "customer": {
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "name": "John Doe",
      "email": "",
      "phone": ""
    },
		submerchant: {
      subMerchantId: "jpt-sim-md-1",
      dbaName: "JPT Kilback - Prohaska"
  	}
  }
}

{
  "event": "onSubscriptionDeactivated",
  "datetime": "2025-09-16T19:11:35.628Z",
  "data": {
    "subscription": {
      "subMerchantId": "jpt-sim-md-1",
      "subscriptionId": "2dd0c808-9f86-4ca6-a88f-5f1c64a5ac59",
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "status": "inactive"
    },
    "plan": {
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "name": "Flat"
    },
    "customer": {
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "name": "John Doe",
      "email": "",
      "phone": ""
    }
  },
	submerchant: {
    subMerchantId: "jpt-sim-md-1",
    dbaName: "JPT Kilback - Prohaska"
	}
}

{
  "event": "onSubscriptionCanceled",
  "datetime": "2025-09-16T19:13:59.739Z",
  "data": {
    "subscription": {
      "subMerchantId": "jpt-sim-md-1",
      "subscriptionId": "2dd0c808-9f86-4ca6-a88f-5f1c64a5ac59",
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "status": "canceled"
    },
    "plan": {
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "name": "Flat"
    },
    "customer": {
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "name": "John Doe",
      "email": "",
      "phone": ""
    }
  },
	submerchant: {
    subMerchantId: "jpt-sim-md-1",
    dbaName: "JPT Kilback - Prohaska"
	}
}

{
  "event": "onSubscriptionPaused",
  "datetime": "2025-09-16T19:20:45.640Z",
  "data": {
    "subscription": {
      "subMerchantId": "jpt-sim-md-1",
      "subscriptionId": "2dd0c808-9f86-4ca6-a88f-5f1c64a5ac59",
      "planId": "a25c8d36-71a3-4036-ab13-f04542c90af6",
      "customerId": "973d8125-d1a5-4fa3-ae2e-81b08024d849",
      "status": "paused"
    },
    "plan": {
      "planId": "d490a96b-abe3-4168-8927-58b7f5c909eb",
      "name": "Per Usage Tiered Jewelry"
    },
    "customer": {
      "customerId": "e2e4d72e-2df2-4742-b131-50d45f8921ed",
      "name": "John Doe",
      "email": "",
      "phone": ""
    },
	  submerchant: {
      subMerchantId: "jpt-sim-md-1",
      dbaName: "JPT Kilback - Prohaska"
  	}
  }
}

Subscription Webhooks Executions

onSubscriptionExecutionSucceeded: Triggered when a subscription payment succeeds.

onSubscriptionExecutionFailed: Triggered when a subscription payment fails.

{
  "event": "onSubscriptionExecutionSucceeded",
  "datetime": "2025-09-16T18:04:39.422Z",
  "data": {
    "execution": {
      "executionId": "3d05f4ed-b679-4139-a242-969780191839",
      "date": "2026-09-01T17:29:48.770Z",
      "amount": 50,
      "status": "succeeded",
      "retriesQty": 0,
      "transactionId": "63021b73-5b04-4760-b9ca-8a94745c4f15"
    },
    "subscription": {
      "subscriptionId": "9e5e1df8-0563-4ca7-be99-4bbde7166a9a",
      "status": "active"
    },
    "plan": {
      "planId": "cd9d2cea-1009-4c95-8ef9-f77346530332",
      "name": "Per-usage-tiered"
    },
    "customer": {
      "customerId": "8ee0e138-04f8-4de7-ac88-df8b1ec23466",
      "name": "John Doe",
      "email": "",
      "phone": ""
    },
    "transaction": {
      "amount": 50,
      "transactionId": "63021b73-5b04-4760-b9ca-8a94745c4f15",
      "paymentMethod": {
        "type": "creditCard",
        "cc": {
          "card": {
            "cardHolderName": "John Doe",
            "last4Digits": "1111",
            "expirationMonth": "02",
            "expirationYear": "30",
            "logo": "Visa"
          },
          "provider": "jupico",
          "token": "5dd19881-b437-42b0-9c9b-7773ebb598eb",
          "tokenSessionId": "700b791f-d815-4a34-b66a-341b4f627c71",
          "cardHolderInitiated": false
        }
      }
    }
  }
}

{
  "event": "onSubscriptionExecutionFailed",
  "datetime": "2025-09-16T19:16:46.021Z",
  "data": {
    "execution": {
      "executionId": "400a91e0-b9df-4e25-9365-6fd7100a33ee",
      "date": "2025-09-16T19:14:56.877Z",
      "amount": 6000,
      "status": "retry",
      "retriesQty": 1
    },
    "subscription": {
      "subscriptionId": "e41d4710-4085-4ccb-85a1-42d6253a944a",
      "status": "active"
    },
    "plan": {
      "planId": "d490a96b-abe3-4168-8927-58b7f5c909eb",
      "name": "Per Usage Tiered Jewelry"
    },
    "customer": {
      "customerId": "e2e4d72e-2df2-4742-b131-50d45f8921ed",
      "name": "John Doe",
      "email": "",
      "phone": ""
    },
    "error": {
      "success": false,
      "code": "tx_cc_declined_amount_exeeded",
      "message": "Amount exceeded sub-merchant limit.",
      "data": {
        "operation": "ccCnpSale"
      }
    }
  }
}

Hosted Page Webhooks

onHostedSessionSale : Triggered when a sale is completed via a hosted session page.

{
  "event": "onHostedSessionSale",
  "datetime": "2025-12-01T12:44:53.541Z",
  "data": {
    "spProductId": "<productId>",
    "sessionId": "<sessionId>",
    "transactionId": "<transactionId>",
    "subMerchantId": "<subMerchantId>",
    "submerchant": {
      "subMerchantId": "<subMerchantId>",
      "dbaName": "<submerchant dba name>"
    },
    "transaction": {
      "status": "succeeded",
      "approvalNumber": "<approvalNumber>",
      "amount": 18,
      "txDate": "Mon, 01 Dec 2025 12:44:53 GMT",
      "taxAmount": 3,
      "description": "desc",
      "billing": {
        "name": "<cardholderName>",
        "address": "<billingAddress>",
        "city": "<city>",
        "zipCode": "<zipCode>",
        "state": "<state>",
        "country": "<country>"
      },
      "paymentMethod": {
        "type": "creditCard",
        "cc": {
          "card": {
            "cardHolderName": "<cardholderName>",
            "last4Digits": "<last4>",
            "expirationMonth": "<MM>",
            "expirationYear": "<YYYY>",
            "logo": "<cardBrand>",
            "type": "<debitOrCredit>"
          }
        }
      }
    }
  }
}