API reference
Access Visa API endpoints, request and response parameters, authentication details, and sample code to integrate quickly.
Introduction
Visa Developer provides REST APIs across multiple products. Our APIs use resource-oriented URLs, accept JSON request bodies (some APIs also use query parameters or specific header fields), return JSON-encoded responses, and follow standard HTTP verbs and response codes.
You can test safely in Sandbox mode, which doesn’t affect Production systems or send transactions into the Visa payment network. Your project credentials determine whether a request runs in Sandbox or Production.
Visa APIs are versioned and product-specific, and availability can vary by region and use case. Log in to Visa Developer to view documentation, sample data, and configuration for your projects.
Ready to start? Follow the quick start.
Authentication methods
Visa APIs typically use one of two authentication methods.
- Two-way SSL (mutual TLS): Download your certificate and note your user ID/password.
- X-Pay Token: Copy your API key and shared secret.
Important: Keep all keys, certificates, and secrets secure; send all API requests over HTTPS; use Sandbox credentials for development and Certification, and request Production access when you’re ready to go live.
Request and response codes
Visa’s Request and Response Codes reference is the canonical source for code sets used across our APIs and authorizations. It includes HTTP status semantics and extensive Visa‑specific code tables used in requests and responses—for example:
- Authorization and transaction codes: actionCode (authorization outcomes), legacy/new responseCode, businessApplicationId (BAI), fastFundsIndicator, pushFundsIndicator, and sourceOfFundsCode.
- Verification results: addressVerificationResults (AVS), responseCode, businessApplicationId (BAI), fastFundsIndicator, pushFundsIndicator, and sourceOfFundsCode.
- Point‑of‑service context: PAN entry mode, POS condition, POS environment, MOTO ECI indicator, message reason codes.
- Reference dictionaries: card type/sub‑type/product, ISO country and currency codes, network IDs and sharing group codes, and alert taxonomies.
For the latest complete tables, visit request and response codes in documentation.
Note: Individual APIs may map subsets of these tables or add product‑specific fields. Always cross‑check the product’s API reference alongside the product’s documentation.
Error codes
Visa provides a general error codes guide (covering common HTTP errors, authN/authZ failures, rate/quota conditions, and server errors), and many products define additional, product‑specific error payloads (fields like reason codes, correlation IDs, diagnostic messages). Use both the global guide and the product docs when you handle errors and retries.
Success
- 200 OK – Request succeeded and a response body is returned
- 201 Created – A new resource was successfully created
Client errors
- 400 Bad Request – The request was invalid or missing required parameters
- 401 Unauthorized – Authentication failed or credentials were missing
- 403 Forbidden – The credentials do not have access to this resource or operation
- 404 Not Found – The requested resource does not exist
- 409 Conflict – The request conflicts with the current state of the resource or an idempotency conflict occurred
- 429 Too Many Requests – Rate limit exceeded; respect any Retry-After header
Server errors
- 500 Internal Server Error – A transient error occurred on Visa’s side
- 503 Service Unavailable – The service is temporarily unavailable; retry according to your retry policy
Best practices
- Treat 4xx responses as non‑retriable unless the product documentation indicates a correctable condition.
- Implement exponential backoff with jitter for 429 and relevant 5xx responses, honoring any Retry‑After guidance.
- Log correlation IDs and error/reason codes to support efficient troubleshooting with Visa and your acquirer/partners.