Create payment session

curl -X POST https://api.payos.money/api/v1/checkout/session \
     -H "Content-Type: application/json" \
     -d '{
  "amount": 10000,
  "currency": "ZAR",
  "merchantReference": "ORDER-12345",
  "merchantId": "550e8400-e29b-41d4-a716-446655440000",
  "payerDetails": {
    "emailAddress": "john.doe@example.com",
    "location": "ZAF",
    "fullName": "John Doe",
    "phoneNumber": "+27821234567",
    "payerId": "550e8400-e29b-41d4-a716-446655440001"
  },
  "integrationType": "hosted",
  "redirectUrl": "https://merchant.com/payment/callback"
}'

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLink": "https://payos.com/checkout/550e8400-e29b-41d4-a716-446655440003",
  "payerId": "550e8400-e29b-41d4-a716-446655440001",
  "signature": "a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0"
}

Create a new payment session

Request

Create a new payment session

amountintegerRequired0-1000000000000

Payment amount in minor units (e.g. cents)

currencyenumRequired

Currency code

merchantReferencestringRequired

Unique merchant reference. Recommended to be only alphanumeric characters (for acceptance across providers, otherwise note that they might appear stripped to alphanumerics on customer’s statements, e.g. ref-123 -> ref123)

merchantIdstringRequiredformat: "uuid"

Merchant UUID

payerDetailsobjectRequired

Payer details

integrationTypeenumRequired

Integration type

Allowed values:

collectionCurrencyenumOptional

Currency the end customer pays in (ISO 4217). Defaults to the primary currency for payerDetails.location when omitted. Used for FX-enabled sessions to determine the source→collection pair.

redirectUrlstringOptionalformat: "uri"

URL the buyer is redirected to after payment. Hosted checkout appends ?status=completed|failed|cancelled before bouncing the buyer. Direct-API redirection flows redirect the buyer here with no ?status param — your page should render a processing state and rely on transaction webhooks for authoritative terminal status.

paymentAttributesmap from strings to stringsOptional

Payment-specific attributes and metadata that will be stored with the session

expiresInSecondsintegerOptional30-604800

Session lifetime in seconds. The payment confirmation window expires this long after creation; defaults to the standard session lifetime when omitted.

Response

Session created successfully

sessionIdstring

Unique identifier for the session

paymentLinkstring

URL for the hosted checkout payment

payerIdstringformat: "uuid"

Unique identifier for the payer

signaturestring

HMAC signature for session verification

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

500

Internal Server Error