وب سرویس های ضمانت خرید سما¶

مستند زیر نحوه‌ی استفاده از سرویس های سما را توضیح می‌دهد. چنانچه به دنبال استفاده از سرویس های سما در فروشگاه وردپرسی هستید به این بخش مراجعه کنید.

پیاده سازی سرویس های سما، به سادگی پیاده سازی یک درگاه پرداخت بانکی است. مشابه درگاه پرداخت بانکی، یک سرویس برای درخواست ایجاد پرداخت و دیگری برای تایید پرداخت فراخوانی می‌شود. برای پیاده سازی نیاز است فروشگاه این دو وب سرویس را فراخوانی کند.

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

کتابخانه sama-laravel-payment برای پیاده سازی سرویس های سما در فریم ورک لاراول

https://github.com/sama-ir/sama-laravel-payment

توضیح مراحل پرداخت¶

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

در ادامه روش انجام هر کدام از این مراحل توضیح داده می‌شود.

توکن دسترسی به وب سرویس¶

برای دسترسی به سرویس‌های سما نیاز به توکن احراز هویت دارید. در صورتی که هنوز این توکن را دریافت نکردید به بخش فعال سازی سرویس مراجعه کنید.

نحوه‌ی استفاده از توکن¶

نحوه‌ی استفاده از توکن احراز هویت به این شکل است که باید آن را در هدر Authorization درخواست فراخوانی خود قرار دهید:

Authorization: Api-Key XXXXXXXXXXXXXXXXXXXXX

بررسی صحت توکن و اتصال به وب سرویس¶

برای بررسی صحت توکن خود می‌توانید از این سرویس استفاده کنید.

GET /api/stores/services/deposits/health/

نمونه کد درخواست¶

BashPythonPHPC#JavaJavascriptGolang

curl --request GET 'https://app.sama.ir/api/stores/services/deposits/health/' \
--header 'Authorization: Api-Key abcd' \
--header 'Content-Type: application/json'

import requests

headers = {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json',
}

response = requests.get('https://app.sama.ir/api/stores/services/deposits/health/', headers=headers)

<?php

// 1. Example using curl:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.sama.ir/api/stores/services/deposits/health/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Api-Key abcd',
    'Content-Type: application/json',
]);

$response = curl_exec($ch);

curl_close($ch);

// 2. Example using Guzzle:

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get( 'https://app.sama.ir/api/stores/services/deposits/health/', [
    'headers' => [
        'Authorization' => 'Api-Key abcd',
        'Content-Type'  => 'application/json'
    ]
]);

// 1. Example using HttpClient:

using System.Net.Http;
using System.Net.Http.Headers;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, "https://app.sama.ir/api/stores/services/deposits/health/");

client.DefaultRequestHeaders.Add("Authorization", "Api-Key abcd");

request.Content = new StringContent("");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

// 2. Example using RestSharp:

using RestSharp;

var options = new RestClientOptions("https://app.sama.ir");
var client = new RestClient(options);
var request = new RestRequest("api/stores/services/deposits/health/");
request.AddHeader("Authorization", "Api-Key abcd");
var response = await client.GetAsync(request);

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.sama.ir/api/stores/services/deposits/health/"))
    .GET()
    .setHeader("Authorization", "Api-Key abcd")
    .setHeader("Content-Type", "application/json")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

// 1. Example using axios:

import axios from 'axios';

const response = await axios.get('https://app.sama.ir/api/stores/services/deposits/health/', {
  headers: {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json'
  }
});

// 2. Example using node-fetch

import fetch from 'node-fetch';

fetch('https://app.sama.ir/api/stores/services/deposits/health/', {
  headers: {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json'
  }
});

