Skip to content

PayKKa API reference (v3)

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

Notify Webhook

Notify Webhook Documentation

Operations

Dispute Result Notification

Request

Dispute Result Notification

Bodyapplication/jsonrequired
event_typestring

Event Type

merchant_idstring

Merchant ID

merchant_namestring

Merchant Business Name

trans_idstring

Original Transaction Merchant Order Number

order_idstring

Original Transaction Gateway Order Number

dispute_idstring

Dispute ID

arnstring

ARN (if available, please provide)

card_binstring

Card BIN

card_last4string

Last 4 digits of card

payment_methodstring(Payment Method)

BankCard: Bank Card
eftpos: eftpos Australia
ApplePay: Apple Pay
GooglePay: Google Pay
WechatPayGlobal: WechatPayGlobal
AlipayPlus: Alipay+
SEPA: SEPA DirectDebit
Bancontact: Bancontact
EPS: EPS
iDEAL: iDEAL
P24: Online banking Poland, Przelewy24
Sofort: Sofort
GrabPay: GrabPay
Boost: Boost
Touch'n Go eWallet: Touch'n Go eWallet
Maybank QRPay: Maybank QRPay
ShopeePay: ShopeePay
LinePay: LinePay
9Pay: 9Pay
GCash: GCash
PayMaya: PayMaya
ZaloPay: ZaloPay
VietQR: VietQR
Pix: Pix
PicPay: PicPay
OpayWallet: OpayWallet

Enum"BankCard""eftpos""ApplePay""GooglePay""WechatPayGlobal""AlipayPlus""SEPA""Bancontact""EPS""iDEAL"
pay_finish_timestring(date-time)

Original Transaction Completion Time

dispute_stagestring

Dispute stage

reason_codestring

Reason Code

reason_code_descriptionstring

Reason Code Description

dispute_amountinteger(int64)

Dispute Amount

dispute_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"
order_amountinteger(int64)

Original Transaction Amount

order_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"
posting_datestring(date)

Institution Dispute Time

dispute_timestring(date-time)

Dispute Registration Time

due_timestring(date-time)

Appeal Deadline

curl -i -X POST \
  https://openapi-sandbox.paykka.com/v3/dispute/acq/NotifyUrlToYourUrl \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "DISPUTE",
    "merchant_id": "18356675194960",
    "merchant_name": "Test Merchant",
    "trans_id": "m58129512",
    "order_id": "GW2056xxxxx2136685",
    "dispute_id": "DG20324325320129",
    "arn": "ARN20324325320129",
    "card_bin": "424242",
    "card_last4": "4242",
    "payment_method": "BANKCARD",
    "pay_finish_time": "2025-04-18T19:34:34+08:00",
    "dispute_stage": "DISPUTE_CREATED",
    "reason_code": "REASON_CODE",
    "reason_code_description": "Reason Code Description",
    "dispute_amount": 100,
    "dispute_currency": "EUR",
    "order_amount": 100,
    "order_currency": "EUR",
    "posting_date": "2025-04-18",
    "dispute_time": "2025-04-18T19:34:34+08:00",
    "due_time": "2025-04-18T19:34:34+08:00"
  }'

Responses

ok

Bodyapplication/json
Response
application/json
{
  "ret_code": "000000",
  "ret_msg": "Success"
}

Payment Result Notification

Request

Payment Result Notification

Bodyapplication/jsonrequired
event_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"
payment_amountinteger(int64)

Payment amount

payment_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

authorization_codestring

Authorization code

notify_typestring(Merchant Notification Event)Deprecated

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"
curl -i -X POST \
  https://openapi-sandbox.paykka.com/v3/payment/acq/NotifyUrlToYourUrl \
  -H 'Content-Type: application/json' \
  -d '{
    "event_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

Bodyapplication/json
Response
application/json
{
  "ret_code": "000000",
  "ret_msg": "Success"
}

Refund Result Notification

Request

Refund Result Notification

Bodyapplication/jsonrequired
event_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

notify_typestring(Merchant Notification Event)Deprecated

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"
curl -i -X POST \
  https://openapi-sandbox.paykka.com/v3/refund/acq/NotifyUrlToYourUrl \
  -H 'Content-Type: application/json' \
  -d '{
    "event_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

Bodyapplication/json
Response
application/json
{
  "ret_code": "000000",
  "ret_msg": "Success"
}

Token

Token

Operations

Refund

Refund

Operations

Session

Session

Operations

Capture and Void

Capture and Void

Operations

Transaction

Transaction

Operations

Recurring Agreement

Recurring Agreement

Operations

Dispute

Dispute

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