IBAN to Wallet - Requested Webhook

Overview

The ibanToWallet.requested webhook fires when an inbound deposit arrives at the clearing bank for one of your dedicated virtual IBANs and is recorded as pending settlement into your corporate wallet.

• Event Name: ibanToWallet.requested
• Target State: requested
• 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 internal payment transaction ID.
amount	string	Inbound monetary amount formatted as string (e.g. "500.00").
reference	string	Unique order tracking reference (e.g. "REF-IBAN-001").
state	string	Current lifecycle state ("requested").
currency	string	3-letter ISO currency code (e.g. "EUR").
type	string	Transaction type identifier ("iban_to_wallet").
walletId	integer	Identifier of destination wallet to be credited.
bankingPartner	string	Underlying banking partner (e.g. "ClearBank").
receivingAccount	string	Receiving virtual IBAN / account number.
createdDate	string	ISO 8601 UTC timestamp of deposit detection.
companyId	string	Platform company identifier.
account	object	Associated bank account details.
account.id	integer	Account identifier.
account.accountNumber	string	Remitting or receiving account number.
account.bankName	string	Remitting banking institution name.
account.currency	string	Account currency.
account.status	string	Account status ("active").

Example Payload

{
  "id": 10001,
  "amount": "500.00",
  "reference": "REF-IBAN-001",
  "state": "requested",
  "currency": "EUR",
  "type": "iban_to_wallet",
  "walletId": 2001,
  "bankingPartner": "ClearBank",
  "receivingAccount": "GB29NWBK60161331926819",
  "createdDate": "2024-01-15T10:30: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.requested
    if (event.state === 'requested') {
      console.log(`Processing IBAN to Wallet - Requested 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: