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 sandbox 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/payment/success",
        "cancel_url": "https://your-site.tn/payment/cancel",
        "webhook_url": "https://your-site.tn/webhooks/paymee"
      }'

  2. Read the response

    Section titled “Read the response”

    A 201 Created returns the session, including a checkout_url:

    {
      "id": "ps_3Nk8x2c9aQ...",
      "merchant_reference": "order-0001",
      "amount": "10.500",
      "checkout_url": "https://pay.paymee.online/checkout/tok_abc123...",
      "status": "CREATED"
    }

  3. Redirect the buyer

    Section titled “Redirect the buyer”

    Send the buyer to the checkout_url. They complete payment on the Paymee-hosted page (with 3-D Secure). When done, Paymee redirects them back to your return_url (or cancel_url if they abandon).

    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 OTP: 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 webhook Paymee sends to your webhook_url:

    • session.succeeded → fulfil the order
    • session.failed → show a failure and let them retry

    Set up and verify webhooks next: Webhooks.

What’s next

Section titled “What’s next”