NAV
php csharp

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;
        }

    }
}
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;
        }
    }
}

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
BTC Bitcoin 110
ETH Ethereum 120
USDT Tether 130

Appendix B : Crypto Currency Transactions

Cryoptocurrency transaction statuses

Status Description
new Newly created invoice. The shopper has not yet selected payment currency.
pending Shopper selected payment currency. Awaiting payment.
confirming Shopper transferred the payment for the invoice. Awaiting blockchain network confirmation.
paid Payment is confirmed by the network, and has been credited to the merchant. Purchased goods/services can be safely delivered to the shopper.
invalid Payment rejected by the network or did not confirm within 7 days.
expired Shopper did not pay within the required time (default: 30 minutes) and the invoice expired.
canceled Shopper canceled the invoice.
refunded Payment was refunded to the shopper.

Statuses by priority

new

pending

confirming*

4a. expired OR canceled**

4b. paid OR invalid

Refunded

*The "confirming" status is sometimes skipped and "paid" or "invalid" status is sent instead.

**The "expired" or "canceled" status is sometimes changed to "paid" if the payment arrived after the invoice has expired / was canceled.

Cryptocurrency transactions have a different verification process than traditional transactions in that the system sends a post request to the callback url you sent at the time of the transaction to change the status of the transaction.

The submitted information is as follows

<?php

// Your custom order_id is defined when you creating new order: https://docs.yekpay.com/create-order
// Also don't forget to prevent SQL injection
$result = mysql_query("SELECT * FROM orders WHERE id = " . $_POST['order_id']);
$order = mysql_fetch_assoc($result);

// token is your random secure string (for example: 5d02161be9bfb6192a33) for each order
if ($_POST['token'] == $order['token']) {
  // Handle Yekpay order status: https://docs.yekpay.com/order-statuses
  $status = NULL;
  if ($_POST['status'] == 'paid') {
    if ($_POST['price_amount'] >= $order['amount']) {
      $status = 'paid';
    }
  }
  else {
    $status = $_POST['status'];
  }

  if (!is_null($status)) {
      mysql_query("UPDATE orders SET status = '".$status."' WHERE id = ".$_POST['order_id']);
  }
}
Name Value
id Yekpay order (invoice) ID.
order_id Custom order ID of the merchant. Should be used to identify order or invoice number.
status Yekpay payment status.
price_amount The price set by the merchant; for example, 499.95.
price_currency The currency code which defines the currency in which the merchant's goods/services are priced; for example, EUR, TRY, BTC (see supported currencies).
recieve_currency The currency code which defines the currency in which the merchant's settlements will be paid. Currency conversions are done by yekpay automatically. For example: EUR, EUR, BTC, USDT, etc.
recieve_amount The amount which will be credited to the merchant when the invoice is paid. It is calculated by taking the price amount (converted to currency units set in receive_currency) and subtracting CoinGate processing fee from it.
pay_amount The amount of cryptocurrency (defined by pay_currency) paid by the shopper.
pay_currency The cryptocurrency in which the payment was made; for example, BTC, LTC, ETH.
underpaid_amount The amount of cryptocurrency (defined by pay_currency) underpaid by the shopper; for example, if pay_amount => 0.123, pay_currency => BTC, and the shopper paid 0.12 BTC, then underpaid_amount => 0.003. Changes in underpaid_amount will not trigger additional callbacks, but when order information is retrieved using GET or LIST, latest value will be shown.
overpaid_amount The amount of cryptocurrency (defined by pay_currency) overpaid by the shopper; for example, if pay_amount => 0.123, pay_currency => BTC, and the shopper paid 0.15 BTC, then overpaid_amount => 0.027. Changes in overpaid_amount will not trigger additional callbacks, but when order information is retrieved using GET or LIST, latest value will be shown.
is_refundable Possible values: true, false. Indicates whether or not the shopper can request a refund on the invoice. Changes in is_refundable will not trigger additional callbacks, but when order information is retrieved using GET or LIST, latest value will be shown.
created_at Invoice creation time.