Overview

To integrate with your system, elepay provides Webhooks and related tools for handling asynchronous notifications.

Webhook

A webhook is a mechanism for receiving notifications about events that occur in a service via an external URL over HTTP.

Tools

We provide development tools such as sending webhook notifications, request logs, and response format validation. See the developer tools for details.

Usage Guide

Use cases

With webhooks, you can have elepay notify any URL when events like the following occur:

• When a payment is completed successfully
• When a refund is completed successfully

Simply add a destination URL in the elepay dashboard and the above events will be delivered automatically.

Setup

Log in to the elepay dashboard. From the management screen shown below, add your webhook destination. Enter the URL, select event types, and click Add. You can register multiple webhook endpoints.

1. Webhook URL

Specify the URL that receives webhook notifications under “Developer Settings / Webhook”.

2. Test mode and Live mode

Both Test mode and Live mode are supported. Use the Test/Live toggle at the top of the dashboard to manage settings for each environment.

3. Webhook events

elepay defines the webhook notification events. When an event listed below occurs, a corresponding webhook notification is sent.

Request

All elepay webhooks are sent as POST requests. The request body contains the event JSON data.

Event list

These are the event types actually sent by elepay. The event type is contained in the JSON under type.

📘 charge.waiting, charge.notified and charge.mismatched occur only with convenience store payments and bank transfers. charge.mismatched means the amount received does not match the amount requested, and needs to be handled on your side.

Below is an example of the event data sent when a payment of 1800 JPY succeeds.

{
  "id": "evt_la06CoQAiPojSgJKe5gt3nwq",
  "object": "event",
  "createTime": 1543944030817,
  "liveMode": false,
  "type": "charge.succeeded",
  "data": {
    "object": {
      // Charge object
    }
  }
}

The data field contains the detailed content of the event. Its structure matches the JSON returned by the API.

Receiving notifications

Success handling

When you successfully receive a webhook notification, return an HTTP 2xx status code.

Error handling

If receiving the webhook fails, be sure to return an HTTP 4xx or 5xx status code. elepay will automatically retry 5 times beyond the initial delivery (6 deliveries in total), giving up after about 21 minutes.

If delivery still fails, use the synchronous APIs to reconcile the payment status.

⚠️ The second delivery arrives as soon as 5 seconds after the first. Do not size your idempotency window in minutes. Duplicate deliveries of the same event can always happen, so always deduplicate on the event id.

These are platform-wide values. They cannot be configured per merchant.

Authenticity

All webhook requests from the elepay servers include an elepay-Signature header. The header looks like this:

Format:
elepay-Signature: t=[timestamp],sign=[signature]

Example:
elepay-Signature: t=1581064080,sign=100dcc3d839c89cd91ecdd23d7305b2fdb8ae73b498c27efd812b25fc86ec702

📘 HTTP header names are case-insensitive (RFC 9110). Use your framework's case-insensitive accessor. Do not match the name as a literal string.

Authenticity verification logic

The signature is generated by applying the HMAC‑SHA256 algorithm using the timestamp and a verification secret. You can view or regenerate the secret on the webhook details page in the dashboard.

1. Extract the timestamp and signature from the header.
2. Read the request body data.
3. Create the string: <timestamp from 1> + "." + <body from 2>.
4. Using the verification secret, sign the string from step 3 with HMAC‑SHA256.
5. Compare the result from step 4 with the signature from step 1 to verify authenticity.

Implementation notes

• Sign the raw request body. Do not parse and re-serialize it before verifying.
• The timestamp tolerance defaults to 300 seconds. The official Java SDK's Webhook.verifyHeader(payload, sigHeader, secret) uses this value and rejects the request as a replay when t= differs from the current time by more than 300 seconds, in either direction.
• Do not write an implementation that reads only one sign=. Deliveries currently carry a single sign=, but the SDK scans every comma-separated value and accepts the request if any one of them matches. Mirror that behaviour in a hand-rolled verifier.
• Prefer the official SDK's Webhook.verifyHeader over a hand-rolled implementation.