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

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

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

کتابخانه 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",
    "payment_type":"installment",
    "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',
    'payment_type': 'installment',
    '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","payment_type":"installment","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","payment_type":"installment","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',
        'payment_type' => 'installment',
        '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\",\"payment_type\": \"installment\",\"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\",\"payment_type\": \"installment\",\"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',
    'payment_type': 'installment',
    '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',
    'payment_type': 'installment',
    '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","payment_type":"installment","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	شماره‌ی تلفن خریدار
payment_type	string	نوع پرداخت (`installment`: اقساطی)
deposit_items	deposit_itemsObject	لیست آیتم‌های سبد خرید

نکته: در صورتی که پرداخت از نوع اقساطی باشد باید فیلد payment_type با مقدار installment در درخواست ارسال شود. در غیر اینصورت نیازی به ارسال این فیلد در درخواست نیست.

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 باشد فروشنده موظف است با استفاده از سرویس تایید پرداخت، عملیات را تایید و وضعیت پرداخت را نهایی کند. در صورت فراخوانی نشدن تایید پرداخت یا بروز مشکلات پرداختی دیگر که منجر به کسر از حساب بانکی خریدار شده باشد، بعد از طی زمان مشخص پرداخت ملغی شده و مبلغ به کارت بانکی خریدار برگردانده می‌شود.

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

سرویس ضمانت خرید سما، بعد مشخص شدن وضعیت پرداخت کاربر را به آدرس callback_url مشخص شده در سرویس ایجاد پرداخت منتقل می کند، در این مرحله لازم است با استفاده از سرویس تایید پرداخت وضعیت پرداخت را بررسی کنید.

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