Submit KYC

post

https://openapi.sandbox.xenithpay.com/v1/kyc

Submit a Japanese customer for KYC. The request is asynchronous: Xenith validates the request, creates a PENDING KYC record, and returns a kycId before verification is complete. KYC is required before the customer can transact in JPY.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

customerReference

string

required

length between 1 and 64

Merchant-provided identifier for the customer. Must be unique per merchant.

currency

string

enum

required

ISO 4217 currency code. KYC is currently supported for JPY only.

Allowed:

callbackUrl

uri

HTTPS URL where Xenith sends KYC status updates. If omitted, Xenith uses the merchant's pre-registered webhook URL.

metadata

object

required

KYC fields for the resolved gateway. nameKatakana is mandatory; additional gateway-supported fields may be added here without changing the request envelope.

Headers

Xenith-Api-Key

string

required

API Key will be delivered to you by email

Xenith-Request-Timestamp

string

required

ISO 8601 date time format, should be in (UTC+0)

Xenith-Request-Signature

string

required

Refer to page Build Signature and Set Headers for instructions on how to build a signature

X-Idempotency-Key

string

required

length ≤ 100

A unique key to prevent duplicate KYC submissions. Must be unique across all KYC submissions for the merchant. Max 100 characters. Reusing the key with a different body returns DUPLICATE_TRANSACTION_ERROR.

Responses

Callback

200An existing PENDING or APPROVED KYC record was returned. Repeating the submission does not create a new attempt.

201KYC submission accepted and created in PENDING status.

400The request failed validation or the idempotency key was reused with a different request body.

408The gateway did not respond in time. The submission may or may not have been created; check the KYC status and retry with the same X-Idempotency-Key when appropriate.

500An internal or gateway error occurred. The KYC record remains PENDING; reconcile using Get KYC Status.

503The gateway's KYC service is temporarily unavailable.