Event Handling

All payment and form events are delivered as a single CustomEvent on the document:

const cleanup = revup.onRevupMessage((event) => {
  // Handle events
});

Use payload.type and payload.source to handle:

• Form events — source === 'form' (e.g. initialized, validation.changed, payment.submitted, payment.action_required, payment.success, payment.failed).
• APM events — source === 'apm' (e.g.payment.submitted, payment.success, payment.failed, payment.cancelled, apm.unavailable).

The returned cleanup function removes the event listener when called.

Event Sources

SOURCE	DESCRIPTION
'form'	Events related to the credit card form
'apm'	Events related to Alternative Payment Methods

Event Types Reference

TYPE	SOURCE	DESCRIPTION
'initialized'	'form'	SDK component initialized and ready
'validation.changed'	'form'	Form validation state changed
'payment.success'	Both	Payment successfully approved
'payment.failed'	Both	Payment failed
'payment.cancelled'	'apm'	User cancelled APM payment
'apm.unavailable'	'apm'	Requested APM is not available
'payment.action_required'	'form'	Action required in order to complete payment (3DS payments)
'payment.submitted'	Both	Payment submitted

Event Payload Structure

{
  type: string,      // Event type
  source: string,    // 'form' or 'apm'
  context?: {        // Present for successful events
    transactionId: string,
    orderId: string,
    apm?: string     // For APM events
  },
  data?: Record<string, unknown>,  // Event-specific payload
  error?: {          // Present for error events
    code: string,
    message: string,
    statusCode?: number
  }
}

Example - Success Event

{
  "type": "payment.success",
  "source": "form",
  "context": {
    "orderId": "86e85e5b-f4ce-4e71-be5f-457b44b3ddd5",
    "transactionId": "05145e19-f7b6-4932-921e-9330ac7ffd15"
  },
  "data": {
    "transactionResult": {
      "status": 200,
      "response": {
        "transactionStatus": "success",
        "message": "The payment has been processed successfully",
        "transactionId": "05145e19-f7b6-4932-921e-9330ac7ffd15"
      }
    }
  }
}

Complete Event Handler Example

const onRevupMessageHandler = (event) => {
  const { type, source, context, error } = event;
  switch (type) {
    case 'initialized':
      // Form/APM ready;
      break;
    case 'payment.submitted':
      // Submitted — the payment was submitted
      break;
    case 'payment.action_required':
      // DDC — the merchant has to do a redirect because the payment network is DDC
      // url: data.transactionResult.response.action.url //url from ddc api
      // status: data.transactionResult.response.transactionStatus ("waiting_user_interaction")
      // transactionId: data.transactionResult.response.transactionId
      break;
    case 'payment.success':
      // Success — use context.transactionId, context.orderId
      break;
    case 'payment.failed':
      // Declined or error — use error.message, error.statusCode
      break;
    case 'payment.cancelled':
      // User cancelled (APM)
      break;
    case 'apm.unavailable':
      // APM not available — context.apm, error.message
      break;
    default:
      break;
  }
};

const revupMessageCleanup = revup.onRevupMessage((event) => {
  onRevupMessageHandler(event);
});

Overview

Revup communicates the state of the payment experience through a unified event system. Each event describes what is happening inside the SDK (form readiness, validation, payment progress, success, failure, or cancellation) so your checkout can react accordingly.

Events allow your checkout to stay in sync with the payment flow without relying on assumptions.

Typical Use Cases

• Showing or hiding loading states
• Enabling or disabling payment actions based on input validity
• Preventing duplicate submissions during processing
• Handling successful payments and continuing the order flow
• Displaying meaningful failure messages and allowing retry
• Detecting when a user cancels an alternative payment method
• Disabling payment methods that are not available

All events are delivered through a single native DOM event (onRevupMessage) and follow a consistent structure.

---

Listening for Events

const revupMessageCleanup = revup.onRevupMessage((event) => {
    console.log('Received Revup event:', event);
});

The returned cleanup function removes the event listener when called.

---

Event Structure

Each event includes core fields and optional sections depending on the situation.

Core Fields

Field	Type	Description
id	string	Unique identifier for the event. Useful for logging or deduplication.
type	string	Describes what happened (e.g., payment.success, payment.failed).
source	string	Indicates where the event originated: form (card form) or apm (alternative payment methods).
timestamp	string	ISO 8601 timestamp of when the event occurred.

Context Object (when available)

Some events include a context object with additional identifiers:

Field	Description
transactionId	Identifier of the payment transaction. May be missing in early failure scenarios.
orderId	Identifier of the order, typically available once a transaction exists.
apm	Present only for APM events. Indicates the payment method: apple_pay, google_pay, paypal, stripe_link.

Data Object (event-specific)

Contains additional information depending on the event. Common examples include form validity or whether a submission is in progress. Please bear in mind that at times the Data Object may return more data depending on the event.

Field	Description
data.isValid	Whether the form is fully valid (card form)
data.isCalling	Whether a submission is currently in progress (card form)
data.complete	Whether the element is complete (Stripe Link)
data.transactionResult	Gateway response details (on payment events)

Error Object (only on specific events)

Field	Description
name	Category of the error (see Error Names Reference below)
message	Human-readable explanation (sanitized)
statusCode	HTTP status code when the failure originated from an HTTP response (e.g., 400, 401, 500). Absent for client-side or SDK-internal errors.
details	Optional extra diagnostic information

---

Error Names Reference

Events with an error field include a machine-readable error.name that identifies the origin:

error.name	Origin
apms_initialization_error	APMs SDK initialization (config validation, availability check)
apple_pay_error	Apple Pay module
google_pay_error	Google Pay module
paypal_error	PayPal module
stripe_link_error	Stripe Link module
PaymentFailed	Form gateway decline (transactionStatus: 'failed')
FormSubmitError	Form submission failure (network error, unexpected exception)

