> ## Documentation Index > Fetch the complete documentation index at: https://manual.kotanipay.com/llms.txt > Use this file to discover all available pages before exploring further. # Crypto Bridge Provider Settlement Webhook > Receives settlement status updates from settlement provider. Requires signature validation. Statuses: SETTLING, COMPLETED, FAILED. For FAILED status, initiates refund process using configured refund method. ## OpenAPI ````yaml POST /api/v3/deposit/crypto-bridge/webhook/provider/settlement openapi: 3.0.0 info: title: KOTANI PAY API PLATFORM description: '' version: '3.0' contact: {} servers: - url: https://preview.kotanipay.com security: [] tags: [] paths: /api/v3/deposit/crypto-bridge/webhook/provider/settlement: post: tags: - CRYPTO BRIDGE DEPOSIT WEBHOOKS summary: Webhook endpoint for provider settlement status updates description: >- Receives settlement status updates from settlement provider. Requires signature validation. Statuses: SETTLING, COMPLETED, FAILED. For FAILED status, initiates refund process using configured refund method. operationId: >- DepositCryptoBridgeWebhookController_handleProviderSettlementWebhook_api/v3 parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProviderSettlementWebhookDto' responses: '200': description: '' content: application/json: schema: properties: success: type: boolean example: true message: type: string example: Webhook received and processed. data: $ref: 016b6ef7-0e0e-46fc-bf7b-4370c7e58800 type: object '404': description: '' content: application/json: schema: properties: success: type: boolean example: false message: type: string example: Transaction not found data: type: object example: {} components: schemas: ProviderSettlementWebhookDto: type: object properties: webhook_type: type: string description: Webhook type identifier example: SETTLEMENT_STATUS_UPDATE provider_reference_id: type: string description: Provider reference ID example: PROVIDER-TXN-20241122-001 kotani_reference_id: type: string description: Kotani reference ID example: KOTANI-REF-789 status: type: string enum: - DEPOSIT_INITIATED - DEPOSIT_CONFIRMED - PAYMENT_SENT - PAYMENT_CONFIRMED - SETTLING - COMPLETED - FAILED - REFUNDED description: Updated settlement status example: COMPLETED timestamp: type: string description: Webhook timestamp (ISO 8601) example: '2024-11-22T12:05:00Z' crypto_payment: description: Crypto payment details allOf: - $ref: '#/components/schemas/WebhookCryptoPaymentDto' settlement_details: description: Settlement details (if successful) allOf: - $ref: '#/components/schemas/WebhookSettlementDetailsDto' failure_details: description: Failure details (if failed) allOf: - $ref: '#/components/schemas/WebhookFailureDetailsDto' refund_details: description: Refund details (if failed and refund initiated) allOf: - $ref: '#/components/schemas/WebhookRefundDetailsDto' metadata: description: Transaction metadata allOf: - $ref: '#/components/schemas/TransactionMetadataDto' required: - webhook_type - provider_reference_id - kotani_reference_id - status - timestamp - crypto_payment WebhookCryptoPaymentDto: type: object properties: chain: type: string enum: - CELO - ETHEREUM - ARBITRUM - AVALANCHE - BINANCE - POLYGON - OPTIMISM - FUSE - TRON - PROVENANCE - SOLANA - HEDERA - STELLAR - BASE - LISK - VICTION - SCROLL - LIGHTNING description: Chain used example: LIGHTNING token: type: string enum: - CUSD - USDC - USDT - BUSD - HASH - HBAR - USDGLO - CKES - CGHS - MSAT description: Token used example: MSAT payment_hash: type: string description: Payment hash example: a1b2c3d4e5f6... received_at: type: string description: When crypto was received (ISO 8601) example: '2024-11-22T12:01:30Z' amount_msat: type: number description: Amount in millisatoshis (Lightning) example: 150000000 crypto_amount: type: number description: Crypto amount (non-Lightning) example: 150.5 required: - chain - token - payment_hash - received_at WebhookSettlementDetailsDto: type: object properties: amount: type: number description: Settlement amount example: 150 currency: type: string description: Settlement currency example: ZAR recipient_phone: type: string description: Recipient phone number example: '+27821234567' payment_method: type: string enum: - MOBILE_MONEY - BANK_TRANSFER description: Payment method used example: MOBILE_MONEY provider: type: string description: Mobile money provider example: VODACOM bank_name: type: string description: Bank name example: ABSA Bank transaction_id: type: string description: Settlement transaction ID from provider example: ZA-TXN-789456 settled_at: type: string description: When settlement completed (ISO 8601) example: '2024-11-22T12:05:00Z' required: - amount - currency - recipient_phone - payment_method - transaction_id - settled_at WebhookFailureDetailsDto: type: object properties: failure_stage: type: string enum: - DEPOSIT_COLLECTION - CRYPTO_PAYMENT - SETTLEMENT description: Stage where failure occurred example: SETTLEMENT failure_reason: type: string description: Failure reason code example: RECIPIENT_ACCOUNT_INVALID failure_message: type: string description: Human-readable failure message example: Mobile number not registered with provider failed_at: type: string description: When failure occurred (ISO 8601) example: '2024-11-22T12:04:00Z' required: - failure_stage - failure_reason - failure_message - failed_at WebhookRefundDetailsDto: type: object properties: refund_method_used: type: string enum: - CRYPTO_INVOICE - CRYPTO_ADDRESS description: Refund method used example: CRYPTO_INVOICE chain: type: string enum: - CELO - ETHEREUM - ARBITRUM - AVALANCHE - BINANCE - POLYGON - OPTIMISM - FUSE - TRON - PROVENANCE - SOLANA - HEDERA - STELLAR - BASE - LISK - VICTION - SCROLL - LIGHTNING description: Chain used for refund example: LIGHTNING token: type: string enum: - CUSD - USDC - USDT - BUSD - HASH - HBAR - USDGLO - CKES - CGHS - MSAT description: Token used for refund example: MSAT refund_invoice: type: string description: Refund invoice (if using invoice method) example: lnbc1500n1p0refund... refund_payment_hash: type: string description: Refund payment hash example: refund123... refund_amount_msat: type: number description: Refund amount in millisatoshis (Lightning) example: 150000000 refund_crypto_amount: type: number description: Refund crypto amount (non-Lightning) example: 150.5 refund_initiated_at: type: string description: When refund was initiated (ISO 8601) example: '2024-11-22T12:04:05Z' refund_status: type: string description: Current refund status example: PENDING required: - refund_method_used - chain - token - refund_initiated_at - refund_status TransactionMetadataDto: type: object properties: sender_name: type: string description: Sender name example: John Doe sender_country: type: string description: Sender country code example: KE recipient_name: type: string description: Recipient name example: Jane Smith recipient_country: type: string description: Recipient country code example: ZA notes: type: string description: Additional notes or context example: Family support payment ````