فاکتور

شروع
فاکتور
دیاگرام فاکتور
موجودی
نرخ
تبدیل
انتقال

فاکتور

ابتدا یک فاکتور بسازید و کاربر را به صفحه پرداخت منتقل کنید. بعد از پرداخت موفق کاربر ، اگر وب هوک را ست کرده باشید مشخصات فاکتور به وب هوک ارسال میشود (trackid,invoice_number,status) .
سپس یوزر به آدرس callback ثبت شده شما برمیگردد که پارامترهای trackid و invoice_number بصورت Query String در انتهای آدرس بازگشت اضافه میگردد .
بعد از بازگشت به آدرس callback وضعیت فاکتور را مجدد از API بررسی کنید برای اینکار کافی است از https://api.zipay.io/api/invoice-status استفاده کنید ، اگر "status" برابر با "pending" بود باید https://api.zipay.io/api/invoice-verify را فراخوانی کنید تا "status" تبدیل بشود به "completed" و سپس خدمات خود را به کاربر بدهید .

* شما 30 دقیقه زمان دارید تا https://api.zipay.io/api/invoice-verify را فراخوانی بکنید در غیر اینصورت مبلغ پرداختی کاربر به حسابش برگشت میخورد.

Create Invoice ساخت فاکتور

POST https://api.zipay.io/api/create-invoice

نام پارامتر	نوع	اجباری	توضیحات
terminal_number	integer	بله	اگه شما شماره ترمینال را ندارید از طریق پنل کاربری اقدام کنید برای ساخت یک درگاه و گرفتن شماره ترمینال.
amount	float	بله	مبلغ فاکتور
currency	string	بله	ارز مورد نظر میتواند یکی از ارزهای`USD` , `USDT` و `IRT` باشد
invoice_number	string	بله	به ازای هر درگاه شما باید یک شماره فاکتور یکتا وارد کنید ، محدودیت طول 200 کاراکتر هست
national_id	string	خیر	اگر کد ملی کاربر را وارد کنید فقط کاربری که این کد ملی را دارد میتواند این فاکتور را پرداخت کند !
callback	string	بله	آدرس برگشت به فروشگاه توجه کنید که پارامترهای trackid and invoice_number به انتهای آدرس اضافه میشوند بطور مثال آدرس `http://example.org/back` تبدیل میشود به `http://example.org/back?trackid=de7d44ae-9df9-487f-a175-ade1ecfab28b&invoice_number=1`
webhook	string	خیر	اگر شما این پارامتر را ست بکنید مقادیر `trackid`, `invoice_number` و `status` بعد از پرداخت موفق بصورت POST به آدرس ست شده ارسال میگردند.

خروجی:

{
    "result": {
        "trackid": "de7d44ae-9df9-487f-a175-ade1ecfab28b",
        "redirect": "http://api.zipay.io/invoice_v1/de7d44ae-9df9-487f-a175-ade1ecfab28b",
        "message": null
    },
    "success": true,
    "status": 200
}

Invoice Status وضعیت فاکتور

POST https://api.zipay.io/api/invoice-status

نام پارامتر	نوع	اجباری	توضیحات
trackid	string	بله	شناسه فاکتور`de7d44ae-9df9-487f-a175-ade1ecfab28b`

خروجی:

{
    "result": {
        "trackid": "de7d44ae-9df9-487f-a175-ade1ecfab28b",
        "status": "pending",
        "amount": "100.99",
        "coin": {
            "name": "United States dollar",
            "currency": "USD",
            "symbol": "$"
        },
        "invoice_number": "1000",
         "time": 1680282113,
        "date": "31/03/2023 17:01 UTC",
        "pay_date": "31/03/2023 17:02 UTC",
        "datew3c": "2023-03-31T17:01:53+00:00",
        "pay_datew3c": "2023-03-31T17:02:08+00:00",
        "merchant_terminal_number": 1003,
        "invoice_transaction_id": 101,
        "national_id": "",
        "payer_firstname": "نام پرداخت کننده",
        "payer_lastname": "نام خانوادگی پرداخت کننده",
        "payer_email": "[email protected]",
        "payer_account_number": 10025
    },
    "success": true,
    "status": 200
}

Invoice Verify تائید فاکتور

POST https://api.zipay.io/api/invoice-verify
این متد را زمانیکه invoice.status=pending هست برای تکمیل فاکتور و افزودن مبلغ به حساب شما باید فراخوانی کنید .

* اگر این API را فراخوانی نکنید بعد از نیم ساعت مبلغ به حساب کاربر مرجوع میشود !

نام پارامتر	نوع	اجباری	توضیحات
trackid	string	بله	شناسه فاکتور`de7d44ae-9df9-487f-a175-ade1ecfab28b`

خروجی:

