NAV
php csharp java

پیش نیازها

این سند حاوی پروتکل هایی است که از متدهای پرداخت به شرح ذیل استفاده می کند: متد پرداخت یک پی: متد پرداخت یک پی، پروتکل هایی را که مابین کسب و کارها ) یا ارایه دهندگان خدمات پرداخت( و یک پی هستند،تایید می کند:

Payment Request متد درخواست پرداخت، تراکنش را با داده های کاربر شروع می کند. اگر داده ها در وضعیت صحیح و یا مورد قبول باشند، مشتری به صفحه پرداخت ارجاع داده می شود تا بتواند اطلاعات کارت شتاب یا کارت بین المللی خود را وارد کند.

Verify Payment از متد تایید پرداخت، بلافاصله پس از متد درخواست و جهت تایید تراکنش استفاده می شود. اگر داده ها و عملیات پرداخت در وضعیت صحیح و یا مورد قبول باشد، وضعیت تراکنش از در حالت انتظار به تایید، تغییر می کند.

Exchange Rate از این متد برای تبدیل ارز بین دو واحد مختلف استفاده می شود. اگر داده ها در وضعیت صحیح و یا مورد قبول باشد، آخرین نرخ بین دو ارز نمایش داده خواهد شد.

نمای کلی

پروتکل درگاه پرداخت یک پی می تواند توسط هرگونه شخص ثالثی برای بررسی اطلاعات سفارش و تایید شروع پرداخت ها مورد استفاده قرار گیرد.

در ابتدا، یک پی باید درخواست Payment Request را با ارجاع خریدار به وبسایت کسب و کار برای ثبت سفارش جدید دریافت کند.

زمانی که خریدار فرآیند ثبت درخواست را از سمت یک پی به پایان می رساند، بسته به نحوه پیاده سازی متد پرداخت، ممکن است برای تکمیل پرداخت به صفحه شخص ثالث یا فروشنده فراخوانده شود.

همچنین فروشنده می تواند اطلاعات سفارش را قبل از شارژ خریدار در سیستم یک پی بررسی و متد Payment Verify را صدا کند.

نمودار

overview,img

1.تسویه حساب مشتری

توضیحات

زمانی که مشتری در صفحه تسویه حساب سایت شما باشد، باید امکان ورود اطلاعات هویتی )از قبیل نام، نام خانوادگی، شماره موبایل و ایمیل( و اطلاعات صورتحساب )از قبیل آدرس، کشور، شهر و کدپستی( را داشته باشد تا بتواند پرداختی سریع و امن انجام دهد.

نمودار

Customer Checkout,img

2.درخواست پرداخت

آدرس اصلی

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

آدرس سندباکس

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

متد

POST

ورودی

<?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

نمودار

Payment Request,img

3.اعتبار سنجی تراکنش

توضیحات

‫پس از فراخوانی متد درخواست، پاسخی با فرمت JSON محتوی کد، توضیحات و فیلدهای اعتبارسنجی دریافت خواهید کرد. در صورت دریافت کد عدد 100 ، می توانید وارد مرحله بعد شوید.‬

کدهای خروجی

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

نمودار

Payment Authorization,img

4.شروع فرآیند تراکنش

توضیحات

اگر در مرحله قبل پیغام "موفقیت آمیز" دریافت کرده اید، می توانید با کد Authority که در متد درخواست دریافت کردهاید و فراخوانی آدرس زیر، فرآیند پرداخت را شروع کنید.

آدرس اصلی

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

آدرس سندباکس

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

نمودار

Start Payment,img

5.پردازش تراکنش

توضیحات

در این مرحله فرآیند تراکنش )توسط کارت شتاب یا کارت بین المللی( توسط درگاه پرداخت ما پردازش می شود. اطلاعات ارزهای قابل استفاده ) 9 ارز ی که توسط ما پشتیبانی می شون د(، در ضمیمه های بعد در دسترس خواهند بود. لطفا در نظر داشته باشید که تمامی درگاه های پرداخت بین المللی ما از گزینه 3 D-secure پشتیبانی می کنند و این گزینه نیز باید برای کارت مشتری شما فعال باشد.

زمانی که فرآیند تراکنش تکمیل شد، )با یا بدون خطا( اعتبارسنجی و وضعیت تراکنش با متد POST به آدرسی که در متد درخواست توسط شما فرستاده شده بود، ارسال می شود.

نمودار

Payment Processing,img

6.تاکید تراکنش

آدرس اصلی

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

آدرس سندباکس

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

متد

POST

ورودی

<?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
PARAMETERS DESCRIPTION EXAMPLE
merchantId 32-digits merchant code XXXXXXXXXXXXXXXXXXXX
authority Authority code that you get before in request method 115162456765

نمودار

Payment Verification,img

7.اطلاعات تراکنش

توضیحات

در این مرحله پاسخی از سمت متد تایید تراکنش با فرمت JSON دریافت خواهید کرد، که اگر این کد برابر " 100 " باشد، درخواست تایید شما موفقیت آمیز بوده اطلاعاتی مانند Reference ، Gateway, OrderNo و Amount دریافت خواهید کرد.

کدهای خروجی

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

نمودار

Payment Information,img

ضمیمه اول: واحد های پولی

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