Create payment session

1 curl -X POST https://api.payos.money/api/v1/checkout/session \ 2 -H "Content-Type: application/json" \ 3 -d '{ 4 "amount": 10000, 5 "currency": "ZAR", 6 "merchantReference": "ORDER-12345", 7 "merchantId": "550e8400-e29b-41d4-a716-446655440000", 8 "payerDetails": { 9 "emailAddress": "john.doe@example.com", 10 "location": "ZAF", 11 "fullName": "John Doe", 12 "phoneNumber": "+27821234567", 13 "payerId": "550e8400-e29b-41d4-a716-446655440001" 14 }, 15 "integrationType": "hosted", 16 "redirectUrl": "https://merchant.com/payment/callback" 17 }'

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

Create a new payment session

Request

This endpoint expects an object.

amountdoubleRequired>=0

Payment amount in minor units ( eg 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)

merchantIdstringRequired

Merchant UUID

payerDetailsobjectRequired

Payer details

integrationTypeenumRequired

Integration type

Allowed values:

redirectUrlstringOptional

Redirect URL after payment

Response

Session created successfully

sessionIdstring

Unique identifier for the session

paymentLinkstring or null

URL for the hosted checkout payment

payerIdstring or null

Unique identifier for the payer

signaturestring or null

HMAC signature for session verification

Request

Response

Errors