Initiate Payment (Transaction)

Initiates a payment transaction for an existing checkout session. PayOS models a “payment” as a transaction; the primary identifier is transactionId.

Request

This endpoint expects an object.

paymentMethodIdenumRequired

Payment method identifier.

sessionIdstringRequired

Unique identifier for the session.

paymentDetailsobjectRequired

signaturestringOptional

Optional signature used for hosted checkout verification.

attributesmap from strings to stringsOptional

Optional transaction attributes.

Response

Transaction initiated successfully.

transactionIdstring

Unique identifier for the transaction.

statusstring

Current transaction status.

messagestring

Human-readable status message.

authStateobjectOptional

Detail for the transaction's current state. When the transaction status is AUTH_REQUIRED, authMethodType says how the payer completes authentication, and a matching detail object (redirect, fields, ussd, bankTransfer) carries the specifics. Error states instead carry code, message, and the raw connectorFailureCode/connectorFailureMessage.

Errors

400

Bad Request Error

401

Unauthorized Error

422

Unprocessable Entity Error

502

Bad Gateway Error