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

ایجاد پرداخت

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

جهت استفاده از سرویس ضمانت خرید و پرداخت اقساطی برای هر خرید، لازم است ابتدا یک پرداخت جدید ایجاد شود، برای ایجاد پرداخت جدید از API زیر استفاده می شود.

POST /api/pg/v2/payment/request.json/

ارسال درخواست به API ایجاد پرداخت:

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

Content-Type: application/json

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

curl --request POST 'https://app.sama.ir/api/pg/v2/payment/request.json/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": "12000000",
    "merchant_id": "GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg",
    "description": "lorem ipsum...",
    "callback_url": "https://test.app.sama.ir",
    "currency":"IRR",
    "metadata": {
        "mobile": "09121234567",
        "order_id": "c6257655-6934-45dd-8251-251aba938aa7"
    },
    "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
        }
    ]
}'

<?php

// 1. Example using curl:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.sama.ir/api/pg/v2/payment/request.json/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"amount": "12000000","merchant_id": "GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg","description": "lorem ipsum...","callback_url": "https://test.app.sama.ir","currency":"IRR","metadata": {"mobile": "09121234567","order_id": "c6257655-6934-45dd-8251-251aba938aa7",       "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/pg/v2/payment/request.json/', [
    'headers' => [
        'Content-Type'  => 'application/json'
    ],
    // 'body' => '{"amount": "12000000","merchant_id": "GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg","description": "lorem ipsum...","callback_url": "https://test.app.sama.ir","currency":"IRR","metadata": {"mobile": "09121234567","order_id": "c6257655-6934-45dd-8251-251aba938aa7","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' => [
        'amount' => '12000000',
        'merchant_id' => 'GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg',
        'description' => 'lorem ipsum...',
        'callback_url' => 'https://test.app.sama.ir',
        'currency' => 'IRR',
        'metadata' => [
            'mobile' => '09121234567',
            'order_id' => 'c6257655-6934-45dd-8251-251aba938aa7'
        ],
        '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 Body (JSON):
Field Type Description
amount* integer مبلغ کل پرداخت
merchant_id* string توکن احراز هویت فروشگاه (API Key)
description* string توضیحات پرداخت
callback_url* string آدرسی که خریدار پس از پرداخت به آن منتقل می‌شود
currency string واحد پول پرداخت (IRR: ریال - IRT: تومان)
metadata metadataObject جزئیات
payment_type string نوع پرداخت (installment: اقساطی)
deposit_items deposit_itemsObject لیست آیتم‌های سبد خرید

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

metadataObject:

Field Type Description
mobile string شماره‌ی تلفن خریدار
email string آدرس ایمیل خریدار
order_id string شناسه‌ی منحصر به فرد هر سفارش

deposit_itemsObject:

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

پاسخ دریافتی از API:

بدنه پاسخ

status_code=201
{
    "data": {
        "code": 100,
        "message": "Success",
        "authority": "5430a992-83c7-40bc-b5f3-e1c998bdecb1",
        "fee_type": "buyer",
        "fee": 150000
    },
    "errors": []
}
Field Type Description
data dataObject اطلاعات پاسخ (در صورت بروز خطا، خالی برمیگردد)
errors errorsObject خطاها (در صورت عدم بروز خطا، خالی برمیگردد)

dataObject:

Field Type Description
code integer کد پاسخ سرور
message string وضعیت دریافت اطلاعات توسط سرور
authority uuid4 شناسه منحصر به فرد معامله (باید در URL پرداخت قرار بگیرد)
fee_type string شخص پرداخت کننده کارمزد (merchant-buyer-both-none)
fee integer مبلغ کارمزد

errorsObject:

در صورت پاسخ دهی صحیح و عدم بروز خطا (status code 201)، این فیلد خالی برمی‌گردد. در غیر اینصورت شامل اطلاعات زیر خواهد بود:

Field Type Description
code string کد خطا
message string پیغام خطا
validations validationsObject فیلدی که باعث بروز خطا شده است

خطاها

خطای احراز توکن فروشگاه (مربوط به فیلد merchant_id):

status_code=401
{
    "data": [],
    "errors": {
        "code": "not_authenticated",
        "message": "اطلاعات برای اعتبارسنجی ارسال نشده است.",
        "validations": []
    }
}

خطای معتبر نبودن callback_url:

status_code=400
{
    "data": [],
    "errors": {
        "code": "-9",
        "message": "The input params invalid, validation error.",
        "validations": [
            {
                "callback_url": "یک URL معتبر وارد کنید"
            }
        ]
    }
}

انجام پرداخت

برای انجام پرداخت، بعد از ارسال درخواست ایجاد پرداخت لازم است از بدنه پاسخ دریافتی، authority را برداشته و به صورت زیر در انتهای آدرس قرار داد:

