پرش به محتویات

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

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

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

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

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

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

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

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

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

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

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

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

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

Authorization: Api-Key XXXXXXXXXXXXXXXXXXXXX

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

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

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

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

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/

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

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/

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

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": {}
}