Create a payment session

POST

/gateway/sessions/

const url = 'https://api.paymee.online/api/v1/gateway/sessions/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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","metadata":{"cart_id":"8812"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.paymee.online/api/v1/gateway/sessions/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "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", "metadata": { "cart_id": "8812" } }'

Create a payment session and its initial hosted checkout. The response includes a checkout_url to redirect the buyer to. Reusing the same merchant_reference returns the existing session (200) instead of creating a duplicate.

Currency. The buyer’s card is always charged, and you are always settled, in your account’s currency (TND). A request in TND is charged as sent. A request in another currency is converted at the exchange rate you configured for it (Settings → Currencies), rounded half-up to millimes; the response amount/currency are then the TND charge and original carries what you requested plus the rate applied. A request in a currency you have not configured a rate for is rejected with 422 and errors[].code = "currency_unsupported" on the currency field. The rate is frozen on the session at creation; later rate changes never alter an existing session, and an idempotent replay returns the original snapshot.

Authorizations

MerchantApiKey

Request Body^required

application/json

Input serializer for creating a payment session.

Optional strings accept "" as “no value” (as Stripe does), so a client that sends every field of a form, filled or not, is not refused.

object

amount

required

Amount as string with correct decimal places for currency

string

>= 1 characters

currency

ISO 4217 code. Defaults to the account’s currency when omitted.

string

<= 3 characters

merchant_reference

required

string

>= 1 characters <= 200 characters

description

string

"" <= 500 characters

order_id

Merchant’s display-friendly order ID

string

"" <= 100 characters

first_name

required

string

>= 1 characters <= 100 characters

last_name

required

string

>= 1 characters <= 100 characters

email

required

string format: email

>= 1 characters <= 255 characters

phone

string

"" <= 20 characters

items

Line items: [{name, quantity, unit_price, description}]

Array<object>

object

key

additional properties

metadata

return_url

string

"" <= 2048 characters

cancel_url

string

"" <= 2048 characters

webhook_url

string

"" <= 2048 characters

max_attempts

integer

default: 5 >= 1 <= 10

locale

Language of the payment page: fr, en, or auto (the default) to follow the buyer’s browser. The buyer can still switch language on the page. The card-entry page opens in the language the buyer is reading when they pay.

auto - The buyer’s browser language
fr - French
en - English

string

default: auto

Allowed values: auto fr en

Examples

CreateASession

Create a session

{
  "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",
  "metadata": {
    "cart_id": "8812"
  }
}

Responses

200

application/json

Response serializer for payment session detail.

object

required

string

merchant_reference

required

Merchant-provided unique reference for idempotency

string

<= 200 characters

order_number

required

System-generated order number (PM-XXXXXX)

string

<= 10 characters

order_id

Merchant order ID

Merchant’s display-friendly order ID (separate from merchant_reference)

string

<= 100 characters

amount

required

string

currency

string

<= 3 characters

original

required

object

amount

required

Requested amount, as a decimal string at the requested currency’s precision.

string

currency

required

Requested ISO 4217 currency code.

string

rate

required

Exchange rate applied (1 original.currency = rate currency), six decimals. “1.000000” when no conversion.

string

description

string

<= 500 characters

items

Line items: [{name, quantity, unit_price, description}]

status

CREATED - Created
PENDING - Pending
PROCESSING - Processing
SUCCEEDED - Succeeded
FAILED - Failed
EXPIRED - Expired
CANCELED - Canceled

string

Allowed values: CREATED PENDING PROCESSING SUCCEEDED FAILED EXPIRED CANCELED

livemode

required

boolean

buyer

required

object

first_name

required

string

last_name

required

string

email

required

string

phone

required

string

metadata

return_url

One of:

string
string

string format: uri

<= 2048 characters

cancel_url

One of:

string
string

string format: uri

<= 2048 characters

webhook_url

One of:

string
string

string format: uri

<= 2048 characters

max_attempts

integer

<= 2147483647

checkout_url

required

string | null

locale

required

Language of the payment page: fr, en, or auto (the buyer’s browser).

string

Allowed values: auto fr en

