Skip to content
/
Inbound message regarding...

Inbound message regarding customer Identity related messages
Webhook

Request

When a customer failed to create an order for a specific reason, the status update will be sent to the provided callback endpoint to your server.

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"
statusstringrequired
StatusDescription
ACCOUNT_BLOCKEDCustomer account is blocked.
Value:"ACCOUNT_BLOCKED"
Example:"ACCOUNT_BLOCKED"
status_datestring, (datetime)required

The date of the status update

Example:"2023-06-05 19:53:08"
internal_reasonstringrequired

The internal body for this inbound message containing the reason of the message, this is for internal use.

Example:"Customer account is blocked."
external_reasonstringrequired

The external reason to provide to your customer via your designated messaging channel.

Example:"You order could not be processed"
Payload
{
  "identity_reference": "c-13344",
  "status": "ACCOUNT_BLOCKED",
  "status_date": "2023-06-05 19:53:08",
  "internal_reason": "Customer account is blocked.",
  "external_reason": "You order could not be processed"
}

Responses

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

© Banxa 2026