{"openapi":"3.1.0","info":{"title":"Transaction Webhooks API","description":"API documentation with separate webhooks for every transaction type and status combination. Payment state webhooks are delivered on the PAYMENT_STATUS_CHANGE topic wrapped in an envelope ({ companyId, eventType, createdAt, payload }); the payment details are in payload.\n","version":"1.0.0"},"webhooks":{"ibanToWallet.requested":{"post":{"operationId":"ibanToWallet_requested","tags":["IBAN to Wallet"],"x-atlas-webhook":true,"summary":"Requested","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/IbanToWalletBase"},{"properties":{"state":{"type":"string","enum":["requested"]}}}]}}}]},"examples":{"iban_to_wallet_requested":{"summary":"IBAN to Wallet — funds inbound, awaiting processing","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T10:30:00.000Z","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","account":{"id":501,"accountNumber":"12345678","bankName":"Barclays","currency":"EUR","status":"active"},"companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"ibanToWallet.completed":{"post":{"operationId":"ibanToWallet_completed","tags":["IBAN to Wallet"],"x-atlas-webhook":true,"summary":"Completed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/IbanToWalletBase"},{"properties":{"state":{"type":"string","enum":["completed"]}}}]}}}]},"examples":{"iban_to_wallet_completed":{"summary":"IBAN to Wallet — funds received and settled","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T10:31:00.000Z","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","account":{"id":501,"accountNumber":"12345678","bankName":"Barclays","currency":"EUR","status":"active"},"companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"ibanToWallet.disputed":{"post":{"operationId":"ibanToWallet_disputed","tags":["IBAN to Wallet"],"x-atlas-webhook":true,"summary":"Disputed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/IbanToWalletBase"},{"properties":{"state":{"type":"string","enum":["disputed"]}}}]}}}]},"examples":{"iban_to_wallet_disputed":{"summary":"IBAN to Wallet — transaction flagged as disputed","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T10:30:00.000Z","payload":{"id":10001,"amount":"500.00","reference":"REF-IBAN-001","state":"disputed","currency":"EUR","type":"iban_to_wallet","walletId":2001,"bankingPartner":"ClearBank","receivingAccount":"GB29NWBK60161331926819","createdDate":"2024-01-15T10:30:00Z","companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"ibanToWallet.archived":{"post":{"operationId":"ibanToWallet_archived","tags":["IBAN to Wallet"],"x-atlas-webhook":true,"summary":"Archived","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/IbanToWalletBase"},{"properties":{"state":{"type":"string","enum":["archived"]}}}]}}}]},"examples":{"iban_to_wallet_archived":{"summary":"IBAN to Wallet — transaction archived","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-16T08:00:00.000Z","payload":{"id":10001,"amount":"500.00","reference":"REF-IBAN-001","state":"archived","currency":"EUR","type":"iban_to_wallet","walletId":2001,"bankingPartner":"ClearBank","receivingAccount":"GB29NWBK60161331926819","createdDate":"2024-01-15T10:30:00Z","archivedDate":"2024-01-16T08:00:00Z","archiveReason":"Duplicate transaction","companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"walletToWallet.completed":{"post":{"operationId":"walletToWallet_completed","tags":["Wallet to Wallet"],"x-atlas-webhook":true,"summary":"Completed","description":"Fires for both the credited and debited wallets.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/WalletToWalletBase"},{"properties":{"state":{"type":"string","enum":["completed"]}}}]}}}]},"examples":{"wallet_to_wallet_credit":{"summary":"Wallet to Wallet — credit side of internal transfer","value":{"companyId":456,"eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T11:00:05.000Z","payload":{"id":10002,"amount":250,"reference":"REF-W2W-002","state":"completed","currency":"GBP","type":"wallet_to_wallet","walletId":3001,"transactionType":"credit","toWalletId":3001,"fromWalletId":3002,"createdDate":"2024-01-15T11:00:00Z","completedDate":"2024-01-15T11:00:05Z","companyId":456}}},"wallet_to_wallet_debit":{"summary":"Wallet to Wallet — debit side of internal transfer","value":{"companyId":456,"eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T11:00:05.000Z","payload":{"id":10003,"amount":250,"reference":"REF-W2W-002","state":"completed","currency":"GBP","type":"wallet_to_wallet","walletId":3002,"transactionType":"debit","toWalletId":3001,"fromWalletId":3002,"createdDate":"2024-01-15T11:00:00Z","completedDate":"2024-01-15T11:00:05Z","companyId":456}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"wallet.credit.success":{"post":{"operationId":"wallet_credit_success","tags":["Wallet Credit"],"x-atlas-webhook":true,"summary":"Success","description":"Fires when a VPay (wallet_to_wallet) transfer settles and the receiver wallet is credited. Covers immediate, scheduled, and recurring VPay payments.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletCreditSuccess"},"examples":{"wallet_credit_success":{"summary":"Wallet Credit — VPay funds credited to receiver wallet","value":{"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"}}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"walletToAccount.requested":{"post":{"operationId":"walletToAccount_requested","tags":["Wallet to Account"],"x-atlas-webhook":true,"summary":"Requested","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/WalletToAccountBase"},{"properties":{"state":{"type":"string","enum":["requested"]}}}]}}}]},"examples":{"wallet_to_account_requested":{"summary":"Wallet to Account — outgoing transfer initiated","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T12:00:00.000Z","payload":{"id":10004,"amount":"1000.00","reference":"REF-W2A-003","state":"requested","currency":"USD","type":"wallet_to_account","walletId":4001,"createdDate":"2024-01-15T12:00:00Z","account":{"id":502,"accountNumber":"87654321","bankName":"HSBC","beneficiaryFirstName":"John","beneficiaryLastName":"Smith","beneficiaryEntityType":"individual","currency":"USD","status":"active"},"companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"walletToAccount.completed":{"post":{"operationId":"walletToAccount_completed","tags":["Wallet to Account"],"x-atlas-webhook":true,"summary":"Completed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/WalletToAccountBase"},{"properties":{"state":{"type":"string","enum":["completed"]}}}]}}}]},"examples":{"wallet_to_account_completed":{"summary":"Wallet to Account — transfer settled to beneficiary","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T12:05:00.000Z","payload":{"id":10004,"amount":"1000.00","reference":"REF-W2A-003","state":"completed","currency":"USD","type":"wallet_to_account","walletId":4001,"createdDate":"2024-01-15T12:00:00Z","completedDate":"2024-01-15T12:05:00Z","account":{"id":502,"accountNumber":"87654321","bankName":"HSBC","beneficiaryFirstName":"John","beneficiaryLastName":"Smith","beneficiaryEntityType":"individual","currency":"USD","status":"active"},"companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"walletToAccount.archived":{"post":{"operationId":"walletToAccount_archived","tags":["Wallet to Account"],"x-atlas-webhook":true,"summary":"Archived","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/WalletToAccountBase"},{"properties":{"state":{"type":"string","enum":["archived"]}}}]}}}]},"examples":{"wallet_to_account_archived":{"summary":"Wallet to Account — transfer archived (cancelled/failed)","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T12:10:00.000Z","payload":{"id":10004,"amount":"1000.00","reference":"REF-W2A-003","state":"archived","currency":"USD","type":"wallet_to_account","walletId":4001,"createdDate":"2024-01-15T12:00:00Z","archivedDate":"2024-01-15T12:10:00Z","archiveReason":"Beneficiary account invalid","account":{"id":502,"accountNumber":"87654321","bankName":"HSBC","currency":"USD","status":"active"},"companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"walletToAccount.refunded":{"post":{"operationId":"walletToAccount_refunded","tags":["Wallet to Account"],"x-atlas-webhook":true,"summary":"Refunded","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaymentStatusChangeEnvelope"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/WalletToAccountBase"},{"properties":{"state":{"type":"string","enum":["refunded"]}}}]}}}]},"examples":{"wallet_to_account_refunded":{"summary":"Wallet to Account — funds returned after failed transfer","value":{"companyId":"123","eventType":"PAYMENT_STATUS_CHANGE","createdAt":"2024-01-15T12:05:00.000Z","payload":{"id":10004,"amount":"1000.00","reference":"REF-W2A-003","state":"refunded","currency":"USD","type":"wallet_to_account","walletId":4001,"createdDate":"2024-01-15T12:00:00Z","completedDate":"2024-01-15T12:05:00Z","account":{"id":502,"accountNumber":"87654321","bankName":"HSBC","beneficiaryFirstName":"John","beneficiaryLastName":"Smith","beneficiaryEntityType":"individual","currency":"USD","status":"active"},"companyId":"123"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}},"wallet.payment.refund":{"post":{"operationId":"wallet_payment_refund","tags":["Wallet Refund"],"x-atlas-webhook":true,"summary":"Refund","description":"Fires when a wallet-to-account payout is refunded back to the wallet. Sent alongside walletToAccount.refunded.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletPaymentRefund"},"examples":{"wallet_payment_refund":{"summary":"Wallet Refund — payout amount returned to wallet","value":{"companyId":"123","eventType":"wallet.payment.refund","createdAt":"2024-01-15T12:05:00.000Z","event":{"walletId":"4001","reference":"REF-W2A-003","currency":"USD","amount":1000,"refundedOn":"2024-01-15T12:05:00.000Z"}}}}}}},"responses":{"200":{"description":"Webhook received"}}}}},"components":{"schemas":{"PaymentStatusChangeEnvelope":{"type":"object","required":["companyId","eventType","createdAt","payload"],"properties":{"companyId":{"type":["string","integer"],"description":"Company the payment belongs to; same value as payload.companyId (integer for wallet_to_wallet, string otherwise). For a sub-account payment, the parent company's copy carries the sub-account's companyId.\n","example":"123"},"eventType":{"type":"string","enum":["PAYMENT_STATUS_CHANGE"],"description":"Webhook topic"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the webhook event was created"},"payload":{"type":"object","description":"Payment details at the time of the state change"}}},"IbanToWalletBase":{"type":"object","required":["id","amount","reference","state","currency","type","walletId","createdDate"],"properties":{"id":{"type":"integer"},"amount":{"type":"string"},"reference":{"type":"string"},"state":{"type":"string"},"currency":{"type":"string"},"type":{"type":"string","enum":["iban_to_wallet"]},"subState":{"type":"string","nullable":true},"initiationSource":{"type":"string","nullable":true},"paymentId":{"type":"string","nullable":true},"clientReference":{"type":"string","nullable":true},"account":{"$ref":"#/components/schemas/AccountDetails"},"walletId":{"type":"integer"},"bankingPartner":{"type":"string"},"receivingAccount":{"type":"string"},"createdDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time","nullable":true},"archivedDate":{"type":"string","format":"date-time","nullable":true},"archiveReason":{"type":"string","nullable":true},"companyId":{"type":"string"}}},"WalletToWalletBase":{"type":"object","required":["id","amount","reference","state","currency","type","walletId","createdDate"],"properties":{"id":{"type":"integer"},"amount":{"type":"number"},"reference":{"type":"string"},"state":{"type":"string"},"currency":{"type":"string"},"type":{"type":"string","enum":["wallet_to_wallet"]},"clientReference":{"type":"string","nullable":true},"walletId":{"type":"integer"},"transactionType":{"type":"string","enum":["credit","debit"]},"toWalletId":{"type":"integer"},"fromWalletId":{"type":"integer"},"createdDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time","nullable":true},"archivedDate":{"type":"string","format":"date-time","nullable":true},"archiveReason":{"type":"string","nullable":true},"companyId":{"type":"integer"},"externalUniqueRef":{"type":"string","nullable":true}}},"WalletCreditSuccess":{"type":"object","required":["companyId","eventType","createdAt","event"],"properties":{"companyId":{"type":"string","description":"Receiver company ID","example":"200"},"eventType":{"type":"string","enum":["wallet.credit.success"],"description":"Webhook event type","example":"wallet.credit.success"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the webhook event was created"},"event":{"$ref":"#/components/schemas/WalletCreditEvent"}}},"WalletToAccountBase":{"type":"object","required":["id","amount","reference","state","currency","type","walletId","createdDate"],"properties":{"id":{"type":"integer"},"amount":{"type":"string"},"reference":{"type":"string"},"state":{"type":"string"},"currency":{"type":"string"},"type":{"type":"string","enum":["wallet_to_account"]},"subState":{"type":"string","nullable":true},"initiationSource":{"type":"string","nullable":true},"paymentId":{"type":"string","nullable":true},"clientReference":{"type":"string","nullable":true},"account":{"$ref":"#/components/schemas/AccountDetails"},"walletId":{"type":"integer"},"createdDate":{"type":"string","format":"date-time"},"completedDate":{"type":"string","format":"date-time","nullable":true},"archivedDate":{"type":"string","format":"date-time","nullable":true},"archiveReason":{"type":"string","nullable":true},"externalUniqueRef":{"type":"string","nullable":true},"companyId":{"type":"string"}}},"WalletPaymentRefund":{"type":"object","required":["companyId","eventType","createdAt","event"],"properties":{"companyId":{"type":"string","description":"Company that owns the wallet","example":"123"},"eventType":{"type":"string","enum":["wallet.payment.refund"],"description":"Webhook event type","example":"wallet.payment.refund"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the webhook event was created"},"event":{"$ref":"#/components/schemas/WalletRefundEvent"}}},"AccountDetails":{"type":"object","properties":{"id":{"type":"integer"},"accountNumber":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"beneficiaryAddress":{"type":"string","nullable":true},"beneficiaryCity":{"type":"string","nullable":true},"beneficiaryCompanyName":{"type":"string","nullable":true},"beneficiaryCountryCode":{"type":"string","nullable":true},"beneficiaryEntityType":{"type":"string","enum":["individual","company"],"nullable":true},"beneficiaryPostcode":{"type":"string","nullable":true},"beneficiaryEmail":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"beneficiaryFirstName":{"type":"string","nullable":true},"beneficiaryLastName":{"type":"string","nullable":true},"nationalId":{"type":"string","nullable":true},"currency":{"type":"string"},"clientReference":{"type":"string","nullable":true},"status":{"type":"string"}}},"WalletCreditEvent":{"type":"object","required":["reference","method","status","createdDate","completedDate","walletId","clientReference","amount","currency","sender"],"properties":{"reference":{"type":"string","description":"Transfer/payment reference","example":"TO-01012025-ABCD"},"method":{"type":"string","description":"Payment method","enum":["VPay"],"example":"VPay"},"status":{"type":"string","description":"Transfer status at credit time","example":"completed"},"createdDate":{"type":"string","format":"date-time","description":"When the transfer was created"},"completedDate":{"type":"string","format":"date-time","description":"When the transfer completed and the wallet was credited"},"walletId":{"type":"string","description":"Receiver wallet ID that was credited","example":"437747"},"clientReference":{"type":"string","description":"Client-supplied payment reference, if any","example":"invoice-42"},"amount":{"type":"number","description":"Net amount credited to the receiver wallet","example":5000},"currency":{"type":"string","description":"Currency of the credited amount","example":"GBP"},"sender":{"$ref":"#/components/schemas/WalletCreditSender"}}},"WalletRefundEvent":{"type":"object","required":["walletId","reference","currency","amount","refundedOn"],"properties":{"walletId":{"type":"string","description":"Wallet the refund was credited to","example":"4001"},"reference":{"type":"string","description":"Reference of the refunded payment","example":"REF-W2A-003"},"currency":{"type":"string","description":"Currency of the refunded amount","example":"USD"},"amount":{"type":"number","description":"Refunded amount","example":1000},"refundedOn":{"type":"string","format":"date-time","description":"When the refund was recorded"}}},"WalletCreditSender":{"type":"object","required":["reference","name"],"properties":{"reference":{"type":"string","description":"Sender company reference (e.g. VU-00441)","example":"VU-00441"},"name":{"type":"string","description":"Sender company name","example":"Brisk Pay Ltd"}}}}},"security":[],"paths":{}}