Webhooks Receive notifications whenever a transaction changes

Setup

Webhooks are URLs to services managed by you, which are invoked by Payyo every time a transaction changes.

Webhooks can be defined on the following JSON-RPC requests:

  • transaction.initiate
  • paymentPage.initialize
  • transaction.authorize
  • transaction.pay

Please note:

  • Webhook URLs must start with https://. Non-secure HTTP requests are not supported.
  • The request contains a JSON body containing the event data
  • Your service should return a 200 status code if the notification was received. Otherwise the request will be re-tried in the following intervals:
    1. 10 minutes after initial attempt
    2. 30 minutes after previous attempt
    3. 1 hour after previous attempt
    4. 2 hours after previous attempt
    5. 12 hours after previous attempt
    6. 24 hours after previous attempt
    After the last attempt the notification attempts will stop.

Events

Currently notifications are sent for the following events.

Authorization with 3D Secure

Transaction was initialized
{
  "event": {
    "type": "TransactionInitializedEvent",
    "time": "2017-06-20T09:31:57+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF",
      "funding_instrument_mask": "XXXX XXXX XXXX 4242",
      "customer": {
        "id": "cus_9b8a421bff5f30d20f118185eb6e",
        "name": "John Doe"
      }
    }
  }
}
Initialized transaction was aborted
{
  "event": {
    "type": "TransactionAbortedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462"
    }
  }
}
Initialized transaction was authorized
{
  "event": {
    "type": "TransactionAuthorizedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462"
    }
  }
}
Authorized transaction was voided
{
  "event": {
    "type": "TransactionVoidedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462"
    }
  }
}

Authorization without 3D Secure

Transaction was directly authorized (no 3D Secure)
{
  "event": {
    "type": "TransactionAuthorizedDirectEvent",
    "time": "2017-06-20T09:31:57+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF",
      "funding_instrument_mask": "XXXX XXXX XXXX 4242",
      "customer": {
        "id": "cus_9b8a421bff5f30d20f118185eb6e",
        "name": "John Doe"
      }
    }
  }
}
Authorized transaction was voided
{
  "event": {
    "type": "TransactionVoidedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462"
    }
  }
}

Capture

Transaction was captured
{
  "event": {
    "type": "TransactionCapturedEvent",
    "time": "2017-06-20T09:32:58+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF"
    }
  }
}
Captured transaction was cancelled
{
  "event": {
    "type": "TransactionCancelledEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462"
    }
  }
}

Settlement

Transaction was settled
{
  "event": {
    "type": "TransactionSettledEvent",
    "time": "2017-06-20T09:32:58+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462"
    }
  }
}
Settled transaction was refunded
{
  "event": {
    "type": "TransactionRefundedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "refund_id": "ref_ad1724d12ad2946e4814a26feaa2",
      "merchant_reference": "refund_10001",
      "amount": 3000,
      "currency": "CHF"
    }
  }
}
Transaction refund was queued
{
  "event": {
    "type": "TransactionRefundScheduledEvent",
    "time": "2017-06-20T09:32:58+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "refund_id": "ref_ad1724d12ad2946e4814a26feaa2",
      "merchant_reference": "refund_10001",
      "amount": 3000,
      "currency": "CHF"
    }
  }
}
Queued transaction refund was rejected/has failed
{
  "event": {
    "type": "TransactionRefundRejectedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "refund_id": "ref_ad1724d12ad2946e4814a26feaa2",
      "reason": "inadvertently_created|processed_through_other_means|insufficient_funds|fraud_risk|credit_card_expired|other",
      "message": "..."
    }
  }
}

Disputes

Dispute opened
{
  "event": {
    "type": "TransactionDisputeOpenedEvent",
    "time": "2017-06-20T09:32:58+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF",
      "reason": "Chargeback by customer",
      "status": "open",
      "opened_at": "2018-01-01T10:00:00+0000",
      "resolved_at": null,
      "reopened_at": null
    }
  }
}
Dispute lost
{
  "event": {
    "type": "TransactionDisputeLostEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF",
      "reason": "Chargeback by customer",
      "status": "lost",
      "opened_at": "2018-01-01T10:00:00+0000",
      "resolved_at": "2018-01-05T10:00:00+0000",
      "reopened_at": null
    }
  }
}
Dispute won
{
  "event": {
    "type": "TransactionDisputeWonEvent",
    "time": "2017-06-20T09:32:58+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF",
      "reason": "Chargeback by customer",
      "status": "won",
      "opened_at": "2018-01-01T10:00:00+0000",
      "resolved_at": "2018-01-05T10:00:00+0000",
      "reopened_at": null
    }
  }
}
Dispute re-opened
{
  "event": {
    "type": "TransactionDisputeReopenedEvent",
    "time": "2017-06-20T09:33:16+0000",
    "data": {
      "transaction_id": "tra_e4814ad1724d1226feaaaad29462",
      "amount": 3000,
      "currency": "CHF",
      "reason": "Chargeback by customer",
      "status": "open",
      "opened_at": "2018-01-01T10:00:00+0000",
      "resolved_at": "2018-01-05T10:00:00+0000",
      "reopened_at": "2018-01-08T10:00:00+0000"
    }
  }
}

KYC Profiles

Kyc Profile Updated
{
  "type": "KycProfileUpdatedEvent",
  "time": "2018-11-21T12:53:06+0000",
  "data": {
    "merchant_id": 1,
    "status": "approved|rejected|information_missing",
    "requirements": [
      {
        "type": "terms_of_service|legal_information|proof_of_identity|proof_of_address|bank_statement|owner_declaration|declaration_of_beneficial_ownership|proof_of_business_registration",
        "status": "accepted|rejected",
        "comment": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Quos, suscipit."
      },
      ...
    ]
  }
}