Worldpay.Webhooks (Worldpay v1.0.0)

Copy Markdown View Source

Worldpay webhook event parsing and dispatch.

Worldpay pushes payment lifecycle events to your HTTPS endpoint as JSON.

Setup

Register your endpoint URL with your Worldpay Implementation Manager. Your endpoint must use HTTPS with a SHA-256+ certificate chain.

Phoenix example

# router.ex
post "/worldpay/webhook", WorldpayWebhookController, :handle

# controller
def handle(conn, _params) do
  {:ok, body, conn} = Plug.Conn.read_body(conn)

  case Worldpay.Webhooks.parse(body) do
    {:ok, event} ->
      MyApp.PaymentHandler.handle_event(event)
      send_resp(conn, 200, "ok")

    {:error, reason} ->
      Logger.error("Worldpay webhook parse error: #{inspect(reason)}")
      send_resp(conn, 400, "bad request")
  end
end

Event types

Card: :authorized · :sent_for_settlement · :settled · :settlement_failed · :charged_back · :chargeback_reversed · :dispute_expired · :refunded · :partially_refunded · :cancelled · :refused · :sent_for_authorization · :updated

APM: :apm_authorized · :apm_pending_merchant · :apm_failed · :apm_request_expired · :pix_confirmed

Payout: :payout_sent · :payout_failed · :payout_reversed

Token: :token_created · :network_token_created · :network_token_updated · :network_token_deleted

Summary

Types

event()

Functions

event_type(body)

Extract the event type atom from a raw webhook body map.

handle(event, handler_module)

Dispatch a parsed event to a handler module implementing Handler.

parse(body)

Parse a raw Worldpay webhook JSON body into a structured event.

Types

event()

@type event() :: %{
  type: atom(),
  payment_id: String.t() | nil,
  order_reference: String.t() | nil,
  command_id: String.t() | nil,
  downstream_reference: String.t() | nil,
  last_event: String.t() | nil,
  amount: %{required(String.t()) => term()} | nil,
  currency: String.t() | nil,
  payment_instrument: %{required(String.t()) => term()} | nil,
  risk_factors: [term()] | nil,
  raw: %{required(String.t()) => term()}
}

Functions

event_type(body)

@spec event_type(%{required(String.t()) => term()}) :: atom()

Extract the event type atom from a raw webhook body map.

handle(event, handler_module)

@spec handle(event(), module()) :: :ok | {:error, term()}

Dispatch a parsed event to a handler module implementing Handler.

parse(body)

@spec parse(String.t() | %{required(String.t()) => term()}) ::
  {:ok, event()}
  | {:error, {:json_decode_error, Jason.DecodeError.t()} | :invalid_body}

Parse a raw Worldpay webhook JSON body into a structured event.

Accepts a JSON binary or a pre-decoded string-keyed map. Returns {:ok, event()} or {:error, {:json_decode_error, Jason.DecodeError.t()} | :invalid_body}.