ارسال صورت حساب

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

POST https://api.gap.im/invoice

send invoice

نام داده نوع الزامی توضیحات
chat_id integer بلی شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
amount ‍ integer بلی مقدار هزینه صورتحساب منتشر شده شما که کاربر باید پرداخت کند به ریال.
description string بلی توضیحات صورت حساب.
  • پس از ارسال صورتحساب، پیام‌رسان گپ در پاسخ درخواست شما یک id ارسال خواهد کرد که شما می‌بایست این مقدار را در بانک اطلاعاتی خود ذخیره کنید تا در صورت لزوم بتوانید از آن استفاده کنید.
  • پس از انجام موفقیت آمیز پرداخت توسط کاربر، یک درخواست به سمت برنامه توسعه دهنده، توسط گپ ارسال خواهد شد که مقدار type آن برابر invoiceCallback و مقدار پارامتر id خواهد بود که توسعه دهنده به وسیله آن می‌تواند تراکنش مورد نظر خود را شناسایی و از طریق متود تایید صورتحساب آن را تایید کند.

200 Success Request

پارامتر توضیحات
id شناسه صورتحساب ارسالی شما. در واقع همان invoice_id می‌باشد که باید آن را جهت پیگیری‌های بعدی حتما ذخیره کنید.

Error 400 Bad Request

پارامتر توضیحات
chat_id داده ارسالی معتبر نمی‌باشد.
amount داده ارسالی معتبر نمی‌باشد.

invoiceCallback

هنگامی که یک صورت حساب توسط کاربر با موفقیت پرداخت می‌شود، یک درخواست توسط گپ برای توسعه دهنده ارسال می‌شود که مقدار type آن برابر invoicecallback و مقدار data بدین صورت می‌باشد.

[
    "invoiceId":"5ehs534a74ns8a25732b9e9"
]
  • توسعه دهنده می‌تواند با استفاده از مقدار invoiceId تراکنش را شناسایی کند.

تایید صورتحساب

پس از پرداخت موفق صورتحساب توسط کاربر، لازم است توسعه دهنده نسبت به تایید این صورتحساب اقدام نماید.

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

POST https://api.gap.im/invoice/verify

نام داده نوع الزامی توضیحات
chat_id integer بلی شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍ integer بلی invoice_id که در هنگام ارسال صورتحساب برای توسعه دهنده ارسال شده است.

200 Success Request

پارامتر توضیحات
amount این مقدار مشخص کننده مبلغ صورتحساب است.
status مشخص کننده وضعیت صورتحساب است. که مقدار آن برابر است با یکی از مقادیر [error, verified]

Error 400 Bad Request

پارامتر توضیحات
chat_id داده ارسالی معتبر نمی‌باشد.
ref_id داده ارسالی معتبر نمی‌باشد.

استعلام صورتحساب

برای استعلام وضعیت صورتحسابی که قبلا برای کاربر ارسال کرده‌اید، می‌توانید از این متود استفاده کنید.

POST https://api.gap.im/invoice/inquiry

نام داده نوع الزامی توضیحات
chat_id integer بلی شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍ integer بلی invoice_id که در هنگام ارسال صورتحساب برای توسعه دهنده ارسال شده است.

200 Success Request

پارامتر توضیحات
amount این مقدار مشخص کننده مبلغ صورتحساب است.
status مشخص کننده وضعیت صورتحساب است. که یکی از حالت‌های [error, verified]

Error 400 Bad Request

پارامتر توضیحات
chat_id داده ارسالی معتبر نمی‌باشد.
ref_id داده ارسالی معتبر نمی‌باشد.

پرداخت درون برنامه ای

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

