Overview

This page explains common authentication and error-handling considerations for Visa Click to Pay integrations, including:

Bearer token authentication
required permissions
SDK errors
checkout response validation
payload decryption failures
authorization failures
3DS and OTP handling
onboarding and configuration errors

Detailed error codes and response schemas will be added once the final API specifications are available.

Authentication

Visa Click to Pay APIs require authentication using a Bearer token.

Authorization: Bearer {{access_token}}

Some APIs may require additional permissions depending on the action being performed.

Required Permissions

Permission	Used for
`VIEW_UCTP_WALLET_CERTIFICATE`	Retrieve Click to Pay encryption key configuration
`CREATE_AUTHORIZATION`	Process Click to Pay payment authorization

Platform-Level Authentication

Platform and Tenant enablement APIs require a Platform-level access token.

These APIs are used to:

enable Visa Click to Pay on the Platform level,
enable Visa Click to Pay on the Tenant level,
make Visa Click to Pay available for supported integration flows.

Common Error Scenarios

Scenario	Possible cause	Recommended action
Authentication failed	Missing, expired, or invalid Bearer token	Request a new access token and retry the request
Permission denied	Token does not include required permissions	Confirm that the token includes the required permission
Merchant configuration unavailable	Merchant has not been onboarded or configuration is incomplete	Confirm merchant onboarding and enablement status
Encryption keys unavailable	Missing permission or configuration issue	Confirm `VIEW_UCTP_WALLET_CERTIFICATE` access and key configuration
SDK initialization failed	Missing or invalid SDK configuration	Confirm `dpaId`, `dpaClientId`, supported brands, and SDK setup
Saved cards unavailable	Customer has no saved Click to Pay cards or identifier was not recognised	Allow the customer to add a new card or use a different identifier
OTP verification failed	Incorrect or expired OTP	Allow the customer to retry or restart authentication
Checkout failed	SDK checkout flow could not complete	Show a clear customer-facing error and allow retry
Invalid JWS signature	Checkout response could not be verified	Reject the request and do not decrypt the payload
Payload decryption failed	Invalid encrypted payload or key mismatch	Reject the request and investigate encryption configuration
Authorization failed	Payment could not be authorized	Return the payment failure state to the checkout experience
3DS required	Additional customer authentication is required	Redirect or render the required 3DS challenge flow
3DS failed	Customer authentication failed or expired	Return a failed payment state and allow retry

SDK Error Handling

Frontend integrations should handle errors from the Visa Click to Pay SDK gracefully.

Examples include:

initialization errors,
customer identification errors,
OTP validation errors,
card retrieval errors,
checkout errors,
timeout errors.

Customer-facing messages should be clear and helpful, but should not expose sensitive technical details.

Backend Validation Errors

Backend systems should validate all Click to Pay responses before processing payment data.

Validation should include:

checking the request structure,
validating the JWS signature,
confirming required fields are present,
decrypting the payload only after signature validation,
rejecting invalid or tampered responses.

JWS Signature Validation Errors

If JWS signature validation fails, the backend must reject the request.

Do not:

decrypt the payload,
process payment authorization,
retry automatically with the same payload,
expose sensitive error details to the customer.

Recommended response:

log the failure securely,
return a generic payment processing error,
allow the customer to restart checkout.

Payload Decryption Errors

Payload decryption may fail if:

the encrypted payload is invalid,
the wrong private key is used,
the key pair configuration is incorrect,
the payload has been modified.

When this happens, the backend should reject the request and treat the payload as untrusted.

3DS and Authentication Handling

Some Click to Pay transactions may require additional authentication.

Depending on the returned authentication data and ECI value, the backend may need to:

return an await_3ds state,
direct the customer to complete 3DS authentication,
continue authorization after authentication,
return the final payment result.

OTP Handling

OTP may be required during customer identification or saved-card retrieval.

Frontend applications should:

display clear OTP instructions,
allow customers to retry,
handle expired OTPs,
allow customers to switch identifier where supported,
avoid exposing sensitive verification details.

Onboarding and Configuration Errors

Visa Click to Pay may depend on merchant, platform, and tenant-level configuration.

Errors may occur if:

the merchant is not onboarded,
the merchant configuration is incomplete,
Visa Click to Pay is not enabled on the required level,
required credentials or keys are missing,
merchant data is out of sync.

Recommended checks:

confirm merchant onboarding status,
confirm Platform-level enablement,
confirm Tenant-level enablement,
confirm required key configuration,
confirm the correct environment is being used.

Retry Behaviour

Retry behaviour depends on the type of failure.

Error type	Retry guidance
Expired access token	Retry after requesting a new token
Network timeout	Retry with caution
SDK initialization error	Do not retry until configuration is corrected
Invalid signature	Do not retry the same payload
Decryption failure	Do not retry the same payload
Authorization failure	Follow payment failure handling
OTP failure	Allow customer retry
3DS failure	Allow customer to restart checkout

Logging and Monitoring

Backend systems should log enough information to support troubleshooting, without exposing sensitive payment data.

Recommended logging:

request correlation ID,
order reference,
payment reference,
merchant reference,
error category,
timestamp,
sanitized failure reason.

Avoid logging:

full checkout responses,
decrypted payloads,
PAN values,
private keys,
shared secrets,
access tokens.

Customer-Facing Error Messages

Customer-facing messages should be simple and non-technical.

Examples:

Scenario	Suggested message
Checkout failed	We could not complete your Click to Pay checkout. Please try again.
OTP failed	The verification code could not be confirmed. Please try again.
Payment declined	Your payment could not be authorized. Please use another card or payment method.
Session expired	Your checkout session has expired. Please restart checkout.
3DS failed	Authentication could not be completed. Please try again or use another payment method.

Additional Notes

This page provides general error-handling and authentication guidance based on the current Visa Click to Pay implementation design. Final error codes, response fields, and API-specific examples should be added once the implementation teams provide the confirmed API specifications.

Error Handling & Authentication