{base url}/pg/StartPay/5430a992-83c7-40bc-b5f3-e1c998bdecb1

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

pay

تست پرداخت در سندباکس

برای انجام پرداخت تستی می‌توان از API سندباکس زیر استفاده کرد:

POST /api/sandbox/pg/v2/payment/request.json/

ارسال درخواست به API ایجاد پرداخت تستی سندباکس:

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

Content-Type: application/json

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

curl --request POST 'https://app.sama.ir/api/sandbox/pg/v2/payment/request.json/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": "12000000",
    "merchant_id": "GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg",
    "description": "lorem ipsum...",
    "callback_url": "https://test.app.sama.ir",
    "currency":"IRR",
    "metadata": {
        "mobile": "09121234567",
        "order_id": "c6257655-6934-45dd-8251-251aba938aa7"
    }
}'

<?php

// 1. Example using curl:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.sama.ir/api/sandbox/pg/v2/payment/request.json/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"amount": "12000000","merchant_id": "GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg","description": "lorem ipsum...","callback_url": "https://test.app.sama.ir","currency":"IRR","metadata": {"mobile": "09121234567", "order_id": "c6257655-6934-45dd-8251-251aba938aa7"}}');

$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/sandbox/pg/v2/payment/request.json/', [
    'headers' => [
        'Content-Type'  => 'application/json'
    ],
    // 'body' => '{"amount": "12000000","merchant_id": "GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg","description": "lorem ipsum...","callback_url": "https://test.app.sama.ir","currency":"IRR","metadata": {"mobile": "09121234567","order_id": "c6257655-6934-45dd-8251-251aba938aa7"}}',
    'json' => [
        'amount' => '12000000',
        'merchant_id' => 'GXyXvV72.woCX6cvclOvIvFB0KkR5OUbLMadMlIqg',
        'description' => 'lorem ipsum...',
        'callback_url' => 'https://test.app.sama.ir',
        'currency' => 'IRR',
        'metadata' => [
            'mobile' => '09121234567',
            'order_id' => 'c6257655-6934-45dd-8251-251aba938aa7'
        ]
    ]
]);

بدنه درخواست

Request Body (JSON):
Field Type Description
amount* integer مبلغ کل پرداخت
merchant_id* string توکن احراز هویت فروشگاه (API Key)
description* string توضیحات پرداخت
callback_url* string آدرسی که خریدار پس از پرداخت به آن منتقل می‌شود
currency string واحد پول پرداخت (IRR: ریال - IRT: تومان)
metadata metadataObject جزئیات

metadataObject:

Field Type Description
mobile string شماره‌ی تلفن خریدار
email string آدرس ایمیل خریدار
order_id string شناسه‌ی منحصر به فرد هر سفارش

پاسخ دریافتی از API:

بدنه پاسخ

status_code=201
{
    "data": {
        "code": 100,
        "message": "Success",
        "authority": "5430a992-83c7-40bc-b5f3-e1c998bdecb1",
        "fee_type": "buyer",
        "fee": 150000
    },
    "errors": []
}
Field Type Description
data dataObject اطلاعات پاسخ (در صورت بروز خطا، خالی برمیگردد)
errors errorsObject خطاها (در صورت عدم بروز خطا، خالی برمیگردد)

dataObject:

Field Type Description
code integer کد پاسخ سرور
message string وضعیت دریافت اطلاعات توسط سرور
authority uuid4 شناسه منحصر به فرد معامله (باید در URL پرداخت قرار بگیرد)
fee_type string شخص پرداخت کننده کارمزد (merchant-buyer-both-none)
fee integer مبلغ کارمزد

errorsObject:

در صورت پاسخ دهی صحیح و عدم بروز خطا (status code 201)، این فیلد خالی برمی‌گردد. در غیر اینصورت شامل اطلاعات زیر خواهد بود:

Field Type Description
code string کد خطا
message string پیغام خطا
validations validationsObject فیلدی که باعث بروز خطا شده است

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

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

  • Authority (شناسه منحصر به فرد هر معامله)
  • Status (وضعیت پرداخت)

فروشگاه با توجه به مقدار Status میتواند از وضعیت پرداخت مطلع شود.

در صورتی که مقدار Status برابر OK باشد عملیات بدون خطا انجام شده است. پس باید با استفاده از سرویس تایید پرداخت، عملیات را تایید و وضعیت پرداخت را نهایی کرد. در صورت فراخوانی نشدن تایید پرداخت یا بروز مشکلات پرداختی دیگر که منجر به کسر از حساب بانکی خریدار شده باشد، بعد از طی زمان مشخص پرداخت لغو شده و مبلغ به کارت بانکی خریدار برگردانده می‌شود.

در صورتی که Status برابر NOK باشد، به این معنا است كه تراكنش ناموفق بوده یا توسط خریدار لغو شده است.