package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  client := &http.Client{}
  req, err := http.NewRequest("GET", "https://app.sama.ir/api/stores/services/deposits/health/", nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Authorization", "Api-Key abcd")
  req.Header.Set("Content-Type", "application/json")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

هدرهای درخواست¶

Authorization: Api-Key {token}

پاسخ وب سرویس¶

Status code: 200

{
  "is_valid": true,
  "store_uid": "e6b9f2b0-5b5a-4b4e-9c1b-1b2c3d4e5f6g"
}

Field	Type	Description
is_valid	boolean	وضعیت توکن
store_uid	uuid4	شناسه‌ی منحصر به فرد فروشگاه

خطاها¶

Status code: 401

به این معنی است که توکن احراز هویت شما دیگر اعتبار ندارد.

status_code=401

{
  "code": "not_authenticated",
  "detail": "Authentication credentials were not provided.",
  "extra": {}
}

ایجاد پرداخت جدید¶

برای استفاده از سرویس ها لازم است ابتدا یک پرداخت جدید ایجاد کنید، برای ایجاد پرداخت جدید می‌توانید از این وب سرویس استفاده کنید.

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

POST /api/stores/services/deposits/guaranteed/

نمونه کد درخواست¶

BashPythonPHPC#JavaJavascriptGolang

curl --request POST 'https://app.sama.ir/api/stores/services/deposits/guaranteed/' \
--header 'Authorization: Api-Key abcd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "price": "100000",
    "client_id": "5a1dca49-96bb-4318-a7cb-ebf2a6281e8e",
    "buyer_phone": "09123456789",
    "callback_url": "https://mystore.ir/payment_callback",
    "deposit_items": [
        {
            "name": "product2",
            "per_price": 60000,
            "price": 144000,
            "quantity": 24,
            "discount": 0,
            "images": [
                "https://example.com/images/1.jpg",
                "https://example.com/images/2.jpg",
                "https://example.com/images/3.jpg"
            ]
        },
        {
            "name": "product3",
            "price": 60000,
            "quantity": 10,
            "discount": 0
        },
        {
            "name": "product1",
            "price": 60000,
            "quantity": 1
        }
    ]
}'

import requests

headers = {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json',
}

json_data = {
    'price': 100000,
    'buyer_phone': '09123456789',
    'client_id':  '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e',
    'callback_url': 'https://mystore.ir/payment_callback',
    'deposit_items': [
        {
            'name': 'product2',
            'per_price': 60000,
            'price': 60000 * 24,
            'quantity': 24,
            'discount': 0,
            'images': [
                'https://s100.divarcdn.com/static/photo/afra/post/1.jpg',
                'https://s100.divarcdn.com/static/photo/afra/post/2.jpg',
                'https://s100.divarcdn.com/static/photo/afra/post/3.jpg'
            ]
        },
        {
            'name': 'product3',
            'quantity': 10,
            'price': 60000,
            'discount': 0,
        },
        {
            'name': 'product1',
            'quantity': 1,
            'price': 60000,
        }
    ]
}

response = requests.post(
    'https://app.sama.ir/api/stores/services/deposits/guaranteed/',
    headers=headers,
    json=json_data
)

<?php

// 1. Example using curl:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.sama.ir/api/stores/services/deposits/guaranteed/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Api-Key abcd',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"price": "100000","client_id": "5a1dca49-96bb-4318-a7cb-ebf2a6281e8e","buyer_phone": "09123456789","callback_url": "https://mystore.ir/payment_callback","deposit_items": [{"name": "product2","per_price": 60000,"price": 144000,"quantity": 24,"discount": 0,"images": ["https://example.com/images/1.jpg","https://example.com/images/2.jpg","https://example.com/images/3.jpg"]},{"name": "product3","price": 60000,"quantity": 10,"discount": 0},{"name": "product1","price": 60000,"quantity": 1}]}');

$response = curl_exec($ch);

curl_close($ch);