expires_at

required

string format: date-time

completed_at

string | null format: date-time

created_at

required

string format: date-time

attempts

required

Array<object>

Serializer for payment attempts (read-only).

object

required

string

attempt_number

required

integer

<= 2147483647

status

INITIATED - Initiated
PROCESSING - Processing
SUCCEEDED - Succeeded
FAILED - Failed
ABANDONED - Abandoned

string

Allowed values: INITIATED PROCESSING SUCCEEDED FAILED ABANDONED

card_brand

required

string | null

card_last_four

required

string | null

failure_code

required

The acquirer’s decline code, as webhooks carry it; None unless the attempt failed.

string | null

failure_message

required

The acquirer’s decline reason, as webhooks carry it; None unless the attempt failed.

string | null

fee_amount

required

string | null

net_amount

required

string | null

created_at

required

string format: date-time

refunds

required

Every refund of this session, oldest first.

Array<object>

A refund.

object

required

Refund id (re_…).

string

session_id

required

The refunded payment session (ps_…).

string

merchant_reference

required

The session’s merchant_reference.

string

amount

required

Refunded amount, as a decimal string.

string

currency

required

ISO 4217 currency of amount.

string

refund_type

FULL - Full
PARTIAL - Partial

string

Allowed values: FULL PARTIAL

status

required

PENDING while the refund is in progress, SUCCEEDED once the money is returned, FAILED if it was not.

string

Allowed values: PENDING SUCCEEDED FAILED

reason

Refund reason

string

processor_message

required

Why the refund is pending or failed, when known. Informational; may change.

string | null

created_at

required

string format: date-time

completed_at

required

When the refund reached SUCCEEDED or FAILED.

string | null

Example

{
  "status": "CREATED",
  "locale": "auto",
  "attempts": [
    {
      "status": "INITIATED"
    }
  ],
  "refunds": [
    {
      "refund_type": "FULL",
      "status": "PENDING"
    }
  ]
}

201

application/json

Response serializer for payment session detail.

object

required

string

merchant_reference

required

Merchant-provided unique reference for idempotency

string

<= 200 characters

order_number

required

System-generated order number (PM-XXXXXX)

string

<= 10 characters

order_id

Merchant order ID

Merchant’s display-friendly order ID (separate from merchant_reference)

string

<= 100 characters

amount

required

string

currency

string

<= 3 characters

original

required

object

amount

required

Requested amount, as a decimal string at the requested currency’s precision.

string

currency

required

Requested ISO 4217 currency code.

string

rate

required

Exchange rate applied (1 original.currency = rate currency), six decimals. “1.000000” when no conversion.

string

description

string

<= 500 characters

items

Line items: [{name, quantity, unit_price, description}]

status

CREATED - Created
PENDING - Pending
PROCESSING - Processing
SUCCEEDED - Succeeded
FAILED - Failed
EXPIRED - Expired
CANCELED - Canceled

string

Allowed values: CREATED PENDING PROCESSING SUCCEEDED FAILED EXPIRED CANCELED

livemode

required

boolean

buyer

required

object

first_name

required

string

last_name

required

string

email

required

string

phone

required

string

metadata

return_url

One of:

string
string

string format: uri

<= 2048 characters

cancel_url

One of:

string
string

string format: uri

<= 2048 characters

webhook_url

One of:

string
string

string format: uri

<= 2048 characters

max_attempts

integer

<= 2147483647

checkout_url

required

string | null

locale

required

Language of the payment page: fr, en, or auto (the buyer’s browser).

string

Allowed values: auto fr en

expires_at

required

string format: date-time

completed_at

string | null format: date-time

created_at

required

string format: date-time

attempts

required

Array<object>

Serializer for payment attempts (read-only).

object

required

string

attempt_number

required

integer

<= 2147483647

status

INITIATED - Initiated
PROCESSING - Processing
SUCCEEDED - Succeeded
FAILED - Failed
ABANDONED - Abandoned

string

Allowed values: INITIATED PROCESSING SUCCEEDED FAILED ABANDONED

card_brand

required

string | null

card_last_four

required

string | null

failure_code

required

The acquirer’s decline code, as webhooks carry it; None unless the attempt failed.

string | null

failure_message

required

The acquirer’s decline reason, as webhooks carry it; None unless the attempt failed.

string | null

fee_amount

required

string | null

net_amount

required

string | null

created_at

required

string format: date-time

refunds

required

Every refund of this session, oldest first.

Array<object>

A refund.

object

required

Refund id (re_…).

string

session_id

required

The refunded payment session (ps_…).

string

merchant_reference

required

The session’s merchant_reference.

string

amount

required

Refunded amount, as a decimal string.

string

currency

required

ISO 4217 currency of amount.

string

refund_type

FULL - Full
PARTIAL - Partial

string

Allowed values: FULL PARTIAL

status

required

PENDING while the refund is in progress, SUCCEEDED once the money is returned, FAILED if it was not.

string

Allowed values: PENDING SUCCEEDED FAILED

reason

Refund reason

string

processor_message

required

Why the refund is pending or failed, when known. Informational; may change.

string | null

created_at

required

string format: date-time

completed_at

required

When the refund reached SUCCEEDED or FAILED.

string | null

Example

{
  "status": "CREATED",
  "locale": "auto",
  "attempts": [
    {
      "status": "INITIATED"
    }
  ],
  "refunds": [
    {
      "refund_type": "FULL",
      "status": "PENDING"
    }
  ]
}

400

Malformed request: the body is not valid JSON, or a header is invalid.

application/problem+json

RFC 9457 problem detail body (application/problem+json).

object

type

required

URI identifying the error type.

string format: uri

title

required

Short, human-readable summary of the error type.

string

status

required

HTTP status code.

integer

detail

required

Human-readable explanation specific to this occurrence.

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

401

Missing, malformed, expired, or revoked API key.

application/problem+json

RFC 9457 problem detail body (application/problem+json).

object

type

required

URI identifying the error type.

string format: uri

title

required

Short, human-readable summary of the error type.

string

status

required

HTTP status code.

integer

detail

required

Human-readable explanation specific to this occurrence.

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

409

The request conflicts with an earlier one; the type says how.

application/problem+json

Problem detail of a 409.

object

type

required

URI identifying the error type.

string format: uri

title

required

Short, human-readable summary of the error type.

string

status

required

HTTP status code.

integer

detail

required

Human-readable explanation specific to this occurrence.

string

existing_session_id

On a conflict from session creation: the session that already uses this merchant_reference.

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "existing_session_id": "example"
}

422

A field failed validation (errors lists them), or a business rule refused the request (the type says which).

application/problem+json

Problem detail of a 422: a per-field errors array when fields failed validation; no errors when a business rule refused the request (the type says which).

object

type

required

URI identifying the error type.

string format: uri

title

required

Short, human-readable summary of the error type.

string

status

required

HTTP status code.

integer

detail

required

Human-readable explanation specific to this occurrence.

string

errors

Array<object>

A single field-level validation error inside a problem+json body.

object

field

required

Name of the field that failed validation.

string

code

required

Machine-readable error code, e.g. ‘required’.

string

message

required

Human-readable description of the failure.

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

429

Rate limit exceeded. Wait the number of seconds in the Retry-After header.

application/problem+json

RFC 9457 problem detail body (application/problem+json).

object

type

required

URI identifying the error type.

string format: uri

title

required

Short, human-readable summary of the error type.

string

status

required

HTTP status code.

integer

detail

required

Human-readable explanation specific to this occurrence.

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

500

Unexpected error; nothing was changed. Safe to retry with backoff.

application/problem+json

RFC 9457 problem detail body (application/problem+json).

object

type

required

URI identifying the error type.

string format: uri

title

required

Short, human-readable summary of the error type.

string

status

required

HTTP status code.

integer

detail

required

Human-readable explanation specific to this occurrence.

string

Example^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

Create a payment session

Authorizations

Request Bodyrequired

Examples

Responses

200

Example

201

Example

400

Examplegenerated

401

Examplegenerated

409

Examplegenerated

422

Examplegenerated

429

Examplegenerated

500

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated