Wallet Credit - Success (VPay)

Overview

The wallet.credit.success webhook fires when a VPay (inter-company wallet) transfer settles into the recipient company's wallet. It includes sender corporate metadata and client reference information.

• Event Name: wallet.credit.success
• Target State: completed
• HTTP Method: POST (Sent from Atlas to your configured webhook listener URL)

---

Webhook Headers

Header	Description
Content-Type	application/json
X-Atlas-Signature	HMAC SHA-256 signature and timestamp for message authentication
X-Atlas-Delivery-Id	Unique UUID tracking this webhook delivery attempt

---

Payload Schema

Payload Fields

Field	Type	Description
companyId	string	Receiver company ID (e.g. "200").
eventType	string	Event type identifier ("wallet.credit.success").
createdAt	string	Timestamp when event was dispatched.
event	object	Core payment settlement payload.
event.reference	string	Transfer reference (e.g. "TO-01012025-ABCD").
event.method	string	Payment method ("VPay").
event.status	string	Transfer status at credit time ("completed").
event.createdDate	string	When transfer was requested.
event.completedDate	string	When funds were credited.
event.walletId	string	Receiver wallet ID that received funds.
event.clientReference	string	Client-supplied memo or invoice reference.
event.amount	number	Net amount credited (e.g. 5000).
event.currency	string	Currency code (e.g. "GBP").
event.sender	object	Sender company metadata.
event.sender.reference	string	Sender business reference (e.g. "VU-00441").
event.sender.name	string	Sender business registered name (e.g. "Brisk Pay Ltd").

Example Payload

{
  "companyId": "200",
  "eventType": "wallet.credit.success",
  "createdAt": "2025-01-01T10:01:00.000Z",
  "event": {
    "reference": "TO-01012025-ABCD",
    "method": "VPay",
    "status": "completed",
    "createdDate": "2025-01-01T10:00:00.000Z",
    "completedDate": "2025-01-01T10:01:00.000Z",
    "walletId": "437747",
    "clientReference": "invoice-42",
    "amount": 5000,
    "currency": "GBP",
    "sender": {
      "reference": "VU-00441",
      "name": "Brisk Pay Ltd"
    }
  }
}

---

Expected Response

Your endpoint must respond with an HTTP 200 OK status code within 5 seconds to acknowledge delivery:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}

---

Handling Example

// Express.js Webhook Handler
app.post('/api/webhooks/atlas', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-atlas-signature'];

  try {
    // 1. Verify webhook signature
    verifySignature(req.body, signature, process.env.ATLAS_WEBHOOK_SECRET);

    const event = JSON.parse(req.body.toString());

    // 2. Handle wallet.credit.success
    if (event.state === 'completed') {
      console.log(`Processing Wallet Credit - Success (VPay): Reference ${event.reference}, Amount: ${event.amount} ${event.currency}`);
      // Update your internal order or ledger state
    }

    // 3. Acknowledge receipt
    res.status(200).json({ status: 'received' });
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.status(400).send('Invalid signature');
  }
});

---

Interactive Payload Schema & Example

Review the full JSON schema and test response handling: