NAV
php csharp java

Prerequisites

This protocol can be used with the following payment methods: Yekpay Payment, Yekpay Payment Verify The following communication protocols should already be in place between merchant (or PSP) and Yekpay:

PR -- Payment Request, calling request method with necessary data to initiate a transaction. If the data is in the correct/expected format, the customer is redirected to payment page, where he has to enter the SHETAB or Master/Visa card data.

VP -- Verify Payment, calling verify method with necessary data to verify a transaction. If the data is in the correct/expected format, transaction status changed from pending to complete.

ER -- Exchange Rate, calling exchange method with necessary data to get exchange rate. If the data is in the correct/expected format, last rate between two currencies are showed.

Overview

This protocol can be used by any third party to check order information and approve payments initiated by our merchants.

First of all, Yekpay must receive a PR request with the buyer redirected from the merchant's website to initiate a new order.

The payment method may or may not be specified in the PR request parameters.

The buyer finishes the order registration process on Yekpay's side and, depending on the payment method implementation, he may be redirected to a third party/acquirer to make the payment.

Before charging the buyer, the acquirer may check the order information in Yekpay's system.

After the acquirer charges the buyer, it must also inform Yekpay about this operation by using the pay protocol so that Yekpay will update its order status and send the IPN to the merchant.

The "request" and "verify" requests are made server to server.

Diagram

overview,img

1- Customer Checkout

Description

When customer is in your checkout page, you must prepare basic (first name, last name, mobile email)and billing (address, country, city, postal code) info, to have a fast and secure payment.

Diagram

Customer Checkout,img

2- Payment Request

URL

https://gate.yekpay.com/api/payment/request

Sandbox URL

https://api.yekpay.com/api/sandbox/request

Method

POST

Inputs

<?php
/* Currency Codes
978 = EUR
364 = IRR
784 = AED
826 = GBP
949 = TRY
*/
try
{
    $client = new SoapClient( 'https://gate.yekpay.com/api/payment/server?wsdl', array( 'encoding' => 'UTF-8' ) );
    $result = $client->request($p = (object)array(
            'merchantId'       => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
            'fromCurrencyCode' => 364, // IRR
            'toCurrencyCode'   => 978, // EUR
            'email'            => '[email protected]',
            'mobile'           => '09123456789',
            'firstName'        => 'Name',
            'lastName'         => 'Family',
            'address'          => 'No.1, Second.St, Third.Sq',
            'postalCode'       => '1234567890',
            'country'          => 'Iran',
            'city'             => 'Tehran',
            'description'      => 'Payment Description',
            'amount'           => number_format(1000000,2), // it means the price is 1.000.000 IRR in our site , and we want to pay the invoice with euro (about 6-7 euro)
            'orderNumber'      => time(),
            'callback'         => 'http://www.YOUR-SITE.com/yekpay/verify.php',
        ));
    $object = json_decode($result);
    if ( $object->Code == 100 )
    {
        $Payment_URL = 'https://gate.yekpay.com/api/payment/start/' . $object->Authority;
        header('location: ' . $Payment_URL);
    }
    else
    {
        echo('YekPay Error : ' . $object->Description);
    }
}
catch (exception $ex)
{
    var_dump($ex);
}
using System;
using System.Configuration;
using System.Data;
using System.Linq;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Xml.Linq;

public class request_response
{
    public string Code;
    public string Authority;
    public string Description;
}

public partial class _Default : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {

    }
    protected void btnPay_Click(object sender, EventArgs e)
    {
        try
        {
            string paramz = "";
            paramz = "merchantId=" + ConfigurationManager.AppSettings["merchant"];
            paramz += "&fromCurrencyCode=" + ConfigurationManager.AppSettings["fcc"];
            paramz += "&toCurrencyCode=" + ConfigurationManager.AppSettings["tcc"];
            paramz += "&email=" + txtEmail.Text;
            paramz += "&mobile=" + txtMobile.Text;
            paramz += "&firstName=" + txtFirstName.Text;
            paramz += "&lastName=" + txtLastName.Text;
            paramz += "&address=" + txtAddress.Text;
            paramz += "&postalCode=" + txtZipCode.Text;
            paramz += "&country=" + txtCountry.Text;
            paramz += "&city=" + txtCity.Text;
            paramz += "&description=" + txtDescription.Text;
            paramz += "&amount=" + Convert.ToDecimal(txtAmount.Text);
            paramz += "&orderNumber=" + new Random().Next();
            paramz += "&callback=" + ConfigurationManager.AppSettings["callback"];
            clsRestAPI api = new clsRestAPI();
            string res = api.LoadWebSite("https://gate.yekpay.com/api/payment/request", paramz);
            System.Web.Script.Serialization.JavaScriptSerializer json = new System.Web.Script.Serialization.JavaScriptSerializer();
            request_response result = json.Deserialize<request_response>(res);
            if (result.Code == "100")
            {
                string Payment_URL = "https://gate.yekpay.com/api/payment/start/" + result.Authority;
                Response.Redirect(Payment_URL);
            }
            else
            {
                lblError.Text = "Error : " + result.Description;
            }
        }
        catch (Exception ex)
        {
            lblError.Text = "Error : " + ex.Message;
        }

    }
}
Public Class request_response
    Public Code As String
    Public Authority As String
    Public Description As String
End Class

Partial Class _Default
    Inherits System.Web.UI.Page

    Protected Sub btnPay_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles btnPay.Click
        Try
            Dim params As String = ""
            params = "merchantId=" & ConfigurationManager.AppSettings("merchant")
            params &= "&fromCurrencyCode=" & ConfigurationManager.AppSettings("fcc")
            params &= "&toCurrencyCode=" & ConfigurationManager.AppSettings("tcc")
            params &= "&email=" & txtEmail.Text
            params &= "&mobile=" & txtMobile.Text
            params &= "&firstName=" & txtFirstName.Text
            params &= "&lastName=" & txtLastName.Text
            params &= "&address=" & txtAddress.Text
            params &= "&postalCode=" & txtZipCode.Text
            params &= "&country=" & txtCountry.Text
            params &= "&city=" & txtCity.Text
            params &= "&description=" & txtDescription.Text
            params &= "&amount=" & Convert.ToDecimal(txtAmount.Text)
            params &= "&orderNumber=" & New Random().Next
            params &= "&callback=" & ConfigurationManager.AppSettings("callback")
            Dim api As New clsRestAPI
            Dim res As String = api.LoadWebSite("https://gate.yekpay.com/api/payment/request", params)
            Dim json As New System.Web.Script.Serialization.JavaScriptSerializer
            Dim result As request_response = json.Deserialize(Of request_response)(res)
            If result.Code = 100 Then
                Dim Payment_URL As String = "https://gate.yekpay.com/api/payment/start/" & result.Authority
                Response.Redirect(Payment_URL)
            Else
                lblError.Text = "Error : " & result.Description
            End If
        Catch ex As Exception
            lblError.Text = "Error : " & ex.Message
        End Try
    End Sub

End Class

PARAMETERS DESCRIPTION EXAMPLE
merchantId 32-digits merchant code XXXXXXXXXXXXXXXXXXXX
amount Amount of your order (with Decimal (15,2)format) 799.00
fromCurrencyCode Origin currency code 978
toCurrencyCode Destination currency code 364
orderNumber Unique order id for each merchant 125548
callback Callback URL of merchant website https://example.com/callback.php
firstName First name of your customer John
lastName Last name of your customer Doe
email Email of your customer [email protected]
mobile Mobile of your customer +44123456789
address Billing address Alhamida st Al ras st
postalCode Billing postal code 64785
country United Arab Emirates Billing country
city Billing city Dubai
description Name of your products or your services Apple mac book air 2017

Diagram

Payment Request,img

3- Payment Authorization

Description

After calling request method you get response in JSON that has Code, Description and Authority fields, if you get Code 100, you can go to next step.

Output Codes Table

CODE DESCRIPTION AUTHORITY
-1 The parameters are incomplete 0
-2 Merchant code is incorrect 0
-3 Merchant code is not active 0
-4 Currencies is not valid 0
-5 Maximum/Minimum amount is not valid 0
-6 Your IP is restricted 0
-7 Order id must be unique 0
-100 Unknown error 0
100 Success XXXXXXXXXXXX

Diagram

Payment Authorization,img

4- Start Payment

Description

If you get Success message in previous step, you can start payment by calling this URL with authority that you get in request method:

URL

https://gate.yekpay.com/api/payment/start/{AUTHORITY}

Sandbox URL

https://api.yekpay.com/api/sandbox/payment/{AUTHORITY}

Diagram

Start Payment,img

5- Payment Processing

Description

In this step we process payment (SHETAB or Credit Card) with our Gateways, 9 currencies supported that you can see details in below appendices.

Please consider that all of gateways support 3D-secure, and your customer cards must support this standard.

After Transaction completed (with or without errors), we send Authority and Status with POST method in your callback URL that you sent in request method.

Diagram

Payment Processing,img

6- Payment Verification

URL

https://gate.yekpay.com/api/payment/verify

Sandbox URL

https://api.yekpay.com/api/sandbox/verify

Method

POST

Inputs

PARAMETERS DESCRIPTION EXAMPLE
merchantId 32-digits merchant code XXXXXXXXXXXXXXXXXXXX
authority Authority code that you get before in request method 115162456765

Diagram

<?php
try
{
    if ( isset( $_GET['success'] ) && $_GET['success'] == '1' )
    {
        $Authority  = $_GET['authority'];
        $client = new SoapClient( 'https://gate.yekpay.com/api/payment/server?wsdl', array( 'encoding' => 'UTF-8' ) );
        $result = $client->verify($p = (object)array(
                'merchantId' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
                'authority'  => $Authority,
            ));
        $object = json_decode($result);
        if ( $object->Code == 100 )
        {
            echo('YekPay Payment Completed . RefNum : ' . $Authority);
        }
        else
        {
            echo('YekPay Error : ' . $object->Description);
        }
    }
    else
    {
        echo('YekPay Payment Cancelled');
    }
}
catch (exception $ex)
{
    var_dump($ex);
}
using System;
using System.Collections;
using System.Configuration;
using System.Data;
using System.Linq;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Xml.Linq;
public class verify_response
{
    public string Code;
    public string Authority;
    public string Description;
}
public partial class Verify : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        try
        {
            if (true || Request.QueryString["success"] == "1")
            {
                string paramz = "";
                paramz = "merchantId=" + ConfigurationManager.AppSettings["merchant"];
                paramz += "&authority=" + Request.QueryString["authority"];
                clsRestAPI api = new clsRestAPI();
                string res = api.LoadWebSite("https://gate.yekpay.com/api/payment/verify", paramz);
                System.Web.Script.Serialization.JavaScriptSerializer json = new System.Web.Script.Serialization.JavaScriptSerializer();
                verify_response result = json.Deserialize<verify_response>(res);
                if (result.Code == "100")
                {
                    lblResult.Text = "Payment Completed";
                }
                else
                {
                    lblResult.Text = "Error : " + result.Description;
                }
            }
            else
            {
                lblResult.Text = "Payment Cancelled";
            }
        }
        catch (Exception ex)
        {
            lblResult.Text = "Error : " + ex.Message;
        }
    }
}

Public Class verify_response
    Public Code As String
    Public Authority As String
    Public Description As String
End Class
Partial Class Verify
    Inherits System.Web.UI.Page
    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        Try
            If 1 OrElse Request.QueryString("success") = 1 Then
                Dim params As String = ""
                params = "merchantId=" & ConfigurationManager.AppSettings("merchant")
                params &= "&authority=" & Request.QueryString("authority")
                Dim api As New clsRestAPI
                Dim res As String = api.LoadWebSite("https://gate.yekpay.com/api/payment/verify", params)
                Dim json As New System.Web.Script.Serialization.JavaScriptSerializer
                Dim result As verify_response = json.Deserialize(Of verify_response)(res)
                If result.Code = 100 Then
                    lblResult.Text = "Payment Completed"
                Else
                    lblResult.Text = "Error : " & result.Description
                End If
            Else
                lblResult.Text = "Payment Cancelled"
            End If
        Catch ex As Exception
            lblResult.Text = "Error : " & ex.Message
        End Try
    End Sub
End Class

Payment Verification,img

7- Payment Information

Description

In this step you get response from verify method in JSON format, if the Code is equal to “100”, your verification request is successful and you will get other information like Reference, Gateway , OrderNo and Amount.

Output Codes Table

CODE DESCRIPTION REFERENCE
-1 The parameters are incomplete 0
-2 Merchant code is incorrect 0
-3 Merchant code is not active 0
-8 Currencies is not valid 0
-9 Maximum/Minimum amount is not valid 0
-10 Your IP is restricted 0
-100 Unknown error 0
100 Success XXXXXXXXXXXX

Diagram

Payment Information,img

Test Cards

CARD NAME CARD NUMBER EXPIRATION DATE CVC DESCRIPTION
John Doe 5269552233334445 2022/12 000 Decline
David Doe 4022771122223334 2022/12 000 Success

Appendix A: Currencies

Currency Name Code
EUR Euro 978
IRR Iranian Rial 364
CHF Switzerland Franc 756
AED United Arab Emirates Dirham 784
CNY Chinese Yuan 156
GBP British Pound 826
JPY Japanese 100 Yens 392
RUB Russian Ruble 643
TRY Turkish New Lira 494