NAV
php csharp java

پیش نیازها

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

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

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

نمای کلی

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

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

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

نمودار

overview,img

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

توضیحات

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

نمودار

Customer Checkout,img

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

آدرس اصلی

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

آدرس سندباکس

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

متد

POST

ورودی

<?php
/* Currency Codes
978 = EUR
364 = IRR
784 = AED
826 = GBP
949 = TRY
*/
try
{
    $client = new SoapClient( 'https://gate.ypsapi.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/ypsapi/verify.php',
        ));
    $object = json_decode($result);
    if ( $object->Code == 100 )
    {
        $Payment_URL = 'https://gate.ypsapi.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.ypsapi.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.ypsapi.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.ypsapi.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.ypsapi.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 ID XXXXXXXXXXXXXXXXXXXX
amount Order amount (In Decimal (15,2) format) 1799.20
fromCurrencyCode Origin currency code 978
toCurrencyCode Destination currency code 978
orderNumber Unique order id for each transaction 125548
callback Merchant Callback URL https://example.com/callback.php
firstName Customer first name John
lastName Customer last name Doe
email Customer email address [email protected]
mobile Customer mobile number +44123456789
address Customer address Alhamida st Al ras st
postalCode Customer postal code 64785
country Customer country Billing country
city Customer city Dubai
description Name of your products or your services Apple mac book air 2017

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

توضیحات

‫پس از فراخوانی متد درخواست، پاسخی با فرمت JSON محتوی Code, Description و Authority دریافت خواهید کرد. در صورت دریافت code=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.ypsapi.com/api/payment/start/{AUTHORITY}

آدرس سندباکس

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

نمودار

Start Payment,img

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

توضیحات

در این مرحله، پرداخت‌کننده تراکنش خود را در درگاه پرداخت انجام می‌دهد و پس از آن (چه پرداخت موفق باشد یا ناموفق) به آدرس callback شما هدایت می‌شود. دو پارامتر Status و Authority به‌صورت POST به آدرس callback ارسال خواهند شد.

نمودار

Payment Processing,img

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

آدرس اصلی

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

آدرس سندباکس

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

متد

POST

ورودی

<?php
try
{
    if ( isset( $_GET['success'] ) && $_GET['success'] == '1' )
    {
        $Authority  = $_GET['authority'];
        $client = new SoapClient( 'https://gate.ypsapi.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.ypsapi.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.ypsapi.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

کارت های تست

CARD NAME CARD NUMBER EXPIRATION DATE CVC DESCRIPTION
John Doe 5269552233334445 2028/12 000 Unsuccessful Transaction
David Doe 4022771122223334 2028/12 000 Successful Transaction