Webhooks

Subscribe to real-time event notifications for transfers, customers, and recipient status changes.

Overview

AxisFI uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like bank transfers or KYC identity verification, allowing you to trigger backend actions without constant API polling.

Security & Signature Verification

To ensure that a request is genuinely sent by AxisFI, each webhook includes an X-Webhook-Signature in the header.

Best Practice: We strongly recommend verifying the HMAC-SHA256 signature using your account’s Webhook Secret before processing any data.

Event Types

Transfers

Stay updated on the lifecycle of individual or batch transfers.

Event	Description
`transfer.completed`	Triggered when the transfer is successfully completed and funds reach the destination.
`transfer.failed`	Triggered if a transfer is rejected due to insufficient funds or compliance issues.

Payload examples The data object is the same as the response body of Transfer endpoint (POST /api/transfer/create). See example below.

{
  "transaction_type": "transfer",
  "transaction_id": "txn_e7f5c7fb52df499e90b59e5f57448eca",
  "partner_transaction_id": "INV_LOGI_2026_001",
  "source": {
    "currency": "USDT",
    "network": "ETH",
    "amount": 5000.00
  },
  "target": {
    "currency": "USD",
    "network": null,
    "amount": 4985.50
  },
  "status": "Succeeded",
  "customer_id": null,
  "recipient_id": null,
  "exchange_rate": 0.999,
  "fee": 9.50,
  "purpose_code": "SERVICES_PAYMENT",
  "notes": "Q1 2026 Warehousing and Fulfillment Service Fees",
  "created_at": "2026-04-02T11:18:03Z",
  "audit_at": "2026-04-02T11:20:00Z",
  "completed_at": "2026-04-02T11:30:00Z",
  "customer": {
    "customer_id": "cus_e2ddee0e7d45490995b4cba6712c6833",
    "partner_customer_id": "AXIS_USER_001",
    "status": "Succeeded",
    "created_at": "2026-01-10T08:00:00Z",
    "business_details": {
      "business_name": "xxx Solutions LLC",
      "business_name_english": "xxx Solutions LLC",
      "business_type": "Limited Liability Company",
      "website": "https://xxxx.com",
      "business_identifier_type": "Business Registration",
      "business_identifier_number": "12-3456789",
      "business_identifier_country_code": "US",
      "business_identifier_start_date": "2020-05-12T00:00:00Z",
      "business_identifier_expiry_date": "2040-05-11T00:00:00Z",
      "business_identifier_document_list": [
        "doc_7bf2b61dc5b24295bd37e548af764e03"
      ]
    },
    "account_usage": {
      "operating_country": "US",
      "goods_service_description": "Financial Services",
      "industry_category_code": "5311",
      "account_usage_product_reference": "Financial Services",
      "estimated_monthly_revenue_currency": "USD",
      "estimated_monthly_revenue_amount": 50000
    },
    "registration_address": {
      "registration_address_line1": "1209 Orange Street",
      "registration_address_city": "Wilmington",
      "registration_address_state": "DE",
      "registration_address_postcode": "19801",
      "registration_address_country_code": "US"
    },
    "primary_contact": {
      "contact_phone": "+12025550178",
      "contact_email": "derek@gmail.test"
    },
    "business_person_list": [
      {
        "basic_info": {
          "first_name": "James",
          "first_name_english": "James",
          "last_name": "Miller",
          "last_name_english": "Miller",
          "birth_date": "1988-03-22T00:00:00Z",
          "nationality": "US",
          "role_type": "CEO",
          "contact_phone": "+12025550178",
          "contact_email": "derek@gmail.test"
        },
        "residential_address": {
          "residential_address_line1": "742 Evergreen Terrace",
          "residential_address_city": "Springfield",
          "residential_address_postcode": "62704",
          "residential_address_country_code": "US",
          "residential_address_state": "IL"
        },
        "identification": {
          "id_type": "National ID",
          "id_number": "919998876655",
          "id_issuing_country_code": "US",
          "id_expiration_date": "2032-05-15T00:00:00Z",
          "id_issue_date": "2022-05-15T00:00:00Z",
          "id_document_front_file_id": "doc_7bf2b61dc5b24295bd37e548af764e04",
          "id_document_back_file_id": "doc_7bf2b61dc5b24295bd37e548af764e05"
        }
      }
    ]
  },
  "recipient": {
    "recipient_id": "rcp_ebb26e5bf5d744fdbd7676c023bb84bd",
    "partner_recipient_id": "VENDOR_LOGI_001",
    "status": "Succeeded",
    "name": "xxxx Solutions Inc",
    "type": "enterprise",
    "country_code": "US",
    "website": "https://globallogistics.test",
    "created_at": "2026-03-20T09:15:00Z",
    "address_info": {
      "address_line_1": "456 Commerce Way",
      "address_line_2": "Suite 200",
      "city": "Los Angeles",
      "state": "CA",
      "post_code": "90001"
    },
    "payment_details": {
      "bank_name": "JPMorgan Chase",
      "network": "SWIFT",
      "payment_method": "INTERNATIONAL_WIRE",
      "account_name": "xxxx Solutions Inc",
      "account_number": "123456789012",
      "swift_code": "CHASUS33",
      "account_currency": "USD",
      "country_code": "US",
      "local_bank_code": "021000021"
    },
    "file_id_list": [
      "doc_7bf2b61dc5b24295bd37e548af764e06"
    ]
  },
  "file_id_list": [
    "doc_7bf2b61dc5b24295bd37e548af764e07"
  ]
}

Deposit

Triggered when external funds are detected entering your wallet address

Event	Description
`deposit.completed`	Triggered when the deposit is confirmed and added to your available balance.
`deposit.failed`	Triggered if a deposit is flagged or fails to settle.

Payload examples The data object is the same as the response body of Create Deposit. See example below.

{
  "transaction_type": "deposit",
  "partner_transaction_id": "3922F79e2EA7e551dF44BE81115",
  "network": "ETH",
  "account_currency": "USDT",
  "amount": 99.99,
  "transaction_id": "txn_ca72384ab1ce4ddda4d95bb090f30350",
  "source_wallet_address": "0x0A4EBD7Ad3922F79e2EA7e551dF44BE81115eAE3",
  "target_wallet_address": "0xdAcA9A62Cf0326F3b0DC010Df78f7F10B6b71c32",
  "status": "completed",
  "created_at": "2023-11-07T05:31:56Z",
  "audit_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

Return

Receive notifications when a payout is returned by the beneficiary bank and when the returned funds are credited to your AxisFI balance.

Event	Description
`refund.received`	Triggered when AxisFI receives the payout return and creates the return transaction.
`refund.credited`	Triggered when the returned funds are credited to your available balance.

Payload example The data object is the same as the response body of the Get Return Details endpoint (GET /api/transactions/return/detail).

{
  "status": "completed",
  "currency": "USD",
  "amount": 990.00000000,
  "sender_account_name": AxisFI Solutions LLC,
  "sender_account_number": 123123123123,
  "transaction_type": "return",
  "transaction_id": "txn_7f42a8b6d1194f2893311e0f63f86c81",
  "original_transaction_id": "txn_2e145cb71e7c4eef9781bcdd0ee21e94",
  "refund_order_id": "R202609171020301234567",
  "refund_reason": "Beneficiary bank return",
  "created_at": "2026-09-16 14:00:58",
  "completed_at": "2026-09-16 16:03:06"
}

Customer

Monitor status changes for customer onboarding and identity verification.

Event	Description
`customer.active`	Triggered when a customer’s KYC is approved and the account is activated.
`customer.rejected`	Triggered when a customer’s application is denied.
`customer.suspended`	Triggered if an account is temporarily frozen due to suspicious activity.

Payload examples The data object is the same as the response body of Create Customer. See example below.

{
  "customer_id": "cus_e052d06117a549e2af5820cb3c74dc7f",
  "partner_customer_id": "USER_2026_001",
  "status": "active",
  "created_at": "2026-04-02T08:30:00Z",
  "business_details": {
    "business_name_english": "AxisFI Solutions LLC",
    "website": "https://axisfi.net",
    "business_identifier_type": "Business Registration",
    "business_identifier_number": "12-3456789",
    "business_name": "AxisFI Solutions LLC",
    "business_type": "Limited Liability Company",
    "business_identifier_country_code": "US",
    "business_identifier_start_date": "2020-05-12T00:00:00Z",
    "business_identifier_expiry_date": "2040-05-11T00:00:00Z",
    "business_identifier_file_id_list": [
      "doc_ein_verification_letter_001",
      "doc_articles_of_organization_002"
    ]
  },
  "account_usage": {
    "operating_country": "US",
    "goods_service_description": "Financial Services.",
    "industry_category_code": "5311",
    "account_usage_product_reference": "Financial Services",
    "estimated_monthly_revenue_currency": "USD",
    "estimated_monthly_revenue_amount": 50000
  },
  "registration_address": {
    "registration_address_line1": "1209 Orange Street",
    "registration_address_city": "Wilmington",
    "registration_address_state": "DE",
    "registration_address_postcode": "19801",
    "registration_address_country_code": "US"
  },
  "primary_contact": {
    "contact_phone": "+8613800138000",
    "contact_email": "derek@axisfi.test"
  },
  "business_person_list": [
    {
      "basic_info": {
        "first_name_english": "James",
        "last_name_english": "Miller",
        "birth_date": "1988-03-22T00:00:00Z",
        "nationality": "US",
        "role_type": "CEO",
        "first_name": "James",
        "last_name": "Miller",
        "contact_phone": "+12025550178",
        "contact_email": "james.miller@axisfi.test"
      },
      "residential_address": {
        "residential_address_line1": "742 Evergreen Terrace",
        "residential_address_city": "Springfield",
        "residential_address_state": "IL",
        "residential_address_postcode": "62704",
        "residential_address_country_code": "US"
      },
      "identification": {
        "id_type": "DRIVERS_LICENSE",
        "id_number": "D123456789",
        "id_issuing_country_code": "US",
        "id_expiration_date": "2032-05-15T00:00:00Z",
        "id_issue_date": "2022-05-15T00:00:00Z",
        "id_document_front_file_id": "file_us_dl_front_882",
        "id_document_back_file_id": "file_us_dl_back_882"
      }
    }
  ]
}

Recipient

Monitor the status of your saved recipients.

Event	Description
`recipient.active`	Recipient details are verified and ready for transfers.
`recipient.rejected`	Recipient information is invalid or rejected.
`recipient.suspended`	Recipient has been blacklisted or paused for compliance reasons.

Payload examples The data object is the same as the response body of Create Recipient. See example below.

{
  "name": "Global Logistics Solutions Inc",
  "type": "enterprise",
  "website": "https://globallogistics.test",
  "recipient_id": "rec_9h2v6kLm4pX",
  "partner_recipient_id": "VENDOR_LOGI_001",
  "status": "active",
  "country_code": "US",
  "created_at": "2026-04-02T09:15:00Z",
  "address_info": {
    "address_line_1": "456 Commerce Way",
    "address_line_2": "Suite 200",
    "city": "Los Angeles",
    "state": "CA",
    "post_code": "90001"
  },
  "payment_details": {
    "account_type": "bank",
    "bank_name": "JPMorgan Chase",
    "network": "SWIFT",
    "payment_method": "INTERNATIONAL_WIRE",
    "account_name": "Global Logistics Solutions Inc",
    "account_number": "123456789012",
    "swift_code": "CHASUS33",
    "account_currency": "USD",
    "country_code": "US",
    "local_bank_code": "021000021"
  },
  "file_id_list": [
    "doc_dc988a1d7dd04f78b24f2bbb20c8ebeb"
  ]
}

Overview

Wallets

Balances

Deposit

Quotes

Transfer

Customers

Recipients

Transactions

Files

Webhooks

Webhooks

Webhooks

Overview

Security & Signature Verification

Event Types

Transfers

Deposit

Return

Customer

Recipient

​Webhooks

​Overview

​Security & Signature Verification

​Event Types

​Transfers

​Deposit

​Return

​Customer

​Recipient

Webhooks

Overview

Security & Signature Verification

Event Types

Transfers

Deposit

Return

Customer

Recipient