# Basic Synchronous Integration

**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`