IBAN to Wallet - Completed Webhook

Overview

The ibanToWallet.completed webhook fires when inbound funds have cleared through the banking network and the destination wallet balance has been credited.

• Event Name: ibanToWallet.completed
• 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
id	integer	Unique payment transaction ID.
amount	string	Settled amount (e.g. "500.00").
reference	string	Unique order tracking reference.
state	string	Current lifecycle state ("completed").
currency	string	3-letter ISO currency code.
type	string	Transaction type ("iban_to_wallet").
walletId	integer	Credited wallet identifier.
bankingPartner	string	Banking rail partner (e.g. "ClearBank").
receivingAccount	string	Virtual IBAN receiving the deposit.
createdDate	string	Timestamp when deposit was initialized.
completedDate	string	Timestamp when funds settled and wallet credited.
companyId	string	Platform company identifier.
account	object	Linked account details.

Example Payload

{
  "id": 10001,
  "amount": "500.00",
  "reference": "REF-IBAN-001",
  "state": "completed",
  "currency": "EUR",
  "type": "iban_to_wallet",
  "walletId": 2001,
  "bankingPartner": "ClearBank",
  "receivingAccount": "GB29NWBK60161331926819",
  "createdDate": "2024-01-15T10:30:00Z",
  "completedDate": "2024-01-15T10:31:00Z",
  "companyId": "comp-123",
  "account": {
    "id": 501,
    "accountNumber": "12345678",
    "bankName": "Barclays",
    "currency": "EUR",
    "status": "active"
  }
}

---

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 ibanToWallet.completed
    if (event.state === 'completed') {
      console.log(`Processing IBAN to Wallet - Completed Webhook: 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: