Skip to content
Paymee Developers

Quickstart

Download .md

This guide takes you from zero to a working payment in under 10 minutes. You will create a payment session and redirect a test buyer to the hosted checkout.

Prerequisites

Section titled “Prerequisites”
  • A Paymee merchant account.
  • Your test secret key (sk_test_…) from the dashboard. See Authentication.

  1. Create a payment session

    Section titled “Create a payment session”

    Send your first request. The only required fields are the amount, a unique merchant_reference, and the buyer’s name and email.

    Terminal window
    curl https://api.paymee.online/api/v1/gateway/sessions/ \
      -H "Authorization: Bearer sk_test_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": "10.500",
        "currency": "TND",
        "merchant_reference": "order-0001",
        "first_name": "Aymen",
        "last_name": "Ben Salah",
        "email": "aymen@example.com",
        "return_url": "https://your-site.tn/orders/order-0001/paid",
        "cancel_url": "https://your-site.tn/cart",
        "webhook_url": "https://your-site.tn/webhooks/paymee"
      }'

    Send amount as a string with exactly three decimals for TND ("10.500"). All URLs must use https:// on a public domain name; to receive webhooks on your own machine, expose it through an HTTPS tunnel.

  2. Read the response

    Section titled “Read the response”

    A 201 Created returns the session, including its checkout_url:

    {
      "id": "ps_0b7c3a1e-5d2f-4e8a-9c6b-1f2e3d4c5b6a",
      "merchant_reference": "order-0001",
      "amount": "10.500",
      "currency": "TND",
      "status": "CREATED",
      "livemode": false,
      "checkout_url": "https://pay.paymee.online/checkout/kq2V8Zr3xN0bT6mW1yPdF4sHjL9cA7uE",
      "expires_at": "2026-11-21T10:24:00.000000Z"
    }

    The full response has more fields — see Hosted checkout.

  3. Redirect the buyer

    Section titled “Redirect the buyer”

    Send the buyer to the checkout_url. They pay on the Paymee-hosted page (with 3-D Secure). After a successful payment, Paymee redirects them to your return_url; the page’s Return to store button takes them to your cancel_url.

    res.redirect(session.checkout_url);

  4. Pay with a test card

    Section titled “Pay with a test card”

    On the checkout page, use a test card:

    • Visa 4509 2111 1111 1119, expiry 12/26, CVV 748
    • 3-D Secure code: 12345

  5. Receive the result

    Section titled “Receive the result”

    Do not rely on the buyer returning to return_url to mark an order paid (they may close the tab). Instead, handle the webhooks Paymee sends to your webhook_url:

    • session.succeeded → fulfil the order
    • session.failed → every attempt was declined: the session is closed; offer a new payment (with a new merchant_reference)
    • session.expired → the buyer never paid: release the order

    Set up and verify webhooks next: Webhooks.

What’s next

Section titled “What’s next”