PWI-Retrieve

When the card details are entered in the payment form and the "Pay X TL" button is pressed, iyzico will redirect to the callbackUrl address that you specified during the creation of the payment form. At this address, a token value will be posted by iyzico. To view additional details about the payment results, a second query must be made using this token.

Following service represents the usage of token;

Pay with iyzico (PWI) — Retrieve

post

Queries the PWI transaction result by token.

Header parameters

AuthorizationstringRequired

Authorization header; starts with IYZWSv2 and is a signed hash in Base64.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequiredExample: application/json

Body

localestring · enumOptional

Language code. Default; tr

Example: enPossible values:

conversationIdstringOptional

Request/response correlation ID.

Example: 8152109759

tokenstringRequired

Token of the PWI session to be retrieved.

Example: da7431f4-89fc-4f65-8533-d83a4fede7d9

Responses

200

Successful response (payment completed)

application/json

statusstring · enumOptional

Outcome of the request.

Example: successPossible values:

localestring · enumOptional

Response language (tr/en).

Example: enPossible values:

systemTimeintegerOptional

Timestamp (epoch ms).

Example: 1755252706797

conversationIdstringOptional

Correlation ID of the request.

Example: 8152109759

pricedecimalOptional

Basket total.

Example: 10

paidPricedecimalOptional

Total collected amount.

Example: 10

installmentintegerOptional

Installment count.

Example: 1

paymentIdstringOptional

Payment ID.

Example: 25152948

fraudStatusinteger · enumOptional

Fraud status of the payment.

1: Approved
0: In review
-1: Rejected

Example: 1Possible values:

merchantCommissionRatedecimalOptional

Merchant’s commission/deferral rate (informational). For example, if price=100 and paidPrice=110, the rate is 10%.

Example: 0

merchantCommissionRateAmountdecimalOptional

Merchant’s commission/deferral amount (informational). For example, if price=100 and paidPrice=110, the amount is 10.

Example: 0

iyziCommissionRateAmountdecimalOptional

iyzico commission amount for the payment.

Example: 0.2094

iyziCommissionFeedecimalOptional

iyzico fee for the payment.

Example: 0.25

cardTypestring · enumOptional

Card type.

Example: CREDIT_CARDPossible values:

cardAssociationstring · enumOptional

Card association.

Example: MASTER_CARDPossible values:

cardFamilystring · enumOptional

Card family.

Example: AxessPossible values:

binNumberstringOptional

BIN (first 8 digits).

Example: 552608

lastFourDigitsstringOptional

Last four digits of the card.

Example: 0006

basketIdstringOptional

Basket ID.

Example: basketId

currencystring · enumOptional

Currency of the payment.

Example: TRYPossible values:

authCodestringOptional

Auth code returned by the bank.

Example: 277568

phasestringOptional

Payment phase.

Example: AUTH

hostReferencestringOptional

Bank-provided host reference for the payment.

Example: mock00007iyzihostrfn

signaturestringOptional

Signature value for verification.

Example: 57b1be1f094d17da286c748e2b2779e078e550bafe9734d4fd8c092aeee022be

tokenstringOptional

Token associated with the transaction (returned by the retrieval).

Example: 0b7b67d2-fdf0-4c9a-905f-2b0003b1b8c7

callbackUrlstringOptional

Callback URL sent at initialization.

Example: https://callbackurl.com

paymentStatusstring · enumOptional

Payment status.

Example: SUCCESSPossible values:

memberEmailstringOptional

Email of the member who paid via PWI.

Example: test@gmail.com

memberGsmNumberstringOptional

GSM number of the member who paid via PWI.

Example: +905555555555

400

Bad request / validation error

application/json

post/payment/iyzipos/checkoutform/auth/ecom/detail

POST https://api.iyzipay.com/payment/iyzipos/checkoutform/auth/ecom/detail
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "8152109759",
  "token": "da7431f4-89fc-4f65-8533-d83a4fede7d9"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755252706797,
  "conversationId": "8152109759",
  "price": 10,
  "paidPrice": 10,
  "installment": 1,
  "paymentId": "25152948",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.349,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552608",
  "lastFourDigits": "0006",
  "basketId": "basketID",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "ItemID",
      "paymentTransactionId": "27142369",
      "transactionStatus": 2,
      "price": 10,
      "paidPrice": 10,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.349,
      "iyziCommissionFee": 0.25,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-08-23 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 9.401,
      "convertedPayout": {
        "paidPrice": 10,
        "iyziCommissionRateAmount": 0.349,
        "iyziCommissionFee": 0.25,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 9.401,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "277568",
  "phase": "AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "57b1be1f094d17da286c748e2b2779e078e550bafe9734d4fd8c092aeee022be",
  "token": "0b7b67d2-fdf0-4c9a-905f-2b0003b1b8c7",
  "callbackUrl": "callbackUrl",
  "paymentStatus": "SUCCESS",
  "memberEmail": "test@gmail.com",
  "memberGsmNumber": "+905555555555"
}

Sample Codes

PreviousPWI-Initialize

NextPWI Sample Imp.

Last updated 10 months ago