Compliance Workflows & Endpoints

Celar compliance has two operational parts:

• Customer verification (KYC/KYB) during onboarding and customer updates
• Transaction monitoring (KYT) during pay-ins and post-transaction review

Use this page as the main operational reference for both.

1. Customer Verification (KYC/KYB)

Verification Lifecycle

1. Create the customer record via API or Dashboard.
2. Add payment details if your payment flow requires them.
3. Upload the required customer documents.
4. Trigger identity verification.
5. Wait for kyc_status to move from pending to success before transacting.
6. If the customer profile changes later, kyc_status may move to pending_update while Celar re-checks the record.

Required Documents

Customer type	document_type	Required uploads
Individual	id_card, passport, or driver_license	verification_document, proof_of_residential_address
Business	incorporation_certificate	verification_document, proof_of_residential_address, incorporation_certificate, proof_of_business_address

Upload Customer Documents

Attach identity and address verification documents to an existing customer. Documents are sent as multipart/form-data, not JSON.

All files must be PDF format, max 5 MB each.

Field	Required	Description
customer_id	Yes	ID of the customer to attach documents to
verification_document	Yes	Government-issued ID, passport, or driver's license
proof_of_residential_address	Yes	Utility bill, bank statement, or similar
incorporation_certificate	Business only	Required for business customers
proof_of_business_address	Business only	Required for business customers

curl --request PATCH \
  --url https://api.sandbox.celar.io/api/v1/customers/uploads \
  --header 'Authorization: Bearer <token>' \
  --form 'customer_id=cr_53c79dae85d2cee2' \
  --form 'verification_document=@/path/to/id.pdf' \
  --form 'proof_of_residential_address=@/path/to/proof_address.pdf' \
  --form 'incorporation_certificate=@/path/to/cert.pdf' \
  --form 'proof_of_business_address=@/path/to/business_address.pdf'

Example Response

{
  "message": "Documents uploaded successfully.",
  "data": {
    "verification_document": "customers/verification_document_id_a3f1c2b4.pdf",
    "proof_of_residential_address": "customers/proof_of_residential_address_bill_9e2d1a.pdf",
    "incorporation_certificate": "customers/incorporation_certificate_cert_7b3e9f.pdf",
    "proof_of_business_address": "customers/proof_of_business_address_lease_1c4d8a.pdf"
  }
}

note

The returned values are internal blob storage paths, not public URLs. To inspect the stored paths later, fetch the customer record from Customers Endpoints.

Complete Identity Verification

After documents are uploaded, trigger identity verification. This sends an identity verification link to the customer's email address for the face/selfie check, initiating the KYC review.

Once the customer completes the verification, kyc_status will update to success and the customer will be cleared for transactions.

curl --request POST \
  --url https://api.sandbox.celar.io/api/v1/customers/compliance \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cr_c32e9ac9d9a0d6ac",
    "email": "john.doe@example.com"
  }'

Example Response

{
  "message": "Identity verification link sent successfully",
  "data": {
    "email": "john.doe@example.com"
  }
}

note

The email field in the request body is the address where the identity verification link will be sent. It does not need to match the email on the customer record.

Dashboard Path

The operational UI still lives under the Customers area in the Celar Dashboard, even though the docs for this workflow live in Compliance.

1. Open the Customers tab in the Dashboard.
2. Create a new customer or open an existing one.
3. Confirm the correct document_type for the customer.
4. Upload the required verification documents from the customer flow.
5. Complete the identity verification step and monitor kyc_status until it reaches success.

Verification Status Expectations

• pending -> Customer record exists, but verification is not complete yet.
• success -> Verification passed and the customer is cleared for transactions.
• pending_update -> Customer details changed and Celar is re-running compliance checks.

For broader compliance verdicts, responsibilities, and policy context, see Compliance Details.

2. Transaction Monitoring (KYT)

Celar's compliance engine runs KYT (Know Your Transaction) checks automatically on all pay-ins. Use these endpoints to fetch individual results or review summaries.

Get Risk for a Pay-in

Retrieve the KYT verdict for a specific payin_id.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/risk/payments/<payin_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Example Response

{
  "payment_id": "payin_47cb728afdb91063",
  "kytVerdict": "low",
  "totalScore": 0,
  "flags": [],
  "checked_at": "2025-09-26T12:08:08.840Z"
}

List Historical KYT Checks

Retrieve historical KYT risk evaluations for all pay-ins under your PSP.

Optional Query Parameters

• level -> filter by risk level (low, medium, high)
• limit -> number of results to return
• offset -> pagination offset

curl --request GET \
  --url "https://api.sandbox.celar.io/api/v1/risk/checks?level=high&limit=10&offset=0" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Get Customer Risk Summary

Retrieve compliance summary for a specific customer.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/risk/summary/customers/<customer_id> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Example Response

{
  "customer_id": "cr_ef211d4ba9c0",
  "risk_level": "medium",
  "last_check": "2025-09-26T11:55:04.522Z"
}

Get PSP Risk Summary

Retrieve an aggregate compliance summary for your entire PSP account.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/risk/summary/total \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Example Response

{
  "psp_id": "psp_3563fdacebcb",
  "total_checks": 245,
  "risk_levels": {
    "low": 220,
    "medium": 20,
    "high": 5
  },
  "last_check": "2025-09-26T12:12:47.733Z"
}

Notes

• KYT runs only on pay-ins.
• Payouts and withdrawals do not trigger KYT checks directly.
• Customer- and PSP-level summaries help you monitor compliance health across your organization.