{"openapi":"3.1.0","info":{"title":"FX Status Change Webhooks API","description":"API documentation with separate webhooks for every FX order transactionState.","version":"1.0.0"},"webhooks":{"fxStatusChange.inward_remittance_pending":{"post":{"operationId":"fxStatusChange_inward_remittance_pending","tags":["FX Status Change"],"x-atlas-webhook":true,"summary":"Inward remittance pending","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeWebhook"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeBase"},{"properties":{"transactionState":{"type":"string","enum":["inward_remittance_pending"]}}}]}}}]},"examples":{"fx_inward_remittance_pending":{"summary":"FX Status Change — order placed, deposit not yet received","value":{"companyId":"12345","eventType":"FX_STATUS_CHANGE","createdAt":"2026-06-30T15:39:24.912Z","payload":{"companyId":"12345","id":"629464","reference":"EN-30062026-F2E0C","amountFrom":"575.21","amountTo":"1065463.00","rate":"1852.306107534273700","transactionState":"inward_remittance_pending","status":"recipient_added","clientReference":"John Doe","currencyFrom":"GBP","currencyTo":"NGN","createdDate":null,"completedDate":null,"archivedDate":null,"archiveReason":null,"ccyReturned":null,"amountReturned":null,"archiveComment":null}}}}}}},"responses":{"200":{"description":"Acknowledged successfully."}}}},"fxStatusChange.inward_remittance_confirmed":{"post":{"operationId":"fxStatusChange_inward_remittance_confirmed","tags":["FX Status Change"],"x-atlas-webhook":true,"summary":"Inward remittance confirmed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeWebhook"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeBase"},{"properties":{"transactionState":{"type":"string","enum":["inward_remittance_confirmed"]}}}]}}}]},"examples":{"fx_inward_remittance_confirmed":{"summary":"FX Status Change — client's deposit recorded","value":{"companyId":"12345","eventType":"FX_STATUS_CHANGE","createdAt":"2026-06-30T15:39:25.031Z","payload":{"companyId":"12345","id":"629464","reference":"EN-30062026-F2E0C","amountFrom":"575.21","amountTo":"1065463.00","rate":"1852.306107534273700","transactionState":"inward_remittance_confirmed","status":"deposit_recorded","clientReference":"John Doe","currencyFrom":"GBP","currencyTo":"NGN","createdDate":"2026-06-30T15:39:24.691Z","completedDate":null,"archivedDate":null,"archiveReason":null,"ccyReturned":null,"amountReturned":null,"archiveComment":null}}}}}}},"responses":{"200":{"description":"Acknowledged successfully."}}}},"fxStatusChange.inward_remittance_disputed":{"post":{"operationId":"fxStatusChange_inward_remittance_disputed","tags":["FX Status Change"],"x-atlas-webhook":true,"summary":"Inward remittance disputed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeWebhook"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeBase"},{"properties":{"transactionState":{"type":"string","enum":["inward_remittance_disputed"]}}}]}}}]},"examples":{"fx_inward_remittance_disputed":{"summary":"FX Status Change — inbound leg flagged as disputed","value":{"companyId":"12345","eventType":"FX_STATUS_CHANGE","createdAt":"2026-06-30T16:02:11.457Z","payload":{"companyId":"12345","id":"629464","reference":"EN-30062026-F2E0C","amountFrom":"575.21","amountTo":"1065463.00","rate":"1852.306107534273700","transactionState":"inward_remittance_disputed","status":"deposit_recorded","clientReference":"John Doe","currencyFrom":"GBP","currencyTo":"NGN","createdDate":"2026-06-30T15:39:24.691Z","completedDate":null,"archivedDate":null,"archiveReason":null,"ccyReturned":null,"amountReturned":null,"archiveComment":null}}}}}}},"responses":{"200":{"description":"Acknowledged successfully."}}}},"fxStatusChange.outward_remittance_complete":{"post":{"operationId":"fxStatusChange_outward_remittance_complete","tags":["FX Status Change"],"x-atlas-webhook":true,"summary":"Outward remittance complete","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeWebhook"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeBase"},{"properties":{"transactionState":{"type":"string","enum":["outward_remittance_complete"]}}}]}}}]},"examples":{"fx_outward_remittance_complete":{"summary":"FX Status Change — payout to beneficiary settled","value":{"companyId":"12345","eventType":"FX_STATUS_CHANGE","createdAt":"2026-06-30T15:38:51.420Z","payload":{"companyId":"12345","id":"629458","reference":"EN-30062026-F2E06","amountFrom":"288.55","amountTo":"534691.27","rate":"1853.046081135665600","transactionState":"outward_remittance_complete","status":"deposit_recorded","clientReference":"Jane Smith","currencyFrom":"GBP","currencyTo":"NGN","createdDate":"2026-06-30T15:34:50.000Z","completedDate":"2026-06-30T15:38:51.000Z","archivedDate":null,"archiveReason":null,"ccyReturned":null,"amountReturned":null,"archiveComment":null}}}}}}},"responses":{"200":{"description":"Acknowledged successfully."}}}},"fxStatusChange.outward_remittance_disputed":{"post":{"operationId":"fxStatusChange_outward_remittance_disputed","tags":["FX Status Change"],"x-atlas-webhook":true,"summary":"Outward remittance disputed","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeWebhook"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeBase"},{"properties":{"transactionState":{"type":"string","enum":["outward_remittance_disputed"]}}}]}}}]},"examples":{"fx_outward_remittance_disputed":{"summary":"FX Status Change — payout leg flagged as disputed","value":{"companyId":"12345","eventType":"FX_STATUS_CHANGE","createdAt":"2026-06-30T15:45:03.118Z","payload":{"companyId":"12345","id":"629458","reference":"EN-30062026-F2E06","amountFrom":"288.55","amountTo":"534691.27","rate":"1853.046081135665600","transactionState":"outward_remittance_disputed","status":"deposit_recorded","clientReference":"Jane Smith","currencyFrom":"GBP","currencyTo":"NGN","createdDate":"2026-06-30T15:34:50.000Z","completedDate":null,"archivedDate":null,"archiveReason":null,"ccyReturned":null,"amountReturned":null,"archiveComment":null}}}}}}},"responses":{"200":{"description":"Acknowledged successfully."}}}},"fxStatusChange.refunded":{"post":{"operationId":"fxStatusChange_refunded","tags":["FX Status Change"],"x-atlas-webhook":true,"summary":"Refunded","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeWebhook"},{"properties":{"payload":{"allOf":[{"$ref":"#/components/schemas/FxStatusChangeBase"},{"properties":{"transactionState":{"type":"string","enum":["refunded"]}}}]}}}]},"examples":{"fx_refunded":{"summary":"FX Status Change — funds returned to sender","value":{"companyId":"12345","eventType":"FX_STATUS_CHANGE","createdAt":"2026-05-28T12:14:28.950Z","payload":{"companyId":"12345","id":"501173","reference":"EN-27022026-D67668","amountFrom":"55.65","amountTo":"103000.00","rate":"1850.698566585800000","transactionState":"refunded","status":"deposit_recorded","clientReference":"topupJohnDoe","currencyFrom":"GBP","currencyTo":"NGN","createdDate":"2026-02-27T08:54:44.000Z","completedDate":"2026-02-27T09:00:03.000Z","archivedDate":"2026-05-28T12:14:28.801Z","archiveReason":"Returned / Beneficiary's Request","ccyReturned":"GBP","amountReturned":"55.65","archiveComment":null}}}}}}},"responses":{"200":{"description":"Acknowledged successfully."}}}}},"components":{"schemas":{"FxStatusChangeWebhook":{"type":"object","required":["companyId","eventType","createdAt","payload"],"properties":{"companyId":{"type":"string","description":"Verto company ID the order belongs to."},"eventType":{"type":"string","enum":["FX_STATUS_CHANGE"]},"createdAt":{"type":"string","format":"date-time","description":"When the event was emitted."},"payload":{"$ref":"#/components/schemas/FxStatusChangeBase"}}},"FxStatusChangeBase":{"type":"object","required":["companyId","id","reference","amountFrom","amountTo","rate","transactionState","status","currencyFrom","currencyTo"],"properties":{"companyId":{"type":"string","description":"Verto company ID (same as the envelope's companyId)."},"id":{"type":"string"},"reference":{"type":"string"},"amountFrom":{"type":"string","description":"Source amount (numeric string)."},"amountTo":{"type":"string","description":"Destination amount (numeric string)."},"rate":{"type":"string","description":"Exchange rate applied (numeric string)."},"transactionState":{"type":"string","enum":["inward_remittance_pending","inward_remittance_confirmed","inward_remittance_disputed","outward_remittance_complete","outward_remittance_disputed","refunded"]},"status":{"type":"string","enum":["order_placed","recipient_added","deposit_recorded","archived"]},"clientReference":{"type":"string","nullable":true},"currencyFrom":{"type":"string"},"currencyTo":{"type":"string"},"createdDate":{"type":"string","format":"date-time","nullable":true},"completedDate":{"type":"string","format":"date-time","nullable":true},"archivedDate":{"type":"string","format":"date-time","nullable":true,"description":"Set when status=archived."},"archiveReason":{"type":"string","nullable":true,"description":"Set when status=archived or transactionState=refunded."},"ccyReturned":{"type":"string","nullable":true,"description":"Set when funds were returned to sender."},"amountReturned":{"type":"string","nullable":true,"description":"Set when funds were returned to sender."},"archiveComment":{"type":"string","nullable":true}}}}},"paths":{}}