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 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.
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
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
2- Payment Request
URL
https://gate.ypsapi.com/api/payment/request
Sandbox URL
https://api.ypsapi.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.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- 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
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.ypsapi.com/api/payment/start/{AUTHORITY}
Sandbox URL
https://api.ypsapi.com/api/sandbox/payment/{AUTHORITY}
Diagram
5- Payment Processing
Description
At this stage, the payer completes their transaction through the payment gateway, and after the payment (whether successful or unsuccessful), they are redirected to your callback URL. The parameters "Status" and "Authority" are sent to the callback address via POST.
Diagram
6- Payment Verification
URL
https://gate.ypsapi.com/api/payment/verify
Sandbox URL
https://api.ypsapi.com/api/sandbox/verify
Method
POST
Inputs
PARAMETERS | DESCRIPTION | EXAMPLE |
---|---|---|
merchantId | 32-digits merchant ID | 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.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
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
Test Cards
CARD NAME | CARD NUMBER | EXPIRATION DATE | CVC | DESCRIPTION |
---|---|---|---|---|
John Doe | 5269552233334445 | 2028/12 | 000 | Unsuccessful Transaction |
David Doe | 4022771122223334 | 2028/12 | 000 | Successful Transaction |
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 |