Webhooks

A webhook is a URL that can be used as a callback to receive information when an event is triggered within the UnivaPay platform. Payloads for a webhook are delivered via a POST request. The body of the request will contain a JSON object with relevant data resource. Webhooks can be created via the merchant console (see Guide).

The following table displays all events you can register a webhook, their payload resource model, and a short description of the triggering event.

Event nameResource typeInfo
charge_updatedchargeA charge is updated (authorizedawaiting)
charge_finishedchargeA charge is finalized (cancelederrorfailedsuccessful)
subscription_paymentsubscriptionA payment is received for a subscription
subscription_completedsubscriptionA subscription has been completed
subscription_failuresubscriptionA payment failed to complete for a subscription
subscription_canceledsubscriptionA subscription has been canceled
subscription_suspendedsubscriptionA subscription has been suspended
subscription_createdsubscriptionA subscription has been created
token_createdtokenA transaction token has been created
token_updatedtokenA transaction token has been updated
token_cvv_auth_updatedtokenA transaction token data.cvv_authorized.status has been updated
recurring_token_deletedtokenA recurring token has been deleted
token_replasedtokenA recurring token has been replased
refund_finishedrefundA refund is finished (success/failure)
cancel_finishedcancelA cancel is has been finalized and received
customs_declaration_finishedcustoms declarationA customs declaration has been finalized
{
  "event": "charge_finished",
  "data": {
    "id": "11e8d04b-5143-f59c-9fa3-e81a25b8537d",
    "store_id": "11e8707d-f289-db48-9d47-dee2fc997783",
    "transaction_token_id": "11e8d04b-5129-9120-9fa1-45a9442661a0",
    "transaction_token_type": "one_time",
    "subscription_id": null,
    "requested_amount": 1500,
    "requested_currency": "JPY",
    "requested_amount_formatted": 1500,
    "charged_amount": 1500,
    "charged_currency": "JPY",
    "charged_amount_formatted": 1500,
    "only_direct_currency": false,
    "capture_at": null,
    "descriptor": null,
    "status": "successful",
    "error": null,
    "metadata": {
      "customer_name": "Carl Ferguson",
      "memo": "MID-12345678",
      "gpapps_contract_id": "98013bca-5fad-4076-85ff-0b5c87f39165"
    },
    "mode": "test",
    "created_on": "2018-10-15T07:24:13.933088Z"
  }
}
{
  "event": "refund_finished",
  "data": {
    "id": "11e8d04c-76ac-f3a0-9fbc-5600743c02b7",
    "store_id": "11e8707d-f289-db48-9d47-b1122dd49d32",
    "charge_id": "11e8d04c-1591-d89c-9fb6-d773e56d5320",
    "status": "failed",
    "amount": 1200,
    "currency": "JPY",
    "amount_formatted": 1200,
    "reason": "customer_request",
    "message": "Test refunds",
    "error": {
      "code": 309,
      "message": "Test refund failed purposely",
      "details": "Test refund failed purposely"
    },
    "metadata": {},
    "mode": "test",
    "created_on": "2018-10-15T07:32:26.193631Z"
  }
}
{
  "event": "customs_declaration_finished",
  "data": {
    "id": "24c6c41f-93bd-4469-ada3-f4819be8b4f8",
    "charge_id": "11ec053a-52b5-8464-bb85-d76d3bef56e9",
    "merchant_id": "11ec053a-5252-2cde-bb85-f3646674285f",
    "store_id": "11ec053a-5275-cba8-bb85-ffc3cc0b6f21",
    "mode": "live_test",
    "gateway": "we_chat_online",
    "declaration": {
      "customs": "HANGZHOU_ZS",
      "merchant_customs_no": "123456",
      "certificate_id": "certificateIdTest",
      "certificate_name": "certificateNameTest"
    },
    "declaration_result": {
      "trade_id": "2018112288340107038204310100000",
      "approving_authority": "UNIONPAY"
    },
    "status": "successful",
    "error": null,
    "created_on": "2021-08-25T09:21:00.052073+09:00"
  }
}
{
  "event": "customs_declaration_finished",
  "data": {
    "id": "bdb058f3-1231-4817-8c00-a9bf37d07bfe",
    "charge_id": "11ec053c-a2f0-8d82-a653-07800a68253f",
    "merchant_id": "11ec053c-a28f-3190-a653-6702fd115e11",
    "store_id": "11ec053c-a2ae-d6b2-a653-2fdb82d75fa5",
    "mode": "live_test",
    "gateway": "we_chat_online",
    "declaration": {
      "customs": "HANGZHOU_ZS",
      "merchant_customs_no": "123456",
      "certificate_id": "certificateIdTest",
      "certificate_name": "certificateNameTest"
    },
    "declaration_result": {
      "trade_id": "2018112288340107038204310100000",
      "approving_authority": "UNIONPAY"
    },
    "status": "failed",
    "error": {
      "code": 304,
      "message": "Identity information is not matched"
    },
    "created_on": "2021-08-25T09:37:33.618921+09:00"
  }
}

Webhook object

The following table describes the webhook object model when creating the webhook. Please take note that this is not the model that is sent to the webhook, but the configuration object when describing the webhook.

Webhooks can be linked to a merchant or a store. Merchant linked webhooks are triggered events occuring on all stores while store linked webhooks are triggered only for that specific store and are denoted by the presence of the store_id field.

Fields
idUUID
The UUID to identify the webhook.
merchant_idUUID
The UUID of the merchant that the webhook belongs to
store_idUUID
The UUID of the store that the webhook belongs to
triggersarray[string]
A list of events that will trigger this webhook to fire a request
urlstring
The URL of the endpoint to send the webhook request to
auth_tokenstring
An optional authorization header value to include when sending the webhook request
activeboolean
Whether the webhook is enabled
created_onstring (ISO-8601)
The date the webhook was created on