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":"example","currency":"example","merchant_reference":"example","description":"","order_id":"","first_name":"example","last_name":"example","email":"hello@example.com","phone":"","items":[{"additionalProperty":"example"}],"metadata":"example","return_url":"","cancel_url":"","webhook_url":"","max_attempts":5}'
};

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": "example", "currency": "example", "merchant_reference": "example", "description": "", "order_id": "", "first_name": "example", "last_name": "example", "email": "hello@example.com", "phone": "", "items": [ { "additionalProperty": "example" } ], "metadata": "example", "return_url": "", "cancel_url": "", "webhook_url": "", "max_attempts": 5 }'

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

Input serializer for creating a payment session.

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

>= 1 characters <= 3 characters

merchant_reference

required

string

>= 1 characters <= 200 characters

description

string

"" >= 1 characters <= 500 characters

order_id

Merchant’s display-friendly order ID

string

"" >= 1 characters <= 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

"" >= 1 characters <= 20 characters

items

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

Array<object>

object

key

additional properties

metadata

return_url

string

"" >= 1 characters <= 2048 characters

cancel_url

string

"" >= 1 characters <= 2048 characters

webhook_url

string

"" >= 1 characters <= 2048 characters

max_attempts

integer

default: 5 >= 1 <= 10

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_first_name

string

<= 100 characters

buyer_last_name

string

<= 100 characters

buyer_email

string format: email

<= 255 characters

buyer_phone

string

<= 20 characters

metadata

return_url

string format: uri

<= 2048 characters

cancel_url

Redirect buyer here on payment failure or cancellation

string format: uri

<= 2048 characters

webhook_url

Per-session webhook URL override

string format: uri

<= 2048 characters

max_attempts

integer

<= 2147483647

checkout_url

required

string

expires_at

required

string format: date-time

completed_at

string format: date-time

nullable

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

card_last_four

required

string

failure_code

required

string

fee_amount

required

string

net_amount

required

string

created_at

required

string format: date-time

Example

{
  "status": "CREATED",
  "attempts": [
    {
      "status": "INITIATED"
    }
  ]
}

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_first_name

string

<= 100 characters

buyer_last_name

string

<= 100 characters

buyer_email

string format: email

<= 255 characters

buyer_phone

string

<= 20 characters

metadata

return_url

string format: uri

<= 2048 characters

cancel_url

Redirect buyer here on payment failure or cancellation

string format: uri

<= 2048 characters

webhook_url

Per-session webhook URL override

string format: uri

<= 2048 characters

max_attempts

integer

<= 2147483647

checkout_url

required

string

expires_at

required

string format: date-time

completed_at

string format: date-time

nullable

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

card_last_four

required

string

failure_code

required

string

fee_amount

required

string

net_amount

required

string

created_at

required

string format: date-time

Example

{
  "status": "CREATED",
  "attempts": [
    {
      "status": "INITIATED"
    }
  ]
}

409

The request conflicts with the current state of the resource.

application/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"
}

422

One or more fields failed validation.

application/json

Problem detail with a per-field errors array (422 responses).

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

required

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"
    }
  ]
}

Create a payment session

Authorizations

Request Bodyrequired

Responses

200

Example

201

Example

409

Examplegenerated

422

Examplegenerated

Request Body^required

Example^generated

Example^generated