Skip to content

KYC refresh guide update 9-26-25 #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 2 commits into
base: main
Choose a base branch
from
Open

KYC refresh guide update 9-26-25 #95

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e333ff9
Documentation edits made through Mintlify web editor
mintlify[bot] Sep 26, 2025
4c54195
Documentation edits made through Mintlify web editor
mintlify[bot] Sep 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 17 additions & 52 deletions guides/identity/kyc-refresh.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,15 @@
---
title: 'Periodic KYC Refresh'
description: Manage the periodic KYC refresh of an Identity on the Paxos Platform in an automated, compliant way.
title: "Periodic KYC Refresh"
description: "Manage the periodic KYC refresh of an Identity on the Paxos Platform in an automated, compliant way."
---

To ensure that Paxos meets regulatory requirements, KYC information of end user identities that are directly onboarded to Paxos must be periodically refreshed (every 1-3 years). All customers that integrate with Paxos [Identity APIs](/api-reference/endpoints/identity) are subject to this process, and must integrate with the automated workflow outlined below to support it.

Paxos streamlines KYC Refresh using a webhook-based approach, which leverages [Paxos Webhooks](/guides/webhooks/quickstart), [Events API](/api-reference/events) and [Identity API](/api-reference/endpoints/identity).





To ensure that Paxos meets regulatory requirements, KYC information of end user identities that are directly onboarded
to Paxos must be periodically refreshed (every 1-3 years).
All customers that integrate with Paxos [Identity APIs](/api-reference/endpoints/identity) are subject to this process, and must integrate with the automated workflow outlined below to support it.

Paxos streamlines KYC Refresh using a webhook-based or polling-based approach, which leverages [Paxos Webhooks](/guides/webhooks/quickstart), [Events API](/api-reference/events) and [Identity API](/api-reference/endpoints/identity).
<Note>
A polling-based approach via [Identity API ](https://docs.paxos.com/api-reference/endpoints/identity/list-identities)will be available in late 2025, check back soon for more details.
</Note>

## Webhook-based Approach

Expand All @@ -23,13 +19,12 @@ Paxos streamlines KYC Refresh using a webhook-based or polling-based approach, w

Setup a [Webhook Consumer](/guides/webhooks/quickstart#consumer) to receive the following KYC refresh events for your end users:

- [`identity.kyc_refresh.started`](/api-reference/events)
- [`identity.kyc_refresh.completed`](/api-reference/events)
- [`identity.kyc_refresh.started`](/api-reference/events/identity-kyc-refresh-object)
- [`identity.kyc_refresh.completed`](/api-reference/events/identity-kyc-refresh-object)
- [`identity.kyc_refresh.expired`](/api-reference/events/identity-kyc-refresh-object)

<Tip>

Use [Get Event](/api-reference/endpoints/events/get-event) to get additional information about the KYC refresh event (`last_kyc_refresh_date`, `next_kyc_refresh_date`, etc.).

Use [Get Event](/api-reference/endpoints/events/get-event) to get additional information about the KYC refresh event (`last_kyc_refresh_date`, `next_kyc_refresh_date`, etc.).
</Tip>

### ➋ Prompt End User about Periodic Refresh
Expand All @@ -43,41 +38,15 @@ When an end user indicates everything is still accurate, call [update-identity](
If an end user refreshed their information, call [update-identity](/api-reference/endpoints/identity/update-identity) as specified above, but also include any changes the end user has made to their information.

<Info>

Calling [update-identity](/api-reference/endpoints/identity/update-identity) with only `last_kyc_refresh_date` and no other changes is considered by Paxos to be confirmation
no information has changed, therefore a completed KYC refresh.
The next KYC refresh date will be updated accordingly (1-3 years from the provided `last_kyc_refresh_date`).

Calling [update-identity](/api-reference/endpoints/identity/update-identity) with only `last_kyc_refresh_date` and no other changes is considered by Paxos to be confirmation
no information has changed, therefore a completed KYC refresh.
The next KYC refresh date will be updated accordingly (1-3 years from the provided `last_kyc_refresh_date`).
</Info>

### ➍ Wait for Completion

Once KYC refresh is complete, a [`identity.kyc_refresh.completed`](/api-reference/events) will be received for the end user in question.

## Polling-based Approach

### ➊ Poll for KYC Refresh Started Events

Poll [List Events](/api-reference/endpoints/events/list-events), offsetting the `created_at.gt` for each subsequent poll, fetching [`identity.kyc_refresh.started`](/api-reference/events) events.

<Info>

We recommend you keep track of the [Event](/api-reference/events) ids you've processed in order to idempotently process the event.

</Info>

### ➋ Prompt End User about Periodic Refresh

As described [above](#-prompt-end-user-about-periodic-refresh) in the webhook-based approach.

### ➌ Inform Paxos about the Refresh

As described [above](#-inform-paxos-about-the-refresh) in the webhook-based approach.

### ➍ Poll for Completed Refreshes

Poll [List Events](/api-reference/endpoints/events/list-events), offsetting the `created_at.gt` for each subsequent poll, fetching [`identity.kyc_refresh.completed`](/api-reference/events) events.

## Advanced

### Handling Expired Refreshes
Expand All @@ -90,16 +59,12 @@ If this occurs, several outcomes could be experienced:

### Refreshes in Compliance Review

In some cases, the Paxos compliance team might need to review the changes received from the end user as part of the
KYC refresh process.
In this case, the [`identity.kyc_refresh.completed`](/api-reference/events) event could experience a meaningful delay in being received.
In some cases, the Paxos compliance team might need to review the changes received from the end user as part of the KYC refresh process. In this case, the `identity.kyc_refresh.completed` event could experience a meaningful delay in being received.

### Backdating the Last KYC Refresh Date

If a historical record is known for the last KYC refresh dates of your end users **or** you've experienced an issue processing KYC refresh for an end-user then you can directly call [update-identity](/api-reference/endpoints/identity/update-identity) setting the `last_kyc_refresh_date` to the known date in the past, and Paxos will accept this as the date KYC refresh was performed for the end user.

<Warning>

Setting this date beyond the 1-3 year refresh period for an end user will cause an immediate [`identity.kyc_refresh.started`](/api-reference/events) to be triggered for the end user.

</Warning>
Setting this date beyond the 1-3 year refresh period for an end user will cause an immediate [`identity.kyc_refresh.started`](/api-reference/events) to be triggered for the end user.
</Warning>
Loading