{
    "result": {
        "trackid": "de7d44ae-9df9-487f-a175-ade1ecfab28b",
        "status": "completed",
        "amount": "100.99",
        "coin": {
            "name": "United States dollar",
            "currency": "USD",
            "symbol": "$"
        },
        "invoice_number": "1000",
         "time": 1680282113,
        "date": "31/03/2023 17:01 UTC",
        "pay_date": "31/03/2023 17:02 UTC",
        "datew3c": "2023-03-31T17:01:53+00:00",
        "pay_datew3c": "2023-03-31T17:02:08+00:00",
        "merchant_terminal_number": 1003,
        "invoice_transaction_id": 101,
        "national_id": "",
        "payer_firstname": "نام پرداخت کننده",
        "payer_lastname": "نام خانوادگی پرداخت کننده",
        "payer_email": "[email protected]",
        "payer_account_number": 10025
    },
    "success": true,
    "status": 200
}

Invoice List لیست فاکتورها

POST https://api.zipay.io/api/invoice-list

نام پارامتر	نوع	اجباری	توضیحات
terminal_number	integer	خیر	شماره ترمینال
invoice_number	string	خیر	شماره فاکتور فروشگاه
status	string	خیر	`refunded` `completed` `generated` `rejected` `pending` `waiting`
limit	integer	خیر	تعداد آیتم مورد نظر ، بصورت پیشفرض `10`
page	integer	خیر	صفحه مورد نظر بصورت پیشفرض`1`
sort	string	خیر	ترتیب آیتم ها بصورت پیشفرض `desc` هست شما میتوانید از `asc` هم استفاده کنید

Response:

{
    "items": [
        {
            "trackid": "08985ab3-5937-40ff-bffa-f85c56256730",
            "status": "generated",
            "amount": "1",
            "coin": {
                "name": "United States dollar",
                "currency": "USD",
                "symbol": "$"
            },
            "invoice_number": "981",
            "time": 1680282307,
            "date": "31/03/2023 17:05 UTC",
            "pay_date": null,
            "datew3c": "2023-03-31T17:05:07+00:00",
            "pay_datew3c": null,
            "merchant_terminal_number": 1003,
            "invoice_transaction_id": 116,
            "national_id": "",
            "payer_firstname": "نام پرداخت کننده",
        "payer_lastname": "نام خانوادگی پرداخت کننده",
            "payer_email": null,
            "payer_account_number": null
        },
        {
            "trackid": "2ac211ad-29f5-4009-a811-2ec64d937065",
            "status": "completed",
            "amount": "1000",
            "coin": {
                "name": "United States dollar",
                "currency": "USD",
                "symbol": "$"
            },
            "invoice_number": "10131",
            "time": 1680282113,
            "date": "31/03/2023 17:01 UTC",
            "pay_date": "31/03/2023 17:02 UTC",
            "datew3c": "2023-03-31T17:01:53+00:00",
            "pay_datew3c": "2023-03-31T17:02:08+00:00",
            "merchant_terminal_number": 1003,
            "invoice_transaction_id": 115,
            "national_id": "",
            "payer_firstname": "نام پرداخت کننده",
            "payer_lastname": "نام خانوادگی پرداخت کننده",
            "payer_email": "[email protected]",
            "payer_account_number": 10025
        },
        {
            "trackid": "abfab42c-2364-4b84-b709-3f7a8969ec2c",
            "status": "rejected",
            "amount": "1000",
            "coin": {
                "name": "United States dollar",
                "currency": "USD",
                "symbol": "$"
            },
            "invoice_number": "10031",
            "time": 1680281790,
            "date": "31/03/2023 16:56 UTC",
            "pay_date": "31/03/2023 16:56 UTC",
            "datew3c": "2023-03-31T16:56:30+00:00",
            "pay_datew3c": "2023-03-31T16:56:41+00:00",
            "merchant_terminal_number": 1003,
            "invoice_transaction_id": 114,
            "national_id": "",
            "payer_firstname": "نام پرداخت کننده",
            "payer_lastname": "نام خانوادگی پرداخت کننده",
            "payer_email": "[email protected]",
            "payer_account_number": 10025
        }
    ],
    "total": 9,
    "limit": 3,
    "page": 1,
    "sort": "desc",
    "success": true,
    "status": 200
}

Invoice refund مرجوع کردن فاکتور

POST https://api.zipay.io/api/invoice-refund

نام پارامتر	نوع	اجباری	توضیحات
trackid	string	بله	شناسه فاکتور`12a2c8ec-249a-43bb-a161-a7658981c110`

پاسخ:

{
    "result": {
        "trackid": "12a2c8ec-249a-43bb-a161-a7658981c110",
        "status": "refunded",
        "amount": "1",
        "coin": {
            "name": "United States dollar",
            "currency": "USD",
            "symbol": "$"
        },
        "invoice_number": "20",
        "time": 1680281790,
        "date": "31/03/2023 16:56 UTC",
        "pay_date": "31/03/2023 16:56 UTC",
        "datew3c": "2023-03-31T16:56:30+00:00",
        "pay_datew3c": "2023-03-31T16:56:41+00:00",
        "merchant_terminal_number": 1003,
        "invoice_transaction_id": 70,
        "national_id": "",
        "payer_firstname": "نام پرداخت کننده",
        "payer_lastname": "نام خانوادگی پرداخت کننده",
        "payer_email": "[email protected]",
        "payer_account_number": 10025
    },
    "success": true,
    "status": 200
}