---

Event Types

initialized

Indicates that a payment component has finished loading and is ready for interaction.

Where it is emitted

• Card form → always
• APMs → not emitted

How to use it

Use this event to remove loading placeholders and display the payment UI. It should not be used as a signal that the payment can be submitted.

---

validation.changed

Indicates that the validity or completeness of input has changed.

Where it is emitted

• Card form → whenever any field changes validity

Payload

Field	Description
data.isValid	Whether the form is fully valid (card form)
data.isCalling	Whether a submission is currently in progress (card form)
data.complete	Whether the element is complete (Stripe Link)

How to use it

This is the primary signal for enabling or disabling your payment action. Use it to reflect whether the user can proceed.

---

payment.submitted

• Card form and APMs → whenever any field changes validity

  Indicates that a payment attempt has started or progressed.

How to use it

Do not interpret it as success or failure. Treat it strictly as a processing state.

---

payment.action_required

Indicates that the merchant has to take action to proceed with the payment.

What it means

Usually refers to a DDC (Direct Digital Challenge) action, where the user must be redirected to the specified action URL for 3DS authentication.

What to expect

Field	Description
data.transactionResult.response.action.url	URL to redirect the user for 3DS challenge
data.transactionResult.response.transactionId	Transaction identifier
data.transactionResult.response.transactionStatus	"waiting_user_interaction"

How to use it

Redirect the user to the action.url to process the 3DS/DDC challenge.

---

payment.success

Indicates that the payment has been successfully approved.

What it means

This is a terminal success event.

What to expect

• context.transactionId and context.orderId are typically present
• For APMs, context.apm identifies the method used
• data.transactionResult.message contains the gateway response message
• data.transactionResult.transactionStatus contains the transaction status

How to use it

Proceed with order confirmation, success messaging, and fulfillment.

---

payment.failed

Indicates that the payment did not complete successfully.

What it means

This is a terminal failure event.

What to expect

• An error object with name, message, and optionally statusCode
• context.transactionId may be absent if failure occurs before a transaction is created
• The form recovers automatically — do not rethrow the error

Triggers

Trigger	error.name
Gateway decline (API returns transactionStatus: 'failed')	PaymentFailed
Network failure or unhandled exception during submission	FormSubmitError

How to use it

Show a clear, user-friendly error message and allow retry or alternative payment methods.

---

payment.cancelled

Indicates that the user cancelled an alternative payment flow.

Where it is emitted

APMs only.

What it means

The user voluntarily stopped the payment process. This should not be treated as a failure.

Payload

All APMs include data: { message: 'User cancelled' } on this event.

How to use it

Restore the checkout state and allow the user to try again or choose another method.

---

apm.unavailable

Indicates that an alternative payment method cannot be used.

What to expect

Field	Description
context.apm	Identifies the method — may be absent when the error originates from APMs SDK initialization
error.name	Identifies the origin (e.g., apms_initialization_error, apple_pay_error)
error.message	Explains the reason
error.statusCode	Present when the failure came from an HTTP response

How to use it

Hide or disable the unavailable payment method and offer alternatives.

---

Differences by Source

Card Form Events (source: form)

The form runs inside a sandboxed iframe. All form messages are relayed to the merchant via MessageService.

Typical events:

• initialized
• validation.changed
• payment.submitted
• payment.action_required
• payment.success / payment.failed

Does NOT emit:

• payment.cancelled

---

APM Events (source: apm)

Each APM (apple_pay, google_pay, paypal, stripe_link) dispatches events with context.apm set to the APM identifier.

Typical events:

• apm.unavailable
• payment.submitted
• payment.cancelled
• payment.success / payment.failed

---

Event Dispatch Quick Reference

Event	source: form	source: apm
initialized	✅	❌
validation.changed	✅	✅ Stripe Link
payment.submitted	✅	✅ All APMs
payment.action_required	✅	✅ All APMs
payment.success	✅	✅ All APMs
payment.failed	✅	✅ All APMs
payment.cancelled	❌	✅ All APMs
apm.unavailable	❌	✅ All APMs

---

Recommended Integration Behavior

Recommendation	Reason
Use validation.changed as main signal to enable/disable payment actions	Reflects real-time input validity
Treat payment.submitted strictly as a processing state	Not success or failure
Only payment.success, payment.failed, or payment.cancelled end a payment attempt	Terminal events
Handle missing transactionId gracefully in early failures	Transaction may not exist yet
Remove or disable APMs immediately when apm.unavailable is received	Prevents user confusion

---

Important Notes

• Events are sanitized and never contain raw card data or sensitive information (card numbers, CVVs, API keys, and other PCI/PII patterns are masked).
• error is only present on payment.failed and apm.unavailable events.
• error.statusCode is present when the failure originated from an HTTP response; absent for client-side or SDK-internal errors.
• context.apm is absent on apm.unavailable events fired by the APMs SDK initialization itself.
• context.orderId is present on all form events and on all APM payment outcome events; may be absent on apm.unavailable from individual APM modules.
• Critical SDK errors (misconfiguration, missing required fields) throw exceptions — they are not dispatched as events.
• Not all payment methods emit the same set of events.
• Always design your UI around event meaning rather than assumptions about sequence.

---

Glossary

Term	Definition
APM	Alternative Payment Method (Apple Pay, Google Pay, PayPal, Stripe Link)
Terminal event	An event that ends a payment attempt (payment.success, payment.failed, payment.cancelled)
In-progress event	Indicates the payment is ongoing (payment.submitted)
Validity event	Indicates whether input is complete or valid (validation.changed)

---

For additional support, contact our Technical Support team at support@revuppayments.com