Install
Requirements: WordPress 6.0+, PHP 7.4+. WooCommerce is optional.
- Download goxost-kyc-wordpress.zip.
- In WordPress open Plugins → Add New → Upload Plugin, choose the zip and click Install Now, then Activate.
- Open Settings → GOXOST KYC.
Connect your account
You need an API key and a webhook endpoint from the GOXOST KYC panel (sign up or log in).
- In the panel create an API key (see Authentication). Start with a
sk_test_…key. - In the plugin settings paste it into API secret key. The settings page shows the mode: Sandbox for
sk_test_…, Live forsk_live_…. - Copy the webhook URL shown on the settings page:
https://your-site.example/wp-json/goxost-kyc/v1/webhook
- In the panel open Webhooks → Add endpoint, paste the URL and choose the events. Recommended:
verification.completed,verification.on_hold,verification.reviewed,session.started,verification.submitted,applicant.reset,applicant.deleted,applicant.reverification_due(or simply All events — the plugin ignores the rest). Leave Include document data in «Result ready» off. - Copy the
whsec_…secret (it is shown once) into Webhook signing secret. - Save, then click Test connection. You should see "Connected" with your plan and period.
The API key and the webhook must belong to the same environment: use a sandbox endpoint with a sk_test_… key and a live endpoint with a sk_live_… key. Events from the other environment are ignored.
Settings
| Setting | Description |
|---|---|
| API secret key | sk_test_… or sk_live_…. Stored in WordPress, never sent to the browser |
| Base URL | https://kyc.goxost.net — change only if support tells you to |
| Webhook signing secret | The whsec_… secret of your webhook endpoint |
| Flow key | Optional. Empty uses the default flow of your account. The flow is fixed when a user's applicant is first created |
| Language | Automatic (site language), Uzbek, Russian or English |
| Verification page | The page with the shortcode or block. Used for links, for example in the checkout notice |
| WooCommerce | Require verification before checkout |
| Uninstall | Delete data on uninstall — removes the verification status and IDs stored for users |
Add the verification page
Create a page and add either the GOXOST KYC verification block (goxost-kyc/verification) or the shortcode:
[goxost_kyc]
Optional attributes override the plugin settings for this page:
[goxost_kyc flow="basic-kyc" locale="ru"]
| Attribute | Values |
|---|---|
flow |
Flow key from the panel |
locale |
uz, ru, en |
What the visitor sees:
- Not logged in — a message and a Log in button. Verification is tied to a WordPress account.
- Not verified, in progress or rejected — the current status and a Verify my identity (or Try again) button. The flow opens on the same page.
- After the flow — "Thank you! Checking your result…", then the status updates from the server.
- Under review or verified — only the status.
Each WordPress user gets one applicant with external_id wp_<user ID>, for example wp_42. You can find them in the panel by this id.
WooCommerce checkout
With Require verification before checkout on, a customer who is not GREEN sees a notice on the checkout page with a link to the verification page, and the order cannot be placed. It works with the classic checkout and the checkout block. Guests are asked to log in first.
Where the status is stored
The plugin stores only IDs, the decision and a timestamp in user meta — never names, document data or images.
| Meta key | Value |
|---|---|
goxost_kyc_status |
GREEN, RED, ON_HOLD or pending; empty if the user never started |
goxost_kyc_applicant_id |
apl_… |
goxost_kyc_verification_id |
ver_… of the last decision |
goxost_kyc_decided_at |
Time of the decision, ISO 8601 UTC |
The status changes only through the signed webhook or a read from the API: applicant.reset and the end of GREEN validity clear the decision, applicant.deleted removes everything.
In Users a KYC column shows each user's status. The user profile has an Identity verification (GOXOST KYC) section; administrators also see the IDs and a Refresh from API button.
Developer hooks
Check the status in templates or your own code:
if ( goxost_kyc_is_verified() ) { // current user
// show verified content
}
if ( goxost_kyc_is_verified( $user_id ) ) { // any user
// ...
}
goxost_kyc_is_verified( $user_id = null ) reads the stored status and never calls the API, so it is cheap to use anywhere.
React to a decision:
add_action( 'goxost_kyc_decision', function ( $user_id, $decision, $payload ) {
// $decision: GREEN, RED or ON_HOLD
// $payload: the webhook event (id, type, created_at, env, data) without document data
if ( 'GREEN' === $decision ) {
( new WP_User( $user_id ) )->add_role( 'verified_customer' );
}
}, 10, 3 );
Change what is sent when the applicant is created:
add_filter( 'goxost_kyc_applicant_data', function ( $payload, $user_id ) {
$payload['purpose'] = 'Age check for alcohol orders';
$payload['metadata'] = [ 'plan' => 'gold' ];
return $payload;
}, 10, 2 );
Do not add personal data to metadata — the API rejects email and phone, and metadata must not contain PII. Keep external_id unchanged: webhooks are matched to users by it.