// 2. Example using Guzzle:

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://app.sama.ir/api/stores/services/deposits/guaranteed/', [
    'headers' => [
        'Authorization' => 'Api-Key abcd',
        'Content-Type'  => 'application/json'
    ],
    // 'body' => '{"price": "100000","client_id": "5a1dca49-96bb-4318-a7cb-ebf2a6281e8e","buyer_phone": "09123456789","callback_url": "https://mystore.ir/payment_callback","deposit_items": [{"name": "product2","per_price": 60000,"price": 144000,"quantity": 24,"discount": 0,"images": ["https://example.com/images/1.jpg","https://example.com/images/2.jpg","https://example.com/images/3.jpg"]},{"name": "product3","price": 60000,"quantity": 10,"discount": 0},{"name": "product1","price": 60000,"quantity": 1}]}',
    'json' => [
        'price' => '100000',
        'client_id' => '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e',
        'buyer_phone' => '09123456789',
        'callback_url' => 'https://mystore.ir/payment_callback',
        'deposit_items' => [
            [
                'name' => 'product2',
                'per_price' => 60000,
                'price' => 144000,
                'quantity' => 24,
                'discount' => 0,
                'images' => [
                    'https://example.com/images/1.jpg',
                    'https://example.com/images/2.jpg',
                    'https://example.com/images/3.jpg'
                ]
            ],
            [
                'name' => 'product3',
                'price' => 60000,
                'quantity' => 10,
                'discount' => 0
            ],
            [
                'name' => 'product1',
                'price' => 60000,
                'quantity' => 1
            ]
        ]
    ]
]);

// 1. Example using HttpClient:

using System.Net.Http;
using System.Net.Http.Headers;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://app.sama.ir/api/stores/services/deposits/guaranteed/");

request.Headers.Add("Authorization", "Api-Key abcd");

request.Content = new StringContent("{\"price\": \"100000\",\"client_id\": \"5a1dca49-96bb-4318-a7cb-ebf2a6281e8e\",\"buyer_phone\": \"09123456789\",\"callback_url\": \"https://mystore.ir/payment_callback\",\"deposit_items\": [{\"name\": \"product2\",\"per_price\": \"60000\",\"price\": \"144000\",\"quantity\": \"24\",\"discount\": \"0\",\"images\": [\"https://example.com/images/1.jpg\",\"https://example.com/images/2.jpg\",\"https://example.com/images/3.jpg\"]},{\"name\": \"product3\",\"price\": \"60000\",\"quantity\": \"10\",\"discount\": \"0\"},{\"name\": \"product1\",\"price\": \"60000\",\"quantity\": \"1\"}]}");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.sama.ir/api/stores/services/deposits/guaranteed/"))
    .POST(BodyPublishers.ofString("{\"price\": \"100000\",\"client_id\": \"5a1dca49-96bb-4318-a7cb-ebf2a6281e8e\",\"buyer_phone\": \"09123456789\",\"callback_url\": \"https://mystore.ir/payment_callback\",\"deposit_items\": [{\"name\": \"product2\",\"per_price\": \"60000\",\"price\": \"144000\",\"quantity\": \"24\",\"discount\": \"0\",\"images\": [\"https://example.com/images/1.jpg\",\"https://example.com/images/2.jpg\",\"https://example.com/images/3.jpg\"]},{\"name\": \"product3\",\"price\": \"60000\",\"quantity\": \"10\",\"discount\": \"0\"},{\"name\": \"product1\",\"price\": \"60000\",\"quantity\": \"1\"}]}"))
    .setHeader("Authorization", "Api-Key abcd")
    .setHeader("Content-Type", "application/json")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

// 1. Example using axios:

import axios from 'axios';

const response = await axios.post(
  'https://app.sama.ir/api/stores/services/deposits/guaranteed/',
  {
    'price': '100000',
    'client_id': '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e',
    'buyer_phone': '09123456789',
    'callback_url': 'https://mystore.ir/payment_callback',
    'deposit_items': [
        {
            'name': 'product2',
            'per_price': 60000,
            'price': 60000 * 24,
            'quantity': 24,
            'discount': 0,
            'images': [
                'https://s100.divarcdn.com/static/photo/afra/post/1.jpg',
                'https://s100.divarcdn.com/static/photo/afra/post/2.jpg',
                'https://s100.divarcdn.com/static/photo/afra/post/3.jpg'
            ]
        },
        {
            'name': 'product3',
            'quantity': 10,
            'price': 60000,
            'discount': 0,
        },
        {
            'name': 'product1',
            'quantity': 1,
            'price': 60000,
        }
    ]
  },
  {
    headers: {
      'Authorization': 'Api-Key abcd',
      'Content-Type': 'application/json'
    }
  }
);

// 2. Example using node-fetch

import fetch from 'node-fetch';

fetch('https://app.sama.ir/api/stores/services/deposits/guaranteed/', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'price': '100000',
    'client_id': '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e',
    'buyer_phone': '09123456789',
    'callback_url': 'https://mystore.ir/payment_callback',
    'deposit_items': [
        {
            'name': 'product2',
            'per_price': 60000,
            'price': 60000 * 24,
            'quantity': 24,
            'discount': 0,
            'images': [
                'https://s100.divarcdn.com/static/photo/afra/post/1.jpg',
                'https://s100.divarcdn.com/static/photo/afra/post/2.jpg',
                'https://s100.divarcdn.com/static/photo/afra/post/3.jpg'
            ]
        },
        {
            'name': 'product3',
            'quantity': 10,
            'price': 60000,
            'discount': 0,
        },
        {
            'name': 'product1',
            'quantity': 1,
            'price': 60000,
        }
    ]
  })
});

package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "strings"
)

