ربط Stripe مع زاتكا

من فريق ماثل · آخر تحديث

Stripe (بوابة دفع) يبلغك لما الطلب يندفع، وماثل يحوّل هالدفعة لفاتورة زاتكا مرسلة ومقبولة، مع PDF عربي وإنجليزي فيه رمز QR.

الحدث اللي تستمع له

checkout.session.completed and checkout.session.async_payment_succeeded (Checkout / Payment Links); fulfill when payment_status != 'unpaid'

التسجيل

Dashboard > Workbench > Webhooks > Create an event destination > Your account > choose events > Webhook endpoint > Endpoint URL; copy the whsec_ signing secret. Or API POST /v2/core/event_destinations. Local test: stripe listen --forward-to localhost:4242/webhook

التحقق إن الطلب جاي من Stripe

Header Stripe-Signature (t=timestamp, v1=HMAC-SHA256 of 't.raw_body' with the whsec_ secret). Verify with Stripe::Webhook.construct_event on the raw body; default tolerance 5 minutes

المبلغ والبنود

بوابات الدفع ما ترسل بنود الطلب: الكود يجيبها من طلبك أنت برقم الطلب (الدالة load_order_items من نظامك، مو من ماثل).

لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "prices_include_vat": true.

الكود

يستقبل الحدث، يتحقق منه، ويستدعي matheel_invoice(items): الدالة الجاهزة اللي تقفل صف الجهاز وترسل الفاتورة وتحفظ المفتاح الجديد.

require 'sinatra'
require 'stripe'

client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))
endpoint_secret = ENV.fetch('STRIPE_WEBHOOK_SECRET') # whsec_...

post '/webhook' do
  payload = request.body.read
  begin
    event = Stripe::Webhook.construct_event(payload, request.env['HTTP_STRIPE_SIGNATURE'], endpoint_secret)
  rescue JSON::ParserError, Stripe::SignatureVerificationError
    halt 400
  end
  if %w[checkout.session.completed checkout.session.async_payment_succeeded].include?(event['type'])
    session = client.v1.checkout.sessions.retrieve(event['data']['object']['id'], {expand: ['line_items']})
    if session.payment_status != 'unpaid'
      items = session.line_items.data.map do |li|
        net = (li.amount_total - li.amount_tax) / 100.0 / li.quantity # halalas -> SAR, tax removed
        { name: li.description, quantity: li.quantity.to_s, price: format('%.2f', net) }
      end
      matheel_invoice(items)
    end
  end
  status 200
end

ملاحظات

amount_tax is only non-zero when Stripe computes tax. If the merchant's Stripe prices already include VAT and Stripe Tax is off, divide by 1.15 as well. expand returns only 'the first handful' of line items: for long carts, use the line-items list endpoint with auto-pagination. Stripe says fulfillment may run more than once, even concurrently, for the same session, so key the filing on the session id. Return 2xx quickly. Stripe's own sample hard-codes the whsec_ secret; this one reads it from the environment.

أسئلة شائعة

هل Stripe يرسل الفواتير لزاتكا بنفسه؟

Stripe بوابة دفع، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.

لازم أعدّل الأسعار عشان الضريبة؟

لا. أرسل المبلغ اللي دفعه العميل مع "prices_include_vat": true، وماثل يطلّع الضريبة ويخلّي المبلغ المستحق في الفاتورة نفس المدفوع.

وش يصير لو جت دفعتين بنفس الثانية؟

فواتير الجهاز تمشي ورا بعض. اقفل صف الجهاز وقت الإرسال (موجود في الدالة الجاهزة)، وماثل يرفض أي نسخة قديمة من مفتاح الجهاز بـ 409 عشان السلسلة ما تنكسر.

المصادر الرسمية: docs.stripe.com/webhooks · docs.stripe.com/checkout/fulfillment?ui=full-page · docs.stripe.com/api/checkout/sessions/line_items

جرّبه الحين على بيئة المطورين

بدون مفتاح ولا تسجيل: الرد رد الهيئة الحقيقي، ومعه الفاتورة PDF عربي وإنجليزي ورمز QR.

ابدأ الأسعار