Skip to content

PayKKa API reference (v3)

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Generated server url
https://openapi.paykka.com/

Notify Webhook

Notify Webhook Documentation

Operations

Payment Result Notification

Request

Payment Result Notification

Headers
x-paykka-appidstringrequired

Entity identification, eg: 978594372956732

Example: 978594372956732
x-paykka-timestampstringrequired

Millisecond-level timestamp, it is recommended to exceed 5min

Example: 1757387467986
x-paykka-noncestringrequired

Request random numbers, anti-request replay

Example: 4326048250346354435
x-paykka-sign-algstringrequired

Signature Algorithm, eg: SHA256_WITH_RSA

Example: SHA256_WITH_RSA
x-paykka-signstringrequired

signature value

Example: Mif3gh48xxxxxxxxx
Bodyapplication/jsonrequired
notify_typestring(Merchant Notification Event)

PAYMENT.AUTHORIZATION: Payment Authorization Event
PAYMENT.SUCCESS: Payment Success Event
PAYMENT.FAILURE: Payment Failure Event
PAYMENT.CANCELED: Payment Canceled Event
REFUND.SUCCESS: Refund Success Event
REFUND.FAILURE: Refund Failure Event

Enum"PAYMENT.AUTHORIZATION""PAYMENT.SUCCESS""PAYMENT.FAILURE""PAYMENT.CANCELED""REFUND.SUCCESS""REFUND.FAILURE"
error_codestring

Error code

error_descriptionstring

Error description

merchant_idstring

Merchant ID

trans_idstring

Merchant order number

order_idstring

paykka order number

amountinteger(int64)

Amount

currencystring(Currency; Pass the ISO 3166-1 supported currency three-letter code)

Currency; Pass the ISO 3166-1 supported currency three-letter code

Enum"CNY""USD""JPY""RUB""EUR""GBP""HKD""AUD""CAD""INR"
Example: "USD"
statusstring(Gateway Order Status)

PROCESSING: Processing
SUCCESS: Succeeded
AUTHORIZED: Not Captured
FAILURE: Failed
REFUNDED: Refunded
PARTIALLY_REFUNDED: Partially Refunded
CANCELED: Canceled
PARTIALLY_REVERSED: Partially Reversed

Enum"PROCESSING""SUCCESS""AUTHORIZED""FAILURE""REFUNDED""PARTIALLY_REFUNDED""CANCELED""PARTIALLY_REVERSED"
pay_finish_timestring(date-time)

Payment completion time

recurring_agreement_idstring

Recurring agreement id

tokenstring

Card token

shopper_referencestring

Customer number

authentication_resultobject(AuthenticationRecordInNotify)

3DS verification result

expire_timestring(date-time)

Expiration time

session_idstring

Session ID

Example: "CS200395192979024625"
paymentobject(PaymentInfoRespInNotify)

Payment information

card_infoobject(CardInfoRespInNotify)

Payment card data

balancesobject(BalanceRespInNotify)

Balance

curl -i -X POST \
  https://openapi.paykka.com/v3/payment/acq/NotifyUrlOfYourPayments \
  -H 'Content-Type: application/json' \
  -H 'x-paykka-appid: 978594372956732' \
  -H 'x-paykka-nonce: 4326048250346354435' \
  -H 'x-paykka-sign: Mif3gh48xxxxxxxxx' \
  -H 'x-paykka-sign-alg: SHA256_WITH_RSA' \
  -H 'x-paykka-timestamp: 1757387467986' \
  -d '{
    "notify_type": "PAYMENT.AUTHORIZATION",
    "merchant_id": "18356675194960",
    "trans_id": "m58129512",
    "order_id": "GW2056xxxxx2136685",
    "status": "AUTHORIZED",
    "amount": 199,
    "currency": "EUR",
    "session_id": "CS20602223728587",
    "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
    "expire_time": "2025-03-08T10:00:00+08:00",
    "payment": {
      "payment_method": "BANKCARD"
    },
    "card_info": {
      "bin": "424242",
      "last4": "4242",
      "card_brand": "VISA"
    }
  }'

Responses

OK

Body*/*
ret_codestringrequired

ResultCode of current request

ret_msgstringrequired

ResultMessage of current request

Response
No content

Refund Result Notification

Request

Refund Result Notification

Headers
x-paykka-appidstringrequired

Entity identification, eg: 978594372956732

Example: 978594372956732
x-paykka-timestampstringrequired

Millisecond-level timestamp, it is recommended to exceed 5min

Example: 1757387467986
x-paykka-noncestringrequired

Request random numbers, anti-request replay

Example: 4326048250346354435
x-paykka-sign-algstringrequired

Signature Algorithm, eg: SHA256_WITH_RSA

Example: SHA256_WITH_RSA
x-paykka-signstringrequired

signature value

Example: Mif3gh48xxxxxxxxx
Bodyapplication/jsonrequired
notify_typestring(Merchant Notification Event)

PAYMENT.AUTHORIZATION: Payment Authorization Event
PAYMENT.SUCCESS: Payment Success Event
PAYMENT.FAILURE: Payment Failure Event
PAYMENT.CANCELED: Payment Canceled Event
REFUND.SUCCESS: Refund Success Event
REFUND.FAILURE: Refund Failure Event

Enum"PAYMENT.AUTHORIZATION""PAYMENT.SUCCESS""PAYMENT.FAILURE""PAYMENT.CANCELED""REFUND.SUCCESS""REFUND.FAILURE"
error_codestring

Error code

error_descriptionstring

Error description

merchant_idstring

Merchant ID

trans_idstring

Merchant return order number

refund_order_idstring

paykka return order number

order_idstring

Original transaction paykka order number

amountinteger(int64)

Amount

currencystring(Currency; Pass the ISO 3166-1 supported currency three-letter code)

Currency; Pass the ISO 3166-1 supported currency three-letter code

Enum"CNY""USD""JPY""RUB""EUR""GBP""HKD""AUD""CAD""INR"
Example: "USD"
statusstring(Gateway Refund Order Status)

REVIEWING: Reviewing
PROCESSING: Processing
SUCCESS: Succeeded
FAILURE: Failed

Enum"REVIEWING""PROCESSING""SUCCESS""FAILURE"
pay_finish_timestring(date-time)

Payment completion time

expire_timestring(date-time)

Expiration time

curl -i -X POST \
  https://openapi.paykka.com/v3/payment/acq/NotifyUrlOfYourRefund \
  -H 'Content-Type: application/json' \
  -H 'x-paykka-appid: 978594372956732' \
  -H 'x-paykka-nonce: 4326048250346354435' \
  -H 'x-paykka-sign: Mif3gh48xxxxxxxxx' \
  -H 'x-paykka-sign-alg: SHA256_WITH_RSA' \
  -H 'x-paykka-timestamp: 1757387467986' \
  -d '{
    "timestamp": 1744976074556,
    "notify_type": "REFUND.SUCCESS",
    "error_code": "0000",
    "error_description": "request success",
    "merchant_id": "18356675194960",
    "trans_id": "m58129512",
    "refund_order_id": "RG20324325320129",
    "order_id": "GW2056xxxxx2136685",
    "status": "SUCCESS",
    "amount": 2,
    "currency": "USD",
    "pay_finish_time": "2025-04-18T19:34:34+08:00"
  }'

Responses

OK

Body*/*
ret_codestringrequired

ResultCode of current request

ret_msgstringrequired

ResultMessage of current request

Response
No content

Transaction

Transaction

Operations

Refund

Refund

Operations

Session

Session

Operations
© 2025 PayKKa. All Rights Reserved. 粤ICP备2024262381号