Assistant
Payvala Assistant
Suggestions
Press Enter to send · Shift+Enter for new line
The Payvala Payment service provides developers with a structured way to initiate, process, and track payment transactions through the Payvala platform. It exposes a set of API endpoints that allow your application to submit payment requests, receive processing results, and react to transaction outcomes in real time or asynchronously.
Payment is one of the core services in the Payvala ecosystem. It acts as the transaction layer between your application and the underlying payment infrastructure. Rather than building and maintaining direct integrations with payment networks yourself, you submit payment requests to Payvala and receive structured responses about the outcome.
This service is intended for developers and businesses that need to collect payments from customers or counterparties as part of an application workflow. It is not a consumer-facing product — it is a developer API.
Explore the Payment API capabilities and understand how they map to your application's transaction and checkout workflows.
Request access through the Payvala developer portal to receive sandbox credentials and full API reference documentation.
Use your sandbox credentials and the Payment API documentation to build, authenticate, and validate your integration before processing real transactions.
Complete integration validation and production-readiness requirements before switching your approved Payment integration to production credentials.
Payvala offers multiple services. Payment handles transaction initiation and processing. Other services in the ecosystem — such as identity verification, account management, or reporting — may interact with Payment but operate independently. This page covers the Payment service only.
Before integrating any payment API, it helps to understand what problem it solves and whether it fits your use case.
Instead of building separate integrations for each payment method or network your business needs to support, you integrate once with Payvala Payment. Payvala handles the downstream complexity.
Payment provides structured transaction status at each stage of processing. Your application can query the status of a transaction at any time, or receive notifications via webhook when the status changes.
Payment responses follow a consistent structure. Success, failure, and pending states are clearly represented, making it straightforward to build reliable result-handling logic in your application.
When a payment cannot be completed, Payvala returns structured error information that your application can use to surface useful feedback or trigger retry and fallback logic.
Payment is designed to be called from within your application's business logic. You control when a payment is initiated, what data is submitted, and how the result is handled.
Payvala provides a sandbox environment so you can develop and test your payment integration before handling real transactions. Sandbox behaviour mirrors the production API.
The following capabilities are available through the Payvala Payment API. Availability of specific features may depend on your access tier and approved use case.
Submit a structured payment request from your application to Payvala for processing.
Allows your application to trigger a payment transaction on behalf of a customer or business process.
Developers building checkout flows, order management systems, or payment-triggered workflows.
Query the current status of a submitted payment transaction at any point in its lifecycle.
Gives your application up-to-date visibility into whether a payment is pending, completed, or has failed.
Developers who need to display payment status to users or trigger downstream logic based on outcome.
Receive real-time notifications at your registered webhook endpoint when a transaction status changes.
Eliminates the need to poll for status updates by pushing events to your application as they occur.
Developers building event-driven payment workflows or needing real-time payment confirmation.
Associate payments with reference identifiers from your own system to maintain traceability across platforms.
Allows you to correlate Payvala transactions with orders, invoices, or records in your application.
Developers integrating payment into order management, accounting, or reconciliation workflows.
Receive machine-readable error codes and descriptions when a payment request cannot be completed.
Provides enough information to diagnose failures programmatically and decide on next steps.
Developers building robust payment flows that need to handle failures gracefully.
Submit payment requests with idempotency keys to prevent duplicate transactions caused by network retries.
Ensures that retrying a failed network request does not result in charging a customer more than once.
Developers building reliable payment integrations that must handle intermittent connectivity.
This section describes the conceptual flow of a payment transaction through Payvala. It is intended to help you understand the role each party plays before you write any code.
The typical payment flow is sequential — each stage depends on the previous one completing successfully. The flow below reflects the standard Payvala payment lifecycle.
The customer or counterparty initiates an action in your application that requires a payment — for example, confirming a purchase or submitting a form.
Your application collects the relevant payment details and prepares a payment request to send to the Payvala API. Your backend makes the API call — payment requests should never be initiated directly from a client device without a backend intermediary.
Payvala receives your payment request, validates the parameters, and routes the transaction for processing. Payvala returns an immediate acknowledgement containing a transaction identifier.
Payvala processes the payment through the appropriate payment infrastructure. The specifics of this step depend on the payment method and your approved configuration.
Payvala determines the outcome of the transaction — success, failure, or a pending state requiring further action. The result is made available through the status API and, if configured, via webhook notification.
Your application receives the payment result — either synchronously in the API response, asynchronously via webhook, or by polling the status endpoint — and completes the relevant business logic.
Payment requests must be made from your backend. Do not expose API credentials or make payment API calls directly from a browser or mobile client.
Not all payment results are available immediately. Some transactions may remain in a pending state while processing is completed. Design your application to handle asynchronous results.
Use idempotency keys for every payment initiation request to prevent duplicate charges in the event of a network interruption.
This is a conceptual overview. The exact internal architecture of the Payvala platform is not described here. Implementation details will be provided in your API reference documentation after access is approved.
The following steps describe what your application needs to do to complete a payment transaction using the Payvala API. This is a high-level guide to integration logic — not a code tutorial.
Gather the information required to initiate a payment: the amount, currency, a reference identifier from your system, and any other parameters required by the API. Validate this data in your application before sending it to Payvala.
All requests to the Payvala Payment API require authentication. Include your access token or API credentials in the request headers as specified in the authentication documentation.
Example request structure (placeholders only)
curl --request POST \
--url <API_BASE_URL>/<API_VERSION>/<PAYMENT_ENDPOINT> \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <UNIQUE_IDEMPOTENCY_KEY>' \
--data '<PAYMENT_REQUEST_PAYLOAD>'Send the authenticated request to the Payvala Payment API. If the request is well-formed and authenticated, Payvala will return an acknowledgement containing a transaction identifier. Store this identifier — you will need it to check the transaction status.
Depending on your integration, the payment result may be returned synchronously in the API response, or asynchronously via a webhook notification or status query. Your application should handle all three scenarios.
Some payment flows return a final result in the initial API response. Read the transaction status field to determine the outcome.
If you have registered a webhook endpoint, Payvala will POST a notification to your endpoint when the transaction status changes. Verify the webhook signature before processing.
You can query the transaction status endpoint at any time using the transaction identifier. Use this as a fallback if a webhook notification is not received within an expected window.
Once you have a confirmed payment result, complete the relevant logic in your application: fulfil the order, update a record, notify the customer, or trigger the next step in your process.
All Payment API endpoints are available in sandbox and production environments. Actual endpoint base URLs, credentials, and authentication values are provided through the developer portal after access is approved.
A Payvala payment transaction moves through a series of states from initiation to final resolution. Understanding these states will help you design application logic that correctly handles each stage.
The payment request has been received and accepted by Payvala. A transaction identifier has been assigned. Processing has not yet begun or is in progress.
Store the transaction ID at this point. It is your reference for all subsequent status queries.
Payvala is actively processing the transaction. The outcome is not yet determined. This state may be brief or may persist for some time depending on the payment method.
Do not update your records as completed at this stage. Wait for a terminal state.
The transaction is awaiting an external input or confirmation — for example, bank authorisation or customer action. This is an intermediate state.
Notify the customer that processing is underway if appropriate. Continue listening for status changes.
The payment has been successfully processed. This is a terminal success state.
Fulfil the order or trigger downstream logic only after reaching this state.
The payment could not be completed. The reason for failure will be provided in the transaction details. This is a terminal failure state.
Read the error information to determine whether a retry is appropriate or whether customer action is needed.
The payment was cancelled before completion — either by your application or through a supported cancellation mechanism. This is a terminal state.
Do not attempt to retry a cancelled transaction. Initiate a new transaction if payment is still required.
The exact state names and transitions in the Payvala API will be documented in your API reference. The states above are conceptual descriptions of the typical lifecycle — not confirmed API field values.
This section describes the integration approach for the Payvala Payment API at a conceptual level. Detailed endpoint documentation, request schemas, and response formats will be provided in your API reference after access is approved.
Before you can make any API calls, you need approved access to the Payvala Payment API. This includes sandbox credentials for development and testing. See the 'Request Payment API Access' section on this page.
After access is approved, you will receive API credentials. Store these in a secure secrets management system — not in source code, environment variables in version control, or client-side code.
Use the sandbox environment to develop and validate your integration before touching production. The sandbox mirrors the production API behaviour, allowing you to test all payment flows, error conditions, and webhook handling without processing real transactions.
Before moving to production, review your integration against the Payvala integration checklist. This typically includes verification of authentication handling, idempotency implementation, error handling coverage, and webhook security.
Once your integration has passed review and you have production credentials, you can deploy to production. Monitor your integration closely during the initial go-live period.
Your application must correctly handle payment results across all possible outcomes. Incomplete result handling is one of the most common sources of issues in payment integrations.
The transaction was completed successfully. You should fulfil the associated order or action and update your records.
The transaction was not completed. The reason for failure is provided in the response. Failure may be due to insufficient funds, a declined authorisation, or an error in the request.
The transaction is not yet resolved. Processing is underway or requires an external confirmation.
Payvala sends a POST request to your registered webhook endpoint when a transaction status changes.
The Payvala Payment API returns structured error responses that allow your application to programmatically understand and respond to failures. This section describes the error handling approach — specific error codes and messages are documented in your API reference.
400The request was rejected because it was malformed or contained invalid parameters. These errors indicate a problem in your integration that must be fixed before retrying.
Fix the request payload before retrying.
401The request could not be authenticated. Your credentials may be missing, expired, or invalid.
Verify and refresh your credentials before retrying.
403Your credentials are valid but your account is not authorised to perform the requested operation.
Review your approved API access scope. Contact Payvala support if you believe the restriction is in error.
404The requested resource — such as a transaction ID — does not exist or is not accessible with your credentials.
Verify the resource identifier in your request.
429Your application has exceeded the request rate limit. The response will include information about when you can retry.
Implement exponential backoff. Respect the retry-after header if present.
5xxAn unexpected error occurred on the Payvala platform. These are generally transient.
Retry with exponential backoff and idempotency keys. If the problem persists, contact Payvala support.
Payvala provides a sandbox environment that allows you to test your integration before processing real transactions. The sandbox API is functionally equivalent to production, but no real payments are processed.
Use the protected API documentation available after sign-in to access the full endpoint details, required headers, request structures, and expected response formats for each Payment operation.
Sandbox credentials are issued separately from production credentials. Always verify you are using sandbox credentials during development.
Sandbox access is included with your developer onboarding. See the 'Request Payment API Access' section if you have not yet received credentials.
Verify that your application correctly handles a completed transaction: records are updated, the customer is notified, and the next workflow step is triggered.
Verify that your application handles a declined or failed transaction: the order is not fulfilled, and the customer receives an appropriate message.
Verify that your application correctly handles the case where a result is not available synchronously. Check that polling and webhook handling work as expected.
Submit the same payment request twice with the same idempotency key. Verify that a duplicate transaction is not created and that your application handles the response correctly.
Trigger a transaction in the sandbox and verify that your webhook endpoint receives the expected notification. Confirm that signature verification works and that your handler returns a 200 response.
Intentionally submit malformed requests, invalid credentials, and rate-limited requests to verify that your error handling logic works correctly for each error category.
Simulate a network failure mid-request and verify that your retry logic using idempotency keys does not result in duplicate charges.
Do not use production credentials in the sandbox environment, and do not use sandbox credentials in production. Mixing environments can result in failed transactions or unintended charges.
Integrating a payment API carries security responsibilities. The following practices are expected of all Payvala Payment integrators.
All payment API requests must be made from your server-side backend. Never make payment requests from a browser, mobile app, or any client-side environment where the request can be intercepted or credentials exposed.
API credentials must be stored in a secure secrets management system. They must never appear in source code, version-controlled configuration files, build artifacts, or logs.
Every webhook notification must have its signature verified before you process its contents. This prevents attackers from sending fraudulent notifications to your webhook endpoint.
Your webhook endpoint and any other URL that receives Payvala data must be served over HTTPS with a valid TLS certificate.
Include a unique idempotency key with every payment initiation request. This ensures that network retries cannot result in a customer being charged more than once.
If Payvala supports scoped API credentials, configure your credentials to only have the permissions required for your integration. Do not use credentials with broader access than necessary.
Log transaction IDs, statuses, and timestamps for audit and debugging purposes. Do not log raw API credentials, full request payloads, or any sensitive cardholder or account data.
Set up monitoring and alerting for your payment integration. Track success rates, failure rates by error category, and webhook delivery latency. Unexpected changes in these metrics may indicate an integration problem or an active issue.
Before going live with real payments, verify that your integration meets the following criteria. This checklist is intended as a guide — Payvala may perform a technical review as part of the production access approval process.
Production credentials are stored securely and not exposed in code or logs. Token expiry and refresh are handled automatically. Sandbox and production credentials are kept strictly separate.
Payment requests are made from your backend only. Every payment initiation request includes a unique idempotency key. Your application stores the transaction ID returned by Payvala for every submitted payment.
Your application handles synchronous success, failure, and pending results. Your webhook endpoint is live, publicly accessible over HTTPS, and signature verification is implemented. Webhook events are acknowledged with a 200 response before business logic is processed. Duplicate webhook deliveries are handled idempotently. A status polling fallback is implemented for cases where webhook delivery fails.
Your application handles all HTTP error categories (400, 401, 403, 404, 429, 5xx). Retryable errors use exponential backoff. Non-retryable errors surface appropriate feedback to users. Error details are logged with transaction references for debugging.
Transaction success and failure rates are monitored. Alerts are configured for unusual failure rates or error spikes. Webhook delivery failures are logged and monitored.
Webhook endpoint is served over HTTPS. Webhook signatures are verified on every incoming request. No sensitive data is logged. Credentials follow a rotation policy.
The Payvala Payment API is available to approved developers and businesses. To get started, you need to request access through the Payvala developer portal.
Sandbox access is granted during the standard onboarding process, before production approval. You can build and fully test your integration in the sandbox environment before any production review takes place.
Once your sandbox integration is complete and meets the production readiness criteria, submit a production access request. After production access is approved, you will receive production credentials and can begin processing real payments.
If you do not already have a Payvala developer account, register at the Payvala developer portal. Your account is required to manage API credentials and access API documentation.
Navigate to the Payment service page in the developer portal and submit an access request. You will be asked to provide information about your use case and your intended integration.
Payvala will review your request. During this period, a member of the Payvala team may contact you for additional information or a technical discussion.
Once your request is approved, you will receive sandbox API credentials and access to the full Payment API reference documentation. You can begin building and testing your integration immediately.
Build and test your integration in the sandbox environment. When you are satisfied that your integration is complete and meets the production readiness criteria, submit a production access request.
After production access is approved, you will receive production credentials. Deploy your integration and begin processing real payments.
No. Sandbox access is granted during the standard onboarding process, before production approval. You can build and fully test your integration in the sandbox environment without any real payments being processed. Production access is a separate review step.
Idempotency keys are strongly recommended for all payment initiation requests and should be treated as mandatory in any production integration. Without them, a network interruption mid-request could result in duplicate transactions. The Payvala API supports idempotency keys to prevent this.
Not necessarily. Some payment flows return a final result synchronously, while others may transition through a pending state before reaching a terminal outcome. You should design your integration to handle asynchronous results via webhook notifications and implement a status polling fallback.
Webhooks are not strictly required for all integrations, but they are strongly recommended for production use. Without a webhook endpoint, your application must poll the status API to determine the outcome of transactions that do not resolve synchronously. A reliable webhook implementation reduces latency and API load.
Yes, as long as you use the same idempotency key as the original request. Payvala will recognise the duplicate and return the same response without creating a new transaction. Never retry a payment request with a new idempotency key unless you intend to create a new transaction.
No. Payment API calls must be made from your backend. Calling the Payment API directly from a client application would expose your API credentials. Your frontend should communicate with your backend, which in turn communicates with the Payvala API.
The full list of Payment API error codes and their meanings is available in the API reference documentation, which is provided after your access request is approved. Error codes are structured to allow programmatic handling of different failure categories.
The sandbox is designed to mirror the production API in terms of request/response structure, error handling, and webhook behaviour. However, sandbox transactions do not involve real payment networks or real funds. Some edge cases involving live payment network responses may not be fully reproducible in the sandbox.
The Payvala sandbox provides mechanisms to simulate different payment outcomes, including failures and declines. The specific approach — whether through special test parameters, test account identifiers, or simulator tools — will be documented in your API reference after access is approved.
Design your webhook handler to be idempotent — processing the same event twice should not produce different side effects than processing it once. You can use the transaction ID or event ID included in the notification to check whether you have already processed a given event before acting on it.