2xx response, and Jupico will POST a JSON payload for each subscribed event.
Payload structure
Every event uses the same envelope:
Each request is sent with these headers:
Your endpoint should respond quickly (a
2xx within a few seconds) and process the event asynchronously.Endpoint requirements
- Use HTTPS with a valid TLS certificate.
- Accept
POSTrequests with a JSON body. - Return a
2xxstatus code once you accept the event. - Be idempotent — the same event may be delivered more than once.
Subscribing to events
Webhooks are opt-in per event. Jupico sends an event only when both of these are true:- Your product has a webhook URL configured.
- Your product is subscribed to that event.
onApplicationInitiated, onMerchantSubmit, onMerchantActivation, onMerchantBankAccountActivation, onMerchantSubmitRemsExtension). To receive any other event — for example onHostedSessionSaleSucceeded — ask your Jupico account team to enable it for your product.
Event catalog
Jupico emits webhooks across onboarding, disputes, payouts, subscriptions, installments, transactions, and hosted sessions.Onboarding
Onboarding
onApplicationInitiated— an application has been initiated.onMerchantSubmit— a merchant has submitted their application.onMerchantActivation— a merchant has been activated.onMerchantSubmitRemsExtension— sent on application submission with extended application data.
Disputes
Disputes
onDisputeInitiated— a new dispute has been created.onDisputeUpdated— a dispute has been updated.
Payouts and bank accounts
Payouts and bank accounts
onPayoutInitiated— a new payout has been created.onMerchantBankAccountActivation— a merchant’s bank account has been activated.
Subscriptions
Subscriptions
onSubscriptionCreated— a subscription has been created.onSubscriptionActivated— a subscription has become active.onSubscriptionDeactivated— a subscription has become inactive.onSubscriptionCanceled— a subscription has been canceled.onSubscriptionPaused— a subscription has been paused.
Subscription executions
Subscription executions
onSubscriptionExecutionSucceeded— a subscription payment succeeded.onSubscriptionExecutionFailed— a subscription payment failed.onSubscriptionExecutionSkipped— a scheduled subscription payment was skipped.
Installments
Installments
onInstallmentCreated— an installment plan has been created.onInstallmentActivated— an installment plan has become active.onInstallmentDeactivated— an installment plan has become inactive.onInstallmentPaused— an installment plan has been paused.onInstallmentExecutionSucceeded— an installment payment succeeded.onInstallmentExecutionFailed— an installment payment failed.onInstallmentExecutionSkipped— a scheduled installment payment was skipped.
Transactions
Transactions
onCardPresentTransactionCreated— a card-present transaction has been created.onEcheckReturnCreated— the bank returned an eCheck (ACH) payment. Sent for every ACH return, whether the payment was funded or not. See eCheck return payloads.
Hosted pages
Hosted pages
onHostedSessionSaleSucceeded— a sale succeeded on a hosted page (checkout, payment link, or invoice).onHostedSessionSaleFailed— a sale attempt failed on a hosted page.
Onboarding payloads
The
invite object is included only when the application originated from an invite.Dispute payloads
Payout and bank account payloads
Subscription payloads
Subscription execution payloads
eCheck return payloads
Jupico sendsonEcheckReturnCreated for every ACH return, whether it arrives before or after funding:
- Non-funded return: the bank returned the payment before it was funded. The transaction is declined, and the payload includes
transaction.declineReason. - Funded return: the bank returned the payment after it was funded. The transaction status becomes
returned.
Jupico no longer sends a separate
onEcheckDeclined event. Non-funded returns now go out as onEcheckReturnCreated. If you handled onEcheckDeclined, move that logic to onEcheckReturnCreated and check for transaction.declineReason.reasonDescriptionis the bank’s description of the return reason (for example,Insufficient Funds). It is included for both funded and non-funded returns when the bank provides it.transaction.declineReasonis included only for non-funded returns.responseCodes.processor.codeholds the ACH return code (for example,R01).- Use
transaction.transactionIdto match the return to the original eCheck sale.
Hosted page payloads
session.sessionIdis the hosted session ID. For a checkout, it matcheshostedSession.hostedSessionIdreturned when you create the checkout. Store it so you can match the webhook to your order.session.typeischeckout,paymentlink, orinvoice.customeris included only when the session has a customer.transactionis included on a failed sale only when the attempt reached the processor (for example, a decline).paymentTokenis included when the payment method was saved during the session.
Recommended handling
1
Receive the request
Accept
POST requests at your registered webhook URL.2
Authenticate the sender
Verify the request came from Jupico using the mechanism agreed with your account team.
3
Persist and acknowledge
Store the raw payload and return
2xx before doing any heavy work.4
Process asynchronously
Handle the event in a background job so slow processing does not block delivery.
5
Deduplicate
Make processing idempotent using a unique identifier from
data (for example, transactionId or subMerchantId) combined with event, so reprocessing the same event is safe.6
Reconcile on drift
If an event references a resource in an unexpected state, use the Query API or Backoffice to fetch the authoritative record.
Delivery behavior
Jupico makes one delivery attempt per event, with a 30-second timeout. Failed deliveries — a non-2xx response, a timeout, or an unreachable endpoint — are not retried automatically.
Testing
- Use a tunneling tool (for example, ngrok) or a webhook inspection service (for example, webhook.site) to receive sandbox events during development.
- Trigger events by performing the relevant action in sandbox (activating a submerchant, completing a hosted session, or executing a subscription cycle).
Best practices
Return 2xx quickly
Acknowledge as soon as possible and process asynchronously.
Store the raw payload
Keep the full JSON body for auditing and reprocessing.
Process idempotently
Reprocessing the same event must be safe.
Reconcile via the API
Failed deliveries are not retried — reconcile with the Query API on a schedule.

