Initiate Payment

curl -X POST https://api.payos.money/api/v1/payment \
     -H "Content-Type: application/json" \
     -d '{
  "sessionId": "string",
  "paymentMethodId": "card",
  "paymentDetails": {
    "type": "card",
    "encryptedCardNumber": "string",
    "cardExpiryMonth": "string",
    "cardExpiryYear": "string",
    "encryptedCardCvv": "string",
    "cardHolderName": "string",
    "payerEmail": "string"
  }
}'

{
  "status": "string",
  "transactionId": "string",
  "message": "string",
  "authState": {
    "state": "string",
    "transitionedAt": "string",
    "transactionId": "string"
  },
  "merchantReference": "string",
  "sessionId": "string",
  "identifiers": {},
  "paymentAttributes": {},
  "paymentMethodId": "string",
  "processorName": "string",
  "processorReference": "string",
  "financialTransactionReference": "string",
  "currentAttemptId": "string",
  "batchPayoutId": "string",
  "collection": {
    "amount": "string",
    "currency": "string"
  },
  "fxMidRate": "string",
  "fxAllInRate": "string",
  "fxMarkupBps": 1,
  "fxFee": {
    "amount": "string",
    "currency": "string"
  }
}

Processes a payment transaction directly.

Request

Payment initiation request

sessionIdstringRequired

Session ID from checkout session creation

paymentMethodIdenumRequired

Payment method identifier

paymentDetailsobjectRequired

Payment method specific details

attributesmap from strings to stringsOptional

Additional transaction attributes as key-value pairs

signaturestringOptional

HMAC signature for hosted checkout validation

Response

Payment processed with result

statusstring

Current transaction status

transactionIdstring

Unique transaction identifier

messagestring

Status message describing the transaction state

authStateobjectOptional

Authentication state union containing all possible transaction states

merchantReferencestringOptional

Merchant reference from the original session

sessionIdstringOptionalformat: "uuid"

Session ID associated with the transaction

identifiersmap from strings to stringsOptional

Additional identifiers related to the transaction

paymentAttributesmap from strings to stringsOptional

Payment-specific attributes and metadata

paymentMethodIdstringOptional

Payment method identifier

processorNamestringOptional

Payment processor name

processorReferencestringOptional

Payment processor reference

financialTransactionReferencestringOptional

Financial transaction reference from the processor

currentAttemptIdstringOptional

Current attempt identifier

batchPayoutIdstringOptional

Batch payout identifier, if the transaction is part of a batch payout

collectionobjectOptional

Monetary amount as a decimal-string major unit + currency code

fxMidRatestringOptionalformat: "^\d+(\.\d+)?$"

Spot mid-market rate at the time the quote was committed (8 decimal places).

fxAllInRatestringOptionalformat: "^\d+(\.\d+)?$"

Mid rate + markup — the rate actually applied to convert source to collection (8 decimal places).

fxMarkupBpsintegerOptional>=0

Markup applied in basis points (0–10000).

fxFeeobjectOptional

Monetary amount as a decimal-string major unit + currency code

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error