پیش نیازها
این سند حاوی پروتکل هایی است که از متدهای پرداخت به شرح ذیل استفاده می کند: متد پرداخت یک پی: متد پرداخت یک پی، پروتکل هایی را که مابین کسب و کارها ( یا ارایه دهندگان خدمات پرداخت) و یک پی هستند،تایید می کند:
Payment Request متد درخواست پرداخت، تراکنش را با داده های کاربر شروع می کند. اگر داده ها در وضعیت صحیح و یا مورد قبول باشند، مشتری به صفحه پرداخت ارجاع داده می شود تا بتواند اطلاعات کارت بین المللی خود را وارد کند.
Verify Payment از متد تایید پرداخت، بلافاصله پس از متد درخواست و جهت تایید تراکنش استفاده می شود. اگر داده ها و عملیات پرداخت در وضعیت صحیح و یا مورد قبول باشد، وضعیت تراکنش از در حالت انتظار به تایید، تغییر می کند.
نمای کلی
پروتکل درگاه پرداخت یک پی می تواند توسط هرگونه شخص ثالثی برای بررسی اطلاعات سفارش و تایید شروع پرداخت ها مورد استفاده قرار گیرد.
در ابتدا، یک پی باید درخواست Payment Request را با ارجاع خریدار به وبسایت کسب و کار برای ثبت سفارش جدید دریافت کند.
زمانی که خریدار فرآیند ثبت درخواست را از سمت یک پی به پایان می رساند، بسته به نحوه پیاده سازی متد پرداخت، ممکن است برای تکمیل پرداخت به صفحه شخص ثالث یا فروشنده فراخوانده شود.
نمودار
1.تسویه حساب مشتری
توضیحات
زمانی که مشتری در صفحه تسویه حساب سایت شما باشد، باید امکان ورود اطلاعات هویتی (از قبیل نام، نام خانوادگی، شماره موبایل و ایمیل) و اطلاعات صورتحساب (از قبیل آدرس، کشور، شهر و کدپستی) را داشته باشد تا بتواند پرداختی سریع و امن انجام دهد.
نمودار
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 |
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 |
نمودار
4.شروع فرآیند تراکنش
توضیحات
اگر در مرحله قبل پیغام "موفقیت آمیز" دریافت کرده اید، می توانید با کد Authority که در متد درخواست دریافت کرده اید و فراخوانی آدرس زیر، فرآیند پرداخت را شروع کنید.
آدرس اصلی
https://gate.ypsapi.com/api/payment/start/{AUTHORITY}
آدرس سندباکس
https://api.ypsapi.com/api/sandbox/payment/{AUTHORITY}
نمودار
5.پردازش تراکنش
توضیحات
در این مرحله، پرداختکننده تراکنش خود را در درگاه پرداخت انجام میدهد و پس از آن (چه پرداخت موفق باشد یا ناموفق) به آدرس callback شما هدایت میشود. دو پارامتر Status و Authority بهصورت POST به آدرس callback ارسال خواهند شد.
نمودار
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 |
نمودار
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 |
نمودار
ضمیمه اول: واحد های پولی
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 |