func main() {
  client := &http.Client{}
  var data = strings.NewReader(`{"price": "100000","client_id": "5a1dca49-96bb-4318-a7cb-ebf2a6281e8e","buyer_phone": "09123456789","callback_url": https://mystore.ir/payment_callback","deposit_items": [{"name": "product2","per_price": 60000,"price": 144000,"quantity": 24,"discount": 0,"images": ["https://example.com/images/1.jpg","https://example.com/images/2.jpg","https://example.com/images/3.jpg"]},{"name": "product3","price": 60000,"quantity": 10,"discount": 0},{"name": "product1","price": 60000,"quantity": 1}]
}`)
  req, err := http.NewRequest("POST", "https://app.sama.ir/api/stores/services/deposits/guaranteed/", data)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Authorization", "Api-Key abcd")
  req.Header.Set("Content-Type", "application/json")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

هدرهای درخواست¶

Authorization: Api-Key {token}

ورودی وب سرویس¶

Request Body (JSON):

Field	Type	Description
price*	integer	مبلغ کل پرداخت
client_id*	string	شناسه‌ی منحصر به فردی که شما به سفارش دهنده اختصاص می‌دهید
callback_url*	string	آدرسی که خریدار پس از پرداخت به آن منتقل می‌شود
buyer_phone	string	شماره‌ی تلفن خریدار
deposit_items	array of deposit_itemsObject	لیست آیتم‌های سبد خرید

deposit_itemsObject:

Field	Type	Description
name	string	نام محصول
per_price	integer	قیمت هر واحد محصول
quantity	integer	تعداد محصول
price	integer	قیمت کل (حاصل ضرب quantity و per_price)
discount	integer	تخفیف
images	array of string	تصاویر محصول

پاسخ وب سرویس¶

status_code=201

{
  "uid": "e6b9f2b0-5b5a-4b4e-9c1b-1b2c3d4e5f6g",
  "web_view_link": "https://app.sama.ir/store/transaction/guaranteed/preview/481c675d-210b-439f-ae7f-7b157bda151a/?phone=MDkxMjExMTExMTE="
}

Field	Type	Description
uid	uuid4	شناسه‌ی منحصر به فرد برای هر پرداخت
web_view_link	string	آدرس صفحه‌ی پرداخت که درخواست دهنده‌ی خدمات تجاری خریدار را به آن منتقل می‌کند.

خطاهای سرویس¶

status_code=400

{
  "code": "validation_error",
  "detail": "validation error",
  "extra": [
    {
      "field": "buyer_phone",
      "error": "شماره تلفن وارد شده معتبر نیست"
    }
  ]
}

status_code=400

{
  "code": "validation_error",
  "detail": "validation error",
  "extra": [
    {
      "field": "callback_url",
      "error": "Enter a valid URL."
    }
  ]
}

هدایت کاربر به وبسایت فروشنده¶

وبسایت سما پس از اتمام تراکنش، خریدار را دوباره به وبسایت فروشنده به آدرس callback_url هدایت می‌کند (ریدایرکت می‌کند). فروشنده پارامترهای ارسال شده از وبسایت سما را با متد POST دریافت می‌کند. پارامترهای ارسالی عبارتند از:

price (مبلغ بدون کارمزد)
process_id*
request_id (شناسه‌ی منحصر به فرد برای هر درخواست)
reference_number (کد رهگیری)
message (پیام)
uid (شناسه‌ی منحصر به فرد برای هر پرداخت)
payment_uid* (شناسه‌ی منحصر به فرد برای درخواست به شاپرک)
result_code (کد نتیجه)

نکته: برای پیاده سازی ، نیازی به دانستن مفهوم موارد ستاره دار ندارید.

فروشنده با توجه به مقدار result_code میتواند از وضعیت پرداخت مطلع شود. در صورتی که مقدار result_code برابر 0 نباشد فروشنده موظف است خطای به وجود آمده و علت آن را با توجه به result_code و message برای کاربر شرح دهد. همچنین فروشنده پارامترهای پرداخت از جمله مبلغ را با مقادیر ذخیره شده سفارش مشتری چک می‌کند. در صورتی که مقدار result_code برابر 0 باشد فروشنده موظف است با استفاده از سرویس تایید پرداخت، عملیات را تایید و وضعیت پرداخت را نهایی کند. در صورت فراخوانی نشدن تایید پرداخت یا بروز مشکلات پرداختی دیگر که منجر به کسر از حساب بانکی خریدار شده باشد، بعد از طی زمان مشخص پرداخت ملغی شده و مبلغ به کارت بانکی خریدار برگردانده می‌شود.

تایید پرداخت¶

بعد از بازگشت، فروشنده باید با استفاده از سرویس تایید پرداخت، پرداخت را تایید کند، برای این کار باید request_id و client_id را به سرویس زیر بدهید.

POST /api/stores/services/deposits/guaranteed/payment/verify/

نمونه کد درخواست¶

BashPythonPHPC#JavaJavascriptGolang

curl --request POST 'https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/' \
--header 'Authorization: Api-Key abcd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "request_id": "aya6ms9vzs",
    "client_id": "5a1dca49-96bb-4318-a7cb-ebf2a6281e8e"
}'

import requests

headers = {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json',
}

json_data = {
    'request_id': 'aya6ms9vzs',
    'client_id': '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e',
}

response = requests.post(
    'https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/',
    headers=headers,
    json=json_data,
)

<?php

// 1. Example using curl:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Api-Key abcd',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"request_id":"aya6ms9vzs","client_id":"5a1dca49-96bb-4318-a7cb-ebf2a6281e8e"}');

$response = curl_exec($ch);

curl_close($ch);

// 2. Example using Guzzle:

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/', [
    'headers' => [
        'Authorization' => 'Api-Key abcd',
        'Content-Type'  => 'application/json'
    ],
    'json' => [
        'request_id' => 'aya6ms9vzs',
        'client_id' => '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e'
    ]
]);

// 1. Example using HttpClient:

using System.Net.Http;
using System.Net.Http.Headers;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/");

request.Headers.Add("Authorization", "Api-Key abcd");

request.Content = new StringContent("{\"request_id\":\"aya6ms9vzs\",\"client_id\":\"5a1dca49-96bb-4318-a7cb-ebf2a6281e8e\"}");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/"))
    .POST(BodyPublishers.ofString("{\"request_id\":\"aya6ms9vzs\",\"client_id\":\"5a1dca49-96bb-4318-a7cb-ebf2a6281e8e\"}"))
    .setHeader("Authorization", "Api-Key abcd")
    .setHeader("Content-Type", "application/json")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

// 1. Example using axios:

import axios from 'axios';

const response = await axios.post(
  'https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/',
  {
    'request_id': 'aya6ms9vzs',
    'client_id': '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e'
  },
  {
    headers: {
      'Authorization': 'Api-Key abcd',
      'Content-Type': 'application/json'
    }
  }
);

// 2. Example using node-fetch

import fetch from 'node-fetch';

fetch('https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key abcd',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'request_id': 'aya6ms9vzs',
    'client_id': '5a1dca49-96bb-4318-a7cb-ebf2a6281e8e'
  })
});

package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "strings"
)

func main() {
  client := &http.Client{}
  var data = strings.NewReader(`{"request_id":"aya6ms9vzs","client_id":"5a1dca49-96bb-4318-a7cb-ebf2a6281e8e"}`)
  req, err := http.NewRequest("POST", "https://app.sama.ir/api/stores/services/deposits/guaranteed/payment/verify/", data)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Authorization", "Api-Key abcd")
  req.Header.Set("Content-Type", "application/json")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

هدرهای درخواست¶

Authorization: Api-Key {token}

ورودی وب سرویس¶

Request Body (JSON):

Field	Type	Description
client_id	string	شناسه‌ی منحصر به فردی که شما به سفارش دهنده اختصاص می‌دهید
request_id	string	شناسه‌ی منحصر به فرد برای هر درخواست

پاسخ وب سرویس¶

Response Body (Status code: 200)

{
  "uid": "fd3c951b-f419-450c-984c-f6811aebd2fb",
  "client_id": "5a1dca49-96bb-4318-a7cb-ebf2a6281e8e",
  "buyer": {
    "phone_number": "09121111111"
  },
  "price": 100000,
  "fee": 10000,
  "is_paid": true,
  "payment": {
    "id": "2801b36a-4d14-45fd-9476-c58ccd8231a2",
    "total_price": 110000,
    "request_id": "aya6ms9vzs",
    "paid_at": "2023-02-12T16:40:44.878698+03:30",
    "reference_number": "a8855a02aad611edbd6b578e4ad3f48a",
    "transaction_code": "ez6643658523",
    "is_failed": false
  }
}

Field	Type	Description
uid	uuid4	شناسه‌ی منحصر به فرد هر پرداخت
client_id	string	شناسه‌ی منحصر به فرد هر سفارش دهنده‌ی تجاری
buyer	buyerObject	اطلاعات خریدار
price	integer	مبلغ کل پرداخت
fee	integer	کارمزد سرویس ضمانت خرید سما
is_paid	boolean	وضعیت پرداخت
payment	paymentObject	اطلاعات پرداخت

buyerObject:

Field	Type	Description
phone_number	string	شماره‌ی خریدار

paymentObject:

Field	Type	Description
id	uuid4	شناسه درخواست پرداخت
total_price	integer	مبلغ کل پرداخت شده توسط خریدار که نشان دهنده‌ی جمع مبلغ پرداخت و کارمزد است
request_id	string	شناسه درخواست که مرحله ی قبل برگردانده شده بود
paid_at	string	تاریخ پرداخت
reference_number	string	کد رهگیری
transaction_code	string	---
is_failed	boolean	وضعیت پرداخت

خطاها¶

اگر فیلد request_id معتبر نباشد خطای 404 برگشت داده می‌شود.

{
  "code": "not_found",
  "detail": "Not found.",
  "extra": {}
}

اگر پرداخت انجام نشده باشد خطای 404 برگشت داده می‌شود.

{
  "code": "ezpay_service_error",
  "detail": "خطا در سرویس پرداخت",
  "extra": {}
}