Skip to content
/
KYC status webhook

KYC status webhook
Webhook

Request

Sent whenever a customer's identity verification status changes, including the result of a Standalone KYC session. Contact your Banxa integration manager to have it enabled.

kyc.status doesn't tell you whether a transaction can proceed. Always check eligibility before creating a ramp.

Bodyapplication/jsonrequired
identity_referencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
accountobjectrequired
kycobjectrequired
POST
kycMessage
Payload
{
  "identity_reference": "c-13344",
  "account": {
    "exists": true,
    "blocked": false,
    "createdAt": "2023-06-05 19:53:08"
  },
  "kyc": {
    "status": "VERIFIED"
  }
}

Responses

Your server returns this code if it accepts the callback. On a failed response we will retry sending the webhook.

© Banxa 2026