Basic Synchronous Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Last Updated: May 2025

1. Overview

Our Basic Synchronous Integration provides a simple way to receive immediate, client-side feedback after a payment is processed. When you provide return_urls during the payment initiation (see our API Reference for details on how to set this), the user's browser will be redirected to this URL upon completion (success or failure) of the payment process.

The payment_reference and the payment_status of the payment will be appended to your return_url as query parameters. This allows you to quickly update your UI and guide the user to the next appropriate step in their journey (e.g., an order confirmation page or a payment failed page).

Important Note: While this method offers a quick way to enhance user experience, it is not recommended as the sole mechanism for tracking payment status or fulfilling orders. For robust and reliable payment status updates, we strongly recommend implementing webhooks. Webhooks are server-to-server, more resilient to user actions (like closing the browser prematurely), and provide a more secure way to handle critical business logic.

2. How It Works

1. Payment Initiation: When initiating a payment via our API, you include a return_urls parameters pointing to pages on your application.
   • Example: https://yourshop.com/payment-confirmation
2. Payment Processing: The user is guided through the payment flow on our platform.
3. Redirection: Once the payment is processed (successfully, fails, or reaches another terminal state), our system redirects the user's browser to the return_url you provided.
4. Parameters Appended: We append the payment_reference and payment_status to this URL as query string parameters.
   • Example Redirect: https://yourshop.com/payment-confirmation?payment_reference=cpay_1J2xY02eZvKYlo2ClK8g9s7d&payment_status=SUCCESS

3. Implementation

To use the Return URL redirect feature:

1. Provide return_urls: Ensure you are passing a valid, absolute URL in the return_urls parameter during the API call that initiates the payment. Refer to the specific API endpoint documentation in our API Reference.

2. Create a Handler Page: Set up an endpoint/page on your server that corresponds to the return_urls. This page will:

   • Receive the incoming GET request.
   • Parse the payment_reference and payment_status from the URL query parameters.
   • Optionally, use the payment_reference to fetch more detailed payment information from your backend (which should have ideally been updated by a webhook or an API poll).
   • Display an appropriate message to the user (e.g., "Payment Successful!", "Payment Failed, please try again.").
   • Guide the user to the next step (e.g., view order details, retry payment).

4. Return URL Parameters

The following parameters will be appended to your return_url:

• payment_reference (string):

  • Description: The unique identifier or reference for the payment transaction.
  • Example: pay_1J2xY02eZvKYlo2ClK8g9s7d

• payment_status (string):

  • Description: The latest known status of the payment at the time of redirection.
  • Possible Values:
    • SUCCESS: The payment was completed successfully.
    • FAILED: The payment attempt failed.
    • PENDING: The payment is still pending (less common for synchronous redirects, but possible for some payment methods).
    • CANCELLED: The payment was cancelled by the user.
    • *(Note: For a comprehensive list of all possible status codes, please refer to our API Reference

5. Example

Let's say your return_url is https://www.your-e-store.com/checkout/complete.

If the payment is successful: The user will be redirected to: https://www.your-e-store.com/checkout/success?payment_reference=pay_aBcDeFgHiJkLmNoPqRsTuV&payment_status=SUCCESS

If the payment fails: The user will be redirected to: https://www.your-e-store.com/checkout/failure?payment_reference=pay_aBcDeFgHiJkLmNoPqRsTuV&payment_status=FAILED