Webhook Notifications

Webhook notifications are automated messages sent by Nayax to your back-end to communicate the final status of a transaction, which can be:

Sale/Auth - Approved (Authorized)
Sale/Auth - Declined
Refund - Approved (Refunded)
Refund - Declined (RefundFailed)
Void/Cancel - Approved (Cancelled)
Void/Cancel - Declined (CancelFailed)
Incremental Authorization - Approved (Authorized)
Incremental Authorization - Declined

This ensures you are always up to date with the latest transaction information.

📘
Webhook URL
You will provide the URL to receive the webhooks during the onboarding phase.

Webhook Request

See the examples for each type of request below:

This webhook communicates whether a transaction was authorized or declined by the card issuer.

The following example shows the structure of a standard Sale or Authorization webhook request:

{
  "CardInfo": {
    "IssuerBin": "411111",
    "Brand": "Visa",
    "CardBin": "411111",
    "CardFinalDigits": "1111",
    "ExpiryDate": "12/2025",
    "IssuingCountry": "US",
    "IssuingBank": "Chase Bank",
    "IsCardCommercial": "false",
    "CardHolderName": "John Doe",
    "Alias": "card_alias_123",
    "AliasType": "Default"
  },
  "Ecom3DSInfo": {
    "Is3DSOffered": "true",
    "Is3DSOfferedResponse": "Y",
    "Is3DSAuthenticated": "true",
    "Is3DSAuthenticatedResponse": "Y",
    "IsScaExemptionRequested": "false",
    "LiabilityShift": "true",
    "CardEnrolled": "Y",
    "Eci": "05",
    "Xid": "3ds_xid_abc123"
  },
  "RetryAttempts": [],
  "AdditionalInfo": {
    "AdditionalData": "Order #12345",
    "AdditionalReceiptData": "Thank you for your purchase"
  },
  "NayaxToken": "tok_nayax_abc123def456",
  "NayaxSession": "sess_nayax_xyz789",
  "ExternalTransactionStatus": 13,
  "AuthCode": "AUTH123456",
  "PaymentAccountReference": "PAR123456789",
  "ShopperCountry": "US",
  "ShopperLocale": "en-US",
  "ShopperIp": "192.168.1.100",
  "PaymentMethod": "scheme",
  "Currency": "USD",
  "Amount": "99.99",
  "Cavv": "AAABBZIGAwAAAABQllRGAAAAAAA=",
  "CavvAlgorithm": "1",
  "CvcResult": "M",
  "EReceiptUrl": "https://receipts.nayax.com/receipt/abc123"
}

{
  "CardInfo": {
    "IssuerBin": "542418",
    "Brand": "Mastercard",
    "CardBin": "542418",
    "CardFinalDigits": "8888",
    "ExpiryDate": "09/2024",
    "IssuingCountry": "GB",
    "IssuingBank": "Barclays",
    "IsCardCommercial": "false",
    "CardHolderName": "Jane Smith",
    "Alias": "card_alias_456",
    "AliasType": "Default"
  },
  "Ecom3DSInfo": {
    "Is3DSOffered": "true",
    "Is3DSOfferedResponse": "Y",
    "Is3DSAuthenticated": "false",
    "Is3DSAuthenticatedResponse": "N",
    "IsScaExemptionRequested": "false",
    "LiabilityShift": "false",
    "CardEnrolled": "Y",
    "Eci": "07",
    "Xid": "3ds_xid_def456"
  },
  "RetryAttempts": [
    {
      "AttemptNumber": "1",
      "Result": "Declined",
      "Timestamp": "2025-01-18T10:30:00Z"
    }
  ],
  "AdditionalInfo": {
    "AdditionalData": "Order #12346",
    "AdditionalReceiptData": "Payment declined - Insufficient funds"
  },
  "NayaxToken": "tok_nayax_ghi789jkl012",
  "NayaxSession": "sess_nayax_uvw456",
  "ExternalTransactionStatus": 250,
  "AuthCode": null,
  "PaymentAccountReference": "PAR987654321",
  "ShopperCountry": "GB",
  "ShopperLocale": "en-GB",
  "ShopperIp": "10.0.0.50",
  "PaymentMethod": "scheme",
  "Currency": "GBP",
  "Amount": "150.00",
  "Cavv": null,
  "CavvAlgorithm": null,
  "CvcResult": "N",
  "EReceiptUrl": null
}

Webhook Request Parameters

The following parameters define the structure of the incoming webhook notification:

Field Name	Type	Description
`CardInfo`	Object	Root object containing payment card details.
`IssuerBin`	String	The first 6 digits of the card (BIN).
`Brand`	String	Card brand (e.g., Visa, Mastercard, Amex).
`CardBin`	String	Detailed BIN information.
`CardFinalDigits`	String	Last 4 digits of the card.
`ExpiryDate`	String	Format: `MM/YYYY`.
`IssuingCountry`	String	ISO 2-character country code of the issuer.
`IssuingBank`	String	Name of the issuing financial institution.
`IsCardCommercial`	String	"true" or "false" indicating if it is a business card.
`CardHolderName`	String	Name of the shopper as it appears on the card.
`Alias`	String	Unique identifier/token for the specific card.
`AliasType`	String	Type of alias used (e.g., "Default").
`Ecom3DSInfo`	Object	Contains 3D Secure authentication details.
`Is3DSOffered`	String	"true"/"false" if 3DS was initiated.
`Is3DSAuthenticated`	String	"true"/"false" if shopper passed authentication.
`LiabilityShift`	String	"true"/"false" indicating if liability has shifted to the issuer.
`Eci`	String	Electronic Commerce Indicator (e.g., 02, 05, 07).
`Xid`	String	Transaction identifier for 3DS.
`RetryAttempts`	Array	List of attempt objects containing `AttemptNumber`, `Result`, and `Timestamp`.
`AdditionalInfo`	Object	Metadata and receipt details.
`AdditionalData`	String	Custom merchant-defined data or order IDs.
`AdditionalReceiptData`	String	Information to be displayed on the customer receipt.
`NayaxToken`	String	The reusable token for this payment method.
`NayaxSession`	String	The unique session ID for the transaction.
`ExternalTransactionStatus`	Int	Status code (e.g., 13=Approved, 250=Declined, 62=Refunded).
`AuthCode`	String	Authorization code from the bank (null for declines).
`PaymentAccountReference`	String	PAR associated with the card for tracking across tokens.
`ShopperCountry`	String	Country of the shopper (ISO code).
`ShopperLocale`	String	Language/Locale of the shopper (e.g., en-US).
`ShopperIp`	String	IP address of the shopper.
`PaymentMethod`	String	Method used (e.g., "scheme", "amex").
`Currency`	String	ISO4217 Alpha-3 format (e.g., USD, GBP, EUR).
`Amount`	String	The transaction amount formatted as a string.
`Cavv`	String	Cardholder Authentication Verification Value.
`CvcResult`	String	Response code for the CVC check (e.g., M=Match, N=No Match).
`EReceiptUrl`	String	URL to the digital receipt hosted by Nayax.

Webhook URL

Webhook Request

Webhook Request Parameters

See Also