Fin Webhooks API
The Webhooks API from Fin — 0 operation(s) for webhooks.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fin-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fin.com Webhooks API
version: 1.0.0
description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
description: Sandbox server
- url: https://api.fin.com
description: Production server
tags:
- name: Webhooks
paths: {}
webhooks:
transit.payment.status:
post:
summary: Transit Payment Status
description: Triggered when a transit payment's status changes through the payment and settlement flow.
x-mint:
metadata:
title: transit.payment.status
content: "## Payment Status Values\n- **PAY_INIT**: Payment initialized\n- **PAY_PROCESS**: Payment is being processed\n- **PAY_SUCCESS**: Payment completed successfully\n- **PAY_FAILED**: Payment failed\n- **PAY_TIMEOUT**: Payment timed out\n- **PAY_CANCEL**: Payment was cancelled\n- **SETTLEMENT_INIT**: Settlement process started\n- **SETTLEMENT_SUCCESS**: Settlement completed successfully\n- **SETTLEMENT_HOLD**: On hold due to insufficient rebalancing funds. Fin will auto-proceed once funds are available.\n- **SETTLEMENT_FAILED**: Settlement failed after 3 retry attempts\n\n<Note>\n The `settlement_info` field will be `null` for PAY_* statuses and populated for SETTLEMENT_* statuses.\n</Note>\n\n<Note>\n All webhook requests include HMAC signatures for verification.\n</Note>\n"
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- event
- data
properties:
event:
type: object
required:
- id
- type
- event_reference_id
- created_at
properties:
id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
type:
type: string
enum:
- transit.payment.status
example: transit.payment.status
event_reference_id:
type: string
format: uuid
description: Reference to the payment_id
example: FIN_PROVIDED_UUID
created_at:
type: string
format: date-time
example: '2025-10-10T15:40:56Z'
data:
type: object
required:
- payment_id
- integration_type
- status
- create_time
- payment_info
properties:
payment_id:
type: string
format: uuid
example: FIN_PROVIDED_UUID
integration_type:
type: string
example: BYBIT
quote_id:
type: string
format: uuid
example: FIN_PROVIDED_UUID
status:
type: string
enum:
- PAY_INIT
- PAY_PROCESS
- PAY_SUCCESS
- PAY_FAILED
- PAY_TIMEOUT
- PAY_CANCEL
- SETTLEMENT_INIT
- SETTLEMENT_HOLD
- SETTLEMENT_SUCCESS
- SETTLEMENT_FAILED
example: PAY_INIT
create_time:
type: integer
example: 1740748353
payment_info:
type: object
properties:
pay_id:
type: string
example: 01JN6AZVEMAC8H9SED6JES3QH8
merchant_trade_no:
type: string
example: 841e4ba2-...-a2a45de7bd00
amount:
type: string
example: '100'
status:
type: string
enum:
- PAY_INIT
- PAY_PROCESS
- PAY_SUCCESS
- PAY_FAILED
- PAY_TIMEOUT
- PAY_CANCEL
example: PAY_INIT
currency:
type: string
example: USDT
currency_type:
type: string
example: crypto
expire_time:
type: integer
example: 1740751953
payment_time:
type: integer
description: 0 until PAY_SUCCESS
example: 0
settlement_info:
type: object
nullable: true
description: null for PAY_* statuses, populated for SETTLEMENT_* statuses
properties:
settlement_via:
type: string
enum:
- ONE_TO_ONE
- MARKET_ORDER
- FEE_RETENTION
example: MARKET_ORDER
wallet_address:
type: string
example: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
currency:
type: string
enum:
- USDC
- USDT
- BTC
- ETH
example: USDC
rail:
type: string
enum:
- SOLANA
- BITCOIN
- ETHEREUM
- BASE
example: SOLANA
amount:
type: string
example: '100'
trx_hash:
type: string
nullable: true
settle_time:
type: integer
example: 0
status:
type: string
enum:
- SETTLEMENT_INIT
- SETTLEMENT_HOLD
- SETTLEMENT_SUCCESS
- SETTLEMENT_FAILED
example: SETTLEMENT_INIT
retry_attempts:
type: integer
minimum: 0
maximum: 3
example: 0
examples:
paymentInitiated:
summary: Payment Initiated
value:
event:
id: 550e8400-e29b-41d4-a716-446655440000
type: transit.payment.status
event_reference_id: FIN_PROVIDED_UUID
created_at: '2025-10-10T15:40:56Z'
data:
payment_id: FIN_PROVIDED_UUID
integration_type: BYBIT
status: PAY_INIT
create_time: 1740748353
payment_info:
pay_id: 01JN6AZVEMAC8H9SED6JES3QH8
merchant_trade_no: 841e4ba2-...-a2a45de7bd00
amount: '100'
status: PAY_INIT
currency: USDT
currency_type: crypto
expire_time: 1740751953
payment_time: 0
settlement_info: null
settlementSuccess:
summary: Settlement Success
value:
event:
id: 550e8400-e29b-41d4-a716-446655440003
type: transit.payment.status
event_reference_id: FIN_PROVIDED_UUID
created_at: '2025-10-10T15:47:00Z'
data:
payment_id: FIN_PROVIDED_UUID
integration_type: BYBIT
status: SETTLEMENT_SUCCESS
create_time: 1740748353
payment_info:
pay_id: 01JN6AZVEMAC8H9SED6JES3QH8
merchant_trade_no: 841e4ba2-...-a2a45de7bd00
amount: '100'
status: PAY_SUCCESS
currency: USDT
currency_type: crypto
expire_time: 1740751953
payment_time: 1740748353
settlement_info:
settlement_via: MARKET_ORDER
wallet_address: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
currency: USDC
rail: SOLANA
amount: '100'
trx_hash: 0x580...
settle_time: 1740748353
status: SETTLEMENT_SUCCESS
retry_attempts: 0
responses:
'200':
description: Webhook received successfully
customer.created:
post:
summary: Customer Created
description: Triggered when a customer is successfully created.
x-mint:
metadata:
title: customer.created
content: "Triggered when a customer is successfully created. Supports both `INDIVIDUAL` and `BUSINESS` customer types.\n\n<Note>\n All webhook requests include HMAC signatures for verification.\n Learn how to [verify webhook signatures](/guides/webhooks/verifying-webhooks).\n</Note>\n"
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event:
$ref: '#/components/schemas/WebhookEventEnvelope'
data:
oneOf:
- $ref: '#/components/schemas/IndividualCustomerData'
- $ref: '#/components/schemas/BusinessCustomerData'
examples:
individualCreated:
summary: Individual Customer Created
value:
event:
id: 60bef15c-4e30-4eb4-bc4d-aa697a7e0857
event_reference_id: c3309534-1517-4d15-b244-be8f943c3823
type: customer.created
created_at: '2025-11-30T07:40:06.853938Z'
sandbox_mode: true
data:
country_of_residence: USA
created_at: '2025-11-30T07:40:06Z'
customer_id: c3309534-1517-4d15-b244-be8f943c3823
customer_status: INCOMPLETE
email: john.doe@email.com
first_name: John
last_name: Doe
phone: '+12597751234'
tos_policies_url: 25764ef6-0f4f-4846-b7c6-9df0598358e9
type: INDIVIDUAL
verification_type: RELIANCE
businessCreated:
summary: Business Customer Created
value:
event:
id: d2a592e4-5703-46aa-b1ac-fa1fa6359abf
event_reference_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
type: customer.created
created_at: '2026-04-13T11:38:57.819938Z'
sandbox_mode: false
data:
associated_parties:
- email: fatima.rahman22@acmecorp.com.bd
id: f6b13e01-044a-4f74-a70b-d5f66b6449af
ownership_percent: 60
type: INDIVIDUAL
verification:
reason:
for_customer: null
for_developer: null
status: INITIATED
updated_at: '2026-04-13T11:38:57.824452053Z'
- email: karim.islam22@acmecorp.com.bd
id: f71dc19f-b9a0-49fb-bd2d-5add3c01626e
ownership_percent: 40
type: INDIVIDUAL
verification:
reason:
for_customer: null
for_developer: null
status: INITIATED
updated_at: '2026-04-13T11:38:57.824452053Z'
business_name: Fin.com
country_of_incorporation: BGD
created_at: '2026-04-13T11:38:57Z'
customer_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
customer_status: INCOMPLETE
email: m@tech.com
phone: '+8801529876543'
type: BUSINESS
verification_type: STANDARD
responses:
'200':
description: Webhook received successfully
customer.status:
post:
summary: Customer Status
description: Triggered when a customer's status changes during verification.
x-mint:
metadata:
title: customer.status
content: "### Customer Status Values\n\nThe status values in the payload depend on which API version was used to create the customer. V1 and V2 use different status names for the same underlying states. V1 has not been deprecated and both sets of statuses are active.\n\n| Status | V1 Name | V2 Name | Description |\n|--------|---------|---------|-------------|\n| Awaiting processing | `QUEUED` | `PROCESSING` | Verification request sent to the work processor |\n| Under review | `REVIEWING` | `REVIEWING` | Customer verification is currently under review |\n| Verified | `APPROVED` | `APPROVED` | Successfully verified and approved |\n| Parties pending | `ASSOCIATED_PARTIES_REMAINING` | `ASSOCIATED_PARTIES_REMAINING` | Additional associated parties need verification |\n| Paused | `ON_HOLD` | `IN_COMPLIANCE` | Verification paused for compliance review |\n| Action needed | `REINITIATE` | `ACTION_REQUIRED` | New document upload required |\n| Rejected | `REJECTED` | `REJECTED` | Customer verification rejected |\n\n<Note>\n `ACTION_REQUIRED` (V2) is also set by the `customer.rfi` webhook, which includes a structured payload describing exactly which documents or fields are missing or invalid.\n</Note>\n\n<Note>\n All webhook requests include HMAC signatures for verification.\n</Note>\n"
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event:
$ref: '#/components/schemas/WebhookEventEnvelope'
data:
oneOf:
- $ref: '#/components/schemas/IndividualCustomerData'
- $ref: '#/components/schemas/BusinessCustomerData'
examples:
v1IndividualQueued:
summary: 'V1: Individual Customer Queued'
value:
event:
id: 29ceb6c4-4849-4312-9b2b-5e8360647da0
event_reference_id: f9e1b162-8a05-4611-9e13-f38e0eb24a29
type: customer.status
created_at: '2026-01-18T09:08:18.66348Z'
sandbox_mode: true
data:
customer_id: f9e1b162-8a05-4611-9e13-f38e0eb24a29
customer_status: QUEUED
email: john.doe@acmecorp.com
first_name: John
last_name: Doe
type: INDIVIDUAL
verification_type: STANDARD
v1BusinessOnHold:
summary: 'V1: Business Customer On Hold'
value:
event:
id: 0deacdde-cd58-42ea-8a1c-dde8668a92e4
event_reference_id: 98665e7d-7736-4762-a57a-cc1e6706302f
type: customer.status
created_at: '2026-01-18T10:32:59.434557Z'
sandbox_mode: true
data:
business_name: Acme Corp Ltd
country_of_incorporation: USA
customer_id: 98665e7d-7736-4762-a57a-cc1e6706302f
customer_status: ON_HOLD
email: contact@acmecorp.com
type: BUSINESS
verification_type: STANDARD
v1BusinessReinitiate:
summary: 'V1: Business Customer Reinitiate'
value:
event:
id: c8f2a5b1-3e4d-4a9c-b7e2-d1f3c8a9b0e5
event_reference_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
type: customer.status
created_at: '2026-01-20T14:15:30.123456Z'
sandbox_mode: true
data:
business_name: Acme Corp Ltd
country_of_incorporation: USA
customer_id: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
customer_status: REINITIATE
email: contact@acmecorp.com
type: BUSINESS
verification_type: STANDARD
v2IndividualProcessing:
summary: 'V2: Individual Customer Processing'
value:
event:
id: 3a4b5c6d-7e8f-9012-abcd-ef1234567890
event_reference_id: f9e1b162-8a05-4611-9e13-f38e0eb24a29
type: customer.status
created_at: '2026-04-04T09:08:18.66348Z'
sandbox_mode: false
data:
customer_id: f9e1b162-8a05-4611-9e13-f38e0eb24a29
customer_status: PROCESSING
email: john.doe@acmecorp.com
first_name: John
last_name: Doe
type: INDIVIDUAL
verification_type: STANDARD
v2BusinessInCompliance:
summary: 'V2: Business Customer In Compliance'
value:
event:
id: 0deacdde-cd58-42ea-8a1c-dde8668a92e4
event_reference_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
type: customer.status
created_at: '2026-04-13T11:40:51.434557Z'
sandbox_mode: false
data:
business_name: Fin.com
country_of_incorporation: BGD
customer_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
customer_status: IN_COMPLIANCE
email: m@tech.com
type: BUSINESS
verification_type: STANDARD
v2BusinessActionRequired:
summary: 'V2: Business Customer Action Required'
value:
event:
id: f1e2d3c4-b5a6-7890-cdef-123456789012
event_reference_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
type: customer.status
created_at: '2026-04-13T11:40:51.000000Z'
sandbox_mode: false
data:
business_name: Fin.com
country_of_incorporation: BGD
customer_id: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
customer_status: ACTION_REQUIRED
email: m@tech.com
type: BUSINESS
verification_type: STANDARD
responses:
'200':
description: Webhook received successfully
customer.rfi:
post:
summary: Customer RFI
description: Triggered when the compliance team requests additional information or documents from a customer. Sets the customer status to ACTION_REQUIRED. The payload includes a structured list of what is missing, invalid, or expired, scoped to either the customer or a specific associated party.
x-mint:
metadata:
title: customer.rfi
content: "### When This Fires\nThis webhook fires when compliance flags one or more documents or fields\nas missing, expired, or invalid. The customer status will be set to\n`ACTION_REQUIRED`.\n\n<Note>\n An RFI can also be triggered after a customer is already `APPROVED`. In that case the customer status remains unchanged. Only the `rrequest_for_information` object in the payload will contain data and this webhook will be received.\n</Note>\n\n### RFI Available Scope\n- **CUSTOMER**: The issue is with the customer's own documents or data\n- **ASSOCIATED PARTY**: The issue is with a specific associated party (identified by `associated_party_id`)\n\n### Field Status Values\n- **MISSING**: Document or field was not provided\n- **EXPIRED**: Document has passed its expiry date\n- **INVALID**: Document or field value does not meet requirements (see `reason`)\n\n### Section Values by Customer Type\n\n| Customer Type | Sections |\n|---------------|----------|\n| Individual | `proof_of_identity`, `proof_of_address`, `tos_policies_value` |\n| Business V1 | `company_details`, `ownership_structure`, `legal_presence` |\n| Business V2 | `formation_documents`, `ownership_documents`, `supporting_documents` |\n| Associated Party (V1) | `proof_of_identity`, `proof_of_address` |\n| Associated Party (V2) | `identifying_documents`, `tax_info`, `address_documents` |\n\n<Note>\n All webhook requests include HMAC signatures for verification.\n</Note>\n"
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event:
$ref: '#/components/schemas/WebhookEventEnvelope'
data:
type: object
required:
- customer_id
- request_for_information
properties:
customer_id:
type: string
format: uuid
description: The customer for whom information is requested.
example: cust-uuid-1234
request_for_information:
type: array
description: List of document or field issues that must be resolved.
items:
type: object
required:
- section
- categories
properties:
section:
type: string
description: 'The document section with the issue. Individual: proof_of_identity, proof_of_address, tos_policies_value. Business V1: company_details, ownership_structure, legal_presence. Business V2: formation_documents, ownership_documents, supporting_documents. Associated Party V1: proof_of_identity, proof_of_address. Associated Party V2: identifying_documents, tax_info, address_documents.'
example: proof_of_identity
categories:
type: array
items:
type: object
required:
- document_type
- fields
properties:
document_type:
type: string
description: The type of document with the issue.
example: GOVERNMENT_ID
fields:
type: array
items:
type: object
required:
- field_name
- data_type
- status
properties:
field_name:
type: string
description: The specific field with the issue.
example: files
data_type:
type: string
enum:
- URI
- DATE
- TEXT
- ENUM
description: The data type of the field.
example: URI
status:
type: string
enum:
- MISSING
- EXPIRED
- INVALID
description: The nature of the issue.
example: EXPIRED
side:
type: string
enum:
- FRONT
- BACK
nullable: true
description: For file fields only. Indicates which side of the document is affected. Null for non-file fields.
example: FRONT
reason:
type: string
nullable: true
description: Human-readable explanation. Null when status is MISSING.
example: Document has expired
examples:
individual:
summary: Individual Customer RFI
value:
event:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
event_reference_id: cust-uuid-1234
type: customer.rfi
created_at: '2026-04-04T10:00:00.000000Z'
sandbox_mode: false
data:
customer_id: cust-uuid-1234
request_for_information:
- section: proof_of_identity
categories:
- document_type: GOVERNMENT_ID
fields:
- field_name: files
data_type: URI
status: EXPIRED
reason: Document has expired
side: FRONT
- field_name: files
data_type: URI
status: INVALID
reason: Back side damaged
side: BACK
- field_name: issue_date
data_type: DATE
status: MISSING
reason: null
- field_name: expiry_date
data_type: DATE
status: MISSING
reason: null
- field_name: text
data_type: TEXT
status: INVALID
reason: Name mismatch
- section: proof_of_address
categories:
- document_type: PROOF_OF_ADDRESS
fields:
- field_name: files
data_type: URI
status: MISSING
reason: null
- section: tos_policies_value
categories:
- document_type: TOS
fields:
- field_name: tos_policies_value
data_type: TEXT
status: MISSING
reason: null
businessV1:
summary: Business Customer V1 RFI
value:
event:
id: b2c3d4e5-f6a7-8901-bcde-f12345678901
event_reference_id: biz-uuid-5678
type: customer.rfi
created_at: '2026-04-04T10:00:00.000000Z'
sandbox_mode: false
data:
customer_id: biz-uuid-5678
request_for_information:
- section: company_details
categories:
- document_type: CERT_OF_INCORPORATION
fields:
- field_name: files
data_type: URI
status: INVALID
reason: Document is illegible
side: FRONT
- field_name: text
data_type: TEXT
status: INVALID
reason: Business name mismatch
- section: ownership_structure
categories:
- document_type: SHAREHOLDER_REGISTRY
fields:
- field_name: files
data_type: URI
status: MISSING
reason: null
- section: legal_presence
categories:
- document_type: PROOF_OF_ADDRESS
fields:
- field_name: files
data_type: URI
status: MISSING
reason: null
- section: proof_of_identity
categories:
- document_type: GOVERNMENT_ID
fields:
- field_name: files
data_type: URI
status: EXPIRED
reason: Document expired
side: FRONT
- field_name: files
data_type: URI
status: INVALID
reason: Back side blurry
side: BACK
- field_name: issue_date
data_type: DATE
status: MISSING
reason: null
- field_name: expiry_date
data_type: DATE
status: MISSING
reason: null
- field_name: text
data_type: TEXT
status: INVALID
reason: Name mismatch
- section: proof_of_address
categories:
- document_type: PROOF_OF_ADDRESS
fields:
- field_name: files
data_type: URI
status: MISSING
reason: null
businessV2:
summary: Business Customer V2 RFI
value:
event:
id: c3d4e5f6-a7b8-9012-cdef-123456789
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/openapi/fin-webhooks-api-openapi.yml