Version: v3

Payment Bridge Documentation

The Payment Bridge API provides a seamless and secure way to initiate and manage online payment transactions. Designed for flexibility and ease of integration, it allows merchants to create payment links, redirect customers to a hosted payment page, and receive asynchronous notifications upon payment completion.

Whether you are building a mobile app or a web platform, the API enables quick integration with minimal effort while ensuring a reliable and user-friendly payment experience. With built-in support for success/fail redirects and real-time payment status updates, the Payment Bridge API simplifies your payment workflows and enhances the overall customer journey.

Authentication

Every request must include your API key (and the region code) in the HTTP headers:

ApiKey: YOUR_API_KEY
H-Region-Code: TR

Note: The ApiKey is obtained from the Partner Portal. If you do not have access to the Partner Portal, please contact the support team.

Payment Flow

1) Create the Payment Link

Send a request to create a payment link. The response contains a paymentUrl that should be consumed by your end-user to initiate the payment process. The link redirects the user to the hosted payment page.

2) Redirect the User to the Payment Link

Redirect the user to the URL obtained in step 1. After the user completes the payment process, the browser will be redirected to the successURL or failURL provided when the link was created. If those URLs were not provided, the browser stays on the payment result page.

3) Listen for Asynchronous Notifications

After the payment is completed and all verification steps are done, a notification is sent to the notifyURL provided when the link was created. You may also query the payment status by calling the QueryPaymentLink endpoint.

Sample Code — Create Payment Link

Below is an example ASP.NET Core controller that creates a payment link:

using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Newtonsoft.Json;

public class PaymentBridgeController : ControllerBase
{
    private readonly IHttpClientFactory _clientFactory;
    private readonly IConfiguration _config;
    private readonly IDatabaseService _db; // your DB access service

    public PaymentBridgeController(IHttpClientFactory clientFactory,
                                   IConfiguration config,
                                   IDatabaseService db)
    {
        _clientFactory = clientFactory;
        _config = config;
        _db = db;
    }

    [HttpPost("createPayment")]
    public async Task<IActionResult> CreatePayment(
        [FromForm] string productid,
        [FromForm] string accountid)
    {
        var product = await _db.GetProductByIdAsync(productid);
        if (product == null)
        {
            _db.LogError($"Invalid Product ID: {productid}");
            return BadRequest("Invalid Product ID");
        }

        var account = await _db.GetAccountByIdAsync(accountid);
        if (account == null)
        {
            _db.LogError($"Invalid Account ID: {accountid}");
            return BadRequest("Invalid Account ID");
        }

        var requestData = new
        {
            Email        = account.Email,
            iFrame       = 1,
            FailURL      = "https://yourdomain.com/failurl",
            OrderID      = HttpContext.Session.GetString("strAccountID"),
            NotifyURL    = "https://yourdomain.com/notifyurl",
            ProductID    = product.ProductID,
            SuccessURL   = "https://yourdomain.com/successurl",
            PhoneNumber  = "+905468469854",
            ProductName  = $"{_config["SITE:NAME"]} - {product.ProductName}",
            TotalAmount  = product.Cost,
            ProductImage = "https://yourdomain.com/productimageurl"
        };

        var client = _clientFactory.CreateClient();
        client.DefaultRequestHeaders.Add("Accept", "application/json");
        client.DefaultRequestHeaders.Add("ApiKey", _config["PAYMENT_BRIDGE_APIKEY"]);
        client.DefaultRequestHeaders.Add("H-Region-Code", "TR"); // TR is the only accepted region for now

        var jsonBody = JsonConvert.SerializeObject(requestData);
        var requestContent = new StringContent(jsonBody, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            "https://YOUR_API_HOST/PaymentBridge/create-link",
            requestContent);

        if (!response.IsSuccessStatusCode)
        {
            var error = await response.Content.ReadAsStringAsync();
            return BadRequest($"API Error: {error}");
        }

        var result = await response.Content.ReadAsStringAsync();
        return Content(result, "application/json");
    }
}

Sample Code — Notification Callback

This is a mock-up endpoint that illustrates how to handle the asynchronous payment notification on your side. The real notification will be sent to the notifyURL you supplied when creating the link.

using System;
using System.Text.Json;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;

public class PaymentBridgeController : ControllerBase
{
    private readonly IConfiguration _config;
    private readonly IDatabaseService _db;

    public PaymentBridgeController(IConfiguration config, IDatabaseService db)
    {
        _config = config;
        _db = db;
    }

    [HttpPost]
    public IActionResult ReceiveNotification([FromBody] NotificationData data)
    {
        var ok = new { success = true, message = "Notification received" };

        // Ignore unsuccessful payments — acknowledge so the platform stops retrying.
        if (data.Status != true) return Ok(ok);

        // Validate the API key.
        var apiKey = Request.Headers["ApiKey"].ToString();
        if (apiKey != _config["PAYMENT_BRIDGE_APIKEY"])
            return Ok(new { success = false, message = "Invalid ApiKey" });

        // Validate the product reference.
        var product = _db.GetProductByIdAsync(data.ProductID);
        if (product == null)
        {
            LogError("Product not found", data);
            return Ok(new { success = false, message = "Product not found" });
        }

        // Idempotency — ignore duplicate notifications for the same payment.
        var existingPayment = _db.GetPaymentById(data.PaymentGuid);
        if (existingPayment != null) return Ok(ok);

        // Persist the payment log.
        var insertLogRows = _db.Execute("INSERT INTO PAYMENTLOGS ...");
        if (insertLogRows <= 0)
        {
            LogError("Cannot INSERT PAYMENTLOGS", data);
            return Ok(new { success = false, message = "DB error history" });
        }

        // Update the user's balance / order state.
        var updateAccountRows = _db.Execute("UPDATE ACCOUNT SET Balance = Balance + ...");
        if (updateAccountRows <= 0)
        {
            LogError("Cannot UPDATE ACCOUNT", data);
            return Ok(new { success = false, message = "DB error history" });
        }

        return Ok(ok);
    }

    private void LogError(string message, NotificationData data)
    {
        Console.Error.WriteLine($"{message} - Data: {JsonSerializer.Serialize(data)}");
    }
}

Best Practices

• Idempotency: the platform may retry the notification — always check whether the payment has already been processed before applying side-effects.
• Validate the ApiKey header on every notification you receive.
• Always respond with HTTP 200 to a notification you have processed (even when the payment was unsuccessful) to stop retries.
• Use the QueryPaymentLink endpoint as a safety net to reconcile payments in case a notification was missed.