Webhook updates

info

During onboarding merchants can give webhook (callback) endpoint to get updates of user transactions. This is sample webhook response sent to the endpoint.

Note: To use your API key and secret, The merchant or parner has to be onboarded to Lunu.

We send webhooks/callbacks only for transaction events in our system. If the webhook URL is not set before the transaction is completed, the webhook will not be sent. Please note that if the payment site is not publicly available for internet requests, then the HTTP notifications about fund transfers from our processing service will not be able to reach your application.

When a user makes a payment, the Processing Service notifies your application of the fund transfer by making an HTTP request to your application's URL in the following format:

Kindly ensure that you use an HTTPS endpoint with a valid SSL certificate that is trusted by your browser. Otherwise, this can result in missing webhook updates at times.

Example URL

https://your-website.com/api/replenishment-notification

Request callback for the transaction updates

POST <your app URL> X-LUNU-SIGNATURE: d10dba39264529811fd31193d23103b06f9e.../

The processing service sends an HTTP request to your application's URL to notify about the funds transfer when a user completes a payment.

200:OK

{
  "id": "922a2f06-6bec-4eee-a55c-76d549f46262",
  "state": "Completed",
  "payment_method": "bancontact",
  "account_id": "23d93cac-000f-5000-8000-126628f15141",
  "customer_external_id": "8ce43c7a-2143-467c-b8b5-fa748c598ddd",
  "merchant_trx_id": "8ce43c7a-2143-467c-b8b5-fa748c598ddd",
  "cc_code": "ETH",
  "crypto_amount": "1.23938",
  "fiat_code": "EUR",
  "fiat_amount": "2000.00",
  "wallet_address": "0xab0f34d6c159f9c4f82f4d4cd8b49cff89dfcec8",
  "expiry_at": "2022-09-23T14:30:45-03:00",
  "created_at": "2022-09-22T14:30:45-03:00",
  "timestamp": "2022-09-22T14:30:45-03:00"
}

Field	Type	Required	Detials
id	string	yes	payment ID
state	string	yes	Payment status Final status Completed, Cancelled, and Refunded Other definitions Created - Transaction session initiated. Confirmed - The Quote confirmed for the payment initiation. Pending and In progress - waiting for the payment. Blocked - Transaction is blocked due to risk.
payment_method	string	yes	payment method (bancontact, creditCard, iDeal, sofort etc)
account_id	string	yes	F2C account ID
customer_external_id	string	yes	Internal user/account/wallet ID in your system
cc_code	string	yes	payment cryptocurrency
crypto_amount	string	yes	payment amount in cryptocurrency
fiat_code	string	yes	payment fiat
fiat_amount	string	yes	payment amount in fiat
merchant_trx_id	string	yes	Internal transaction ID in your system
transaction_id	string	no	transaction hash from 3rd party service
transaction_explorer	string	no	transaction explorer link
wallet_explorer	string	no
wallet_address	string	no	destination address
expiry_at	string	no	date when payment expires, RFC3339 format
created_at	string	yes	payment creation date, RFC3339 format
timestamp	string	yes	notification timestamp

Authentication of Notification

To ensure the authenticity of a notification, you can authenticate it by verifying the signature of the notification.

The notification signature can be found in the HTTP header "X-LUNU-SIGNATURE".

To authenticate the signature, concatenate the auth token with the request body, and generate the sha256 hash.

Sample PHP authentication

(Simple copy / paste and chaging parms form your system is enough)

$auth_token = 'l.QtEo8ahkNFX4RTpbqp0u4z4GDZq27HzUp6AotJASBx7_DVqmqZMHfM2Cy7JmUjS80boI9eVg';
$request_body = file_get_contents('php://input');
$signature = hash('sha256', $auth_token . $request_body);
$signatureOfRequest = $headers['x-lunu-signature'];
if ($signature === $signatureOfRequest) {
  // Notification genuine
} else {
  // Notification not genuine
}