[
  [
    ['text' => 'دونیت', 'amount' => 2000, 'currency' => 'IRR', 'ref_id' => 'XXXXXXX', 'desc' => 'توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها'],
  ]
]
پارامتر الزامی توضیحات
text بلی مقدار قرار گرفته در این پارامتر در واقع متنی است که در داخل دکمه قرار می‌گیرد و کاربر آن را می‌بیند.
amount بلی این مقدار به منظور گرفتن وجه از کاربر به شکل پرداخت درون برنامه‌ای می‌باشد.
currency بلی این مقدار مشخص کننده واحد پول است. که در حال حاضر می‌تواند برای پرداخت‌های ریالی مقدار IRR و پرداخت گپسی مقدار coin را دریافت کند.
ref_id بلی یک رشته Base64 شامل حروف و ارقام می‌باشد که در واقع یک کد منحصر بفرد است که توسط توسعه دهنده ایجاد شده و برای شناسایی کاربر پس از انجام روال پرداخت استفاده می‌شود. پس از انجام پرداخت توسط کاربر و یا به وجود آمدن خطا در روال پرداخت، گپ یک درخواست به منظور اعلام نتیجه برای توسعه دهنده ارسال می‌کند که از نوع payCallback و شامل مقدار ref_id نیز می‌باشد.
desc خیر توضیحات مربوط به پرداخت که برای نمایش در لیست تراکنش‌ها استفاده می‌شود.
  • در مدل پرداخت درون برنامه‌ای در صورتی که که کاربر روی دکمه مربوط به آن کلیک کند، پیغامی مبنی بر پرداخت مشاهده می‌کند که در صورت تایید آن بدون ارجاع به صفحه کیف پول گپ، در صورت کافی بودن موجودی، بلافاصله پرداخت انجام می‌شود.
payCallback
  • هنگامی که یک صورت حساب از نوع پرداخت درون برنامه‌ای توسط Inline Button برای کاربر ایجاد می‌شود و کاربر بروی آن کلیک می‌کند برای انجام روال پرداخت در صورت انجام موفقیت‌آمیز پرداخت و یا ایجاد خطا، یک درخواست توسط گپ برای توسعه دهنده ارسال می‌شود که مقدار type آن برابر payCallback و مقادیر آن بدین صورت می‌باشد.
[
  ref_id: 'XXXXXXX', // کد منحصر بفردی که در زمان ایجاد دکمه inline Button توسط توسعه دهنده ایجاد می‌کند برای پیگیری روند پرداخت.
  message_id: 'XXXXXXX', // شناسه پیام که کاربر بروی inline keyboard آن کلیک کرده است.
  status: 'error', // وضغیت پرداخت صورتحساب
  code: 1000,
]
  • پارمتر code که از آن برای شناسایی بهتر پیام سرور به توسعه دهنده می توان استفاده کرد داری یکی از مقادیر زیر می‌باشد.
مقدار توضیحات
1000 موجودی کافی نیست.
در هنگام ارسال این مقدار پارامتر دیگری هم ارسال می شود که نامش charge_url می باشد و مقدار آن یک url است که می توانید آن را به شکل inline keyboard و از طریق url برای کاربر ارسال کنید که کاربر با کلیک بروی آن می‌تواند کیف پول خود را شارژ کند.
1001 پارامتر انکد شده نا معتبر است.
1002 پارامتر ارسالی نامعتبر است.
1003 شناسه تکراری است.
1004 خطا در عملیات پرداخت از طریق کیف گپ لطفا دوباره امتحان نمایید.
1005 تراکنش پرداخت تایید نشده است.
1006 خطا در تایید تراکنش پرداخت.

تایید پرداخت درون برنامه‌ای

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

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

POST https://api.gap.im/payment/verify

نام داده نوع الزامی توضیحات
chat_id integer بلی شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍ integer بلی ref_id که در هنگام ایجاد دکمه پرداخت توسط توسعه دهنده تولید شده است.

200 Success Request

پارامتر توضیحات
amount این مقدار مشخص کننده مبلغ پرداخت است.
status مشخص کننده وضعیت پرداخت است. که مقدار آن برابر است با یکی از مقادیر [error, verified]

Error 400 Bad Request

پارامتر توضیحات
chat_id داده ارسالی معتبر نمی‌باشد.
ref_id داده ارسالی معتبر نمی‌باشد.

استعلام پرداخت درون برنامه‌ای

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

POST https://api.gap.im/payment/inquiry

نام داده نوع الزامی توضیحات
chat_id integer بلی شناسه ایجاد شده برای کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است.
ref_id ‍ integer بلی ref_id که در هنگام ایجاد دکمه پرداخت توسط توسعه دهنده تولید شده است.

200 Success Request

پارامتر توضیحات
amount این مقدار مشخص کننده مبلغ است.
status مشخص کننده وضعیت پرداخت است. که مقدار آن برابر است با یکی از مقادیر [error, verified]

Error 400 Bad Request

پارامتر توضیحات
chat_id داده ارسالی معتبر نمی‌باشد.
ref_id داده ارسالی معتبر نمی‌باشد.