Webhooks

When a payment is completed — whether successful or failed — xMoney can notify you through multiple channels. This ensures that both you and the customer receive immediate feedback, and that your systems stay in sync even if there are browser or network issues.

Notification URLs

To properly handle payment results, you need to provide:

1. Server-to-Server Notification URL (Webhook/IPN)

   • An endpoint on your server to receive Instant Payment Notifications (IPNs).
   • This notification occurs after the payment is processed, crucial if the customer's browser fails or closes before returning to your site.
   • Configuration:
     • Access your Merchant Dashboard.
     • Navigate to Sites -> SiteId -> Payment Page.
     • Enter your URL and enable the "Use Server-to-server notification URL" checkbox.
     

2. Payment Page Back URL (backUrl)

   • A page on your site to which the customer is redirected immediately after the payment attempt — whether successful or failed.
   • This helps you show the customer a confirmation or error message in real-time.

Notification flow overview

1. Browser Redirect: Immediately after the customer completes or cancels payment, xMoney redirects their browser to your Payment Page Back URL.
2. Server-to-Server Notification (IPN/Webhook): xMoney also sends a server-to-server notification to the Notification URL you provided. This message might arrive with a delay if retries are needed (e.g., if your server is temporarily unreachable).

Acknowledging the Webhook (IPN)

When you receive the Webhook (IPN), your server must respond with:

HTTP/1.1 200 OK
Content-Type: text/plain

OK

To confirm successful processing, your server must respond with HTTP/1.1 200 OK and the body content OK. Failure to do so will trigger xMoney to retry sending the IPN on a schedule of 1 minute, 5 minutes, 1 hour, and 24 hours, after which retries will cease.

Payload decryption

Both notification URLs receive payment details via POST. The payload is identical for both URLs and includes the following parameters: result, opensslResult, and signature.

Decryption Steps:

1. String Split: Divide the encrypted string at the first comma (,).
   • Left: Initialization Vector (IV).
   • Right: Encrypted data.
2. Base64 Decoding: Decode the IV and encrypted data using Base64.
3. OpenSSL Decryption: Use the OpenSSL aes-256-cbc algorithm, your API key, and the decoded IV.

Example decryption code

import crypto from 'crypto';

/**
 * Decrypts an encrypted payload received via POST from xMoney notification URLs.
 *
 * @param {string} encryptedPayload The encrypted payload string.
 * @param {string} secretKey The secret key (your xMoney API key).
 *
 * @returns {object} The decrypted JSON object from the payload.
 */
function decryptNotificationPayload(encryptedPayload, secretKey = 'YOUR API KEY HERE') {
    const encryptedParts = encryptedPayload.split(',', 2);
    const iv = Buffer.from(encryptedParts[0], 'base64');
    const encryptedData = Buffer.from(encryptedParts[1], 'base64');

    const decipher = crypto.createDecipheriv('aes-256-cbc', secretKey, iv);
    let decryptedPayload = Buffer.concat([
        decipher.update(encryptedData),
        decipher.final(),
    ]).toString('utf8');

    return JSON.parse(decryptedPayload);
}

Payload data

Both the Payment Page Back URL and the Server-to-Server Notification URL receive the same payload data.

The JSON structure typically includes:

{
  externalOrderId,
  identifier,
  transactionStatus,
  customerId,
  orderId,
  cardId,
  transactionId,
  transactionMethod,
  timestamp,
  amount,
  currency,
  customData, // may be a string or object
}

Examples

{
  "transactionStatus": "complete-ok",
  "orderId": 1234,
  "externalOrderId": "external-order-id",
  "transactionId": 1234,
  "transactionMethod": "card",
  "customerId": 1,
  "identifier": "identifier",
  "amount": 5.55,
  "currency": "EUR",
  "customData": {
    "key_1": "value_1",
    "key_2": "value_2"
  },
  "timestamp": 1600874501,
  "cardId": 3
}

Transaction Statuses

The transactionStatus key in the response payload indicates the current state of the transaction. Use these statuses to update your order management system, trigger notifications, or display relevant messages.

Conclusion

By setting up both the Payment Page Back URL and the Server-to-Server Notification URL, you ensure reliable, real-time visibility into payment outcomes. Whether the customer's browser returns successfully or not, xMoney's server-to-server notification system will keep your backend updated with the final transaction status.

Next Steps:

• Implement and test the decryption logic for opensslResult in your environment.
• Confirm that your notification endpoints respond with 200 OK to avoid repeated IPN attempts.
• Monitor your logs and transaction dashboard to verify successful communication.

With proper webhook and response handling in place, you'll be equipped to provide a seamless, transparent experience for both your customers and your internal order management.