Skip to main content
Webhooks let Jupico push events to your backend as they happen. Register an HTTPS endpoint that returns a 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 POST requests with a JSON body.
  • Return a 2xx status code once you accept the event.
  • Be idempotent — the same event may be delivered more than once.
Confirm the authentication mechanism for your webhook endpoint with your Jupico account team before going live. Reject unauthenticated requests.

Subscribing to events

Webhooks are opt-in per event. Jupico sends an event only when both of these are true:
  1. Your product has a webhook URL configured.
  2. Your product is subscribed to that event.
New products are subscribed to the onboarding events only (onApplicationInitiated, onMerchantSubmit, onMerchantActivation, onMerchantBankAccountActivation, onMerchantSubmitRemsExtension). To receive any other event — for example onHostedSessionSaleSucceeded — ask your Jupico account team to enable it for your product.
Registering a webhook URL is not enough. If you are not subscribed to an event, it is never sent and is not queued for later.

Event catalog

Jupico emits webhooks across onboarding, disputes, payouts, subscriptions, installments, transactions, and hosted sessions.
  • 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.
  • onDisputeInitiated — a new dispute has been created.
  • onDisputeUpdated — a dispute has been updated.
  • onPayoutInitiated — a new payout has been created.
  • onMerchantBankAccountActivation — a merchant’s bank account has been activated.
  • 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.
  • onSubscriptionExecutionSucceeded — a subscription payment succeeded.
  • onSubscriptionExecutionFailed — a subscription payment failed.
  • onSubscriptionExecutionSkipped — a scheduled subscription payment was skipped.
  • 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.
  • 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.
  • 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 sends onEcheckReturnCreated 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.
  • reasonDescription is 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.declineReason is included only for non-funded returns. responseCodes.processor.code holds the ACH return code (for example, R01).
  • Use transaction.transactionId to match the return to the original eCheck sale.

Hosted page payloads

  • session.sessionId is the hosted session ID. For a checkout, it matches hostedSession.hostedSessionId returned when you create the checkout. Store it so you can match the webhook to your order.
  • session.type is checkout, paymentlink, or invoice.
  • customer is included only when the session has a customer.
  • transaction is included on a failed sale only when the attempt reached the processor (for example, a decline).
  • paymentToken is included when the payment method was saved during the session.
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.
Do not rely on webhooks alone for critical state such as recording a payment. Periodically reconcile against the Query API (for example, checkouts with status paid) to catch any event your endpoint missed.

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.
Last modified on November 4, 2026