Notify Webhook Documentation
PayKKa API reference (v3)
Download OpenAPI description
Languages
Servers
Generated server url
https://openapi-sandbox.paykka.com
Headers
Bodyapplication/jsonrequiredIdentification of Entity or Partner, eg: 978594372956732
Example: 978594372956732
Millisecond-level timestamp, it is recommended to exceed 5min
Example: 1757387467986
Request random numbers, anti-request replay
Example: 4326048250346354435
Merchant Name Displayed to Customer, Default by PayKKa if Empty
- Generated server urlhttps://openapi-sandbox.paykka.com/v3/payment/acq/apple-pay/create-session
- cURL
- Python
- PHP
- Node.js
- Ruby
- Java
- ApacheHttpClint
- Go
- JS
- C#
curl -i -X POST \
https://openapi-sandbox.paykka.com/v3/payment/acq/apple-pay/create-session \
-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 '{
"merchant_id": "18356675194960",
"timestamp": 1745922570644,
"display_name": "Your Merchant Name",
"domain_name": "www.mydomain.com"
}'Headers
Bodyapplication/jsonrequiredIdentification of Entity or Partner, eg: 978594372956732
Example: 978594372956732
Millisecond-level timestamp, it is recommended to exceed 5min
Example: 1757387467986
Request random numbers, anti-request replay
Example: 4326048250346354435
Merchant order number (all three cannot be empty)
Example: "t202311081113"
PayKKa order number (all three cannot be empty)
Example: "GW200395192979024625"
- Generated server urlhttps://openapi-sandbox.paykka.com/v3/payment/acq/query
- cURL
- Python
- PHP
- Node.js
- Ruby
- Java
- ApacheHttpClint
- Go
- JS
- C#
curl -i -X POST \
https://openapi-sandbox.paykka.com/v3/payment/acq/query \
-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 '{
"merchant_id": "18356675194960",
"trans_id": "",
"order_id": "GW20620xxxxx6999",
"session_id": "",
"timestamp": 1746515084018
}'ok
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"
Authorization type, default FINAL_AUTH
Value"FINAL_AUTH"
Example: "FINAL_AUTH"
Transaction amount, minimum denomination of the country's currency
Example: 1250
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 amount, minimum denomination of the country's currency
Example: 1250
Currency; Pass the ISO 3166-1 supported currency three-letter code
Enum"CNY""USD""JPY""RUB""EUR""GBP""HKD""AUD""CAD""INR"
Example: "USD"
Recurring payment agreement ID, returned for recurring payments
Example: "RA37285619238472"
Customer reference, required when store_payment_method=true or token payment
Example: "user1234567890"
Response
application/json
- Payments Processing
- Payments Authorized
- Payments Success
- Payments Failed
- Payments partially reversed
- Payments Canceled
{ "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "174293243204402", "order_id": "GW20620xxxxx6999", "status": "PROCESSING", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "amount": 100, "currency": "EUR", "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11", "expire_time": "2025-05-06T14:40:43+08:00", "payment": { "payment_method": "BANKCARD" }, "card_info": { "bin": "424242", "last4": "4242", "card_brand": "VISA", "card_type": "DEBIT", "issuer_bank": "CIAGROUP", "issuer_country": "BR", "exp_year": "2045", "exp_month": "01" }, "balances": { "authed_amount": 100, "captured_amount": 0, "able_to_capture_amount": 100, "voided_amount": 0, "able_to_void_amount": 100, "refunded_amount": 0, "able_to_refund_amount": 0 } } }
Headers
Bodyapplication/jsonrequiredIdentification of Entity or Partner, eg: 978594372956732
Example: 978594372956732
Millisecond-level timestamp, it is recommended to exceed 5min
Example: 1757387467986
Request random numbers, anti-request replay
Example: 4326048250346354435
Authorization type, default FINAL_AUTH
Value"FINAL_AUTH"
Example: "FINAL_AUTH"
Currency; Pass the ISO 3166-1 supported currency three-letter code
Enum"CNY""USD""JPY""RUB""EUR""GBP""HKD""AUD""CAD""INR"
Example: "USD"
Transaction amount, enter a value that conforms to the minimum unit rule of the transaction currency (e.g.: USD/CNY unit is cent, JPY unit is yen)
Example: 1250
Transaction notification Webhook address; When the transaction status changes, the transaction result will be sent to the corresponding URL (Recommended to configure uniformly on PayKKa platform)
Example: "https://www.baidu.com/notifyUrl"
Transaction redirect address; When the transaction triggers 3D secure verification completion or the checkout payment is completed, this URL is required for non-subsequent recurring payments
Example: "https://www.baidu.com/returnUrl"
Consumer payment data
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"
Example: "BANKCARD"
Whether to store card information If payment_type is PURCHASE, this field is True means the customer chooses to save payment information to enable future quick payments If payment_type is RECURRING, this field is True means to inform the customer that the payment will be saved for subsequent recurring payments when the current order payment is completed
Example: false
token usage (recurring transactions - SUBSCRIPTION, spending transactions - CARD_ON_FILE), must be passed when store_payment_method=true or token payment is required
Enum"CARD_ON_FILE""SUBSCRIPTION"
Customer number, required when store_payment_method=true or token payment
Example: "user1234567890"
Card token, one of [token, card_no, encrypted_card_no] for BANKCARD payment
Example: "CS200395192979024625"
Card number, one of [token, card_no, encrypted_card_no] for BANKCARD payment
Example: "4342561111118885"
Encrypted expiry year, required if cardNo is filled
Encrypted expiry month, required if cardNo is filled
(Merchant decryption is required) GooglePay/ApplePay decrypted authentication data Details: https://developers.google.com/pay/api/processors/guides/implementation/understand-our-payload?hl=zh-cn#assurance-details-specification Details: https://developer.apple.com/documentation/passkit/payment-token-format-reference#//apple_ref/doc/uid/TP40014929-CH8-SW1
Product or service display link, reflecting the access link of product or service information for this transaction, allowing users to view related product descriptions or transaction content
Example: "https://www.apple.com/shop/buy-ipad/ipad-air/11-inch-display-512gb-blue-wifi-cellular"
Product price, pass the minimum denomination amount of the corresponding country's currency (e.g., USD/CNY unit is cents, JPY unit is yen)
Example: 625
Bill information (can be empty for recurring payments; if customer website collects bill information, it is recommended to pass in according to the rule when payment method=card)
Shipping information (required for goods trade, optional for other trades)
Customer user information
User payment IP address, e.g.: 202.96.209.10. Payment IP is the ip when the user actually pays, which may be different from the order ip. Not required for mit scenarios.
User order IP address, e.g.: 202.96.209.16. Order IP is the ip when the user creates the order in the shopping cart. Not required for mit scenarios.
3DS authentication parameters; Optional for non-card payment methods
[Recurring Payment] Recurring payment agreement ID, required for non-first recurring payments
Example: "RA37285619238472"
- Generated server urlhttps://openapi-sandbox.paykka.com/v3/payment/acq
- cURL
- Python
- PHP
- Node.js
- Ruby
- Java
- ApacheHttpClint
- Go
- JS
- C#
- Initiate Purchase Payments
- Initiate Recurring Payments
- Initiate Recurring Payments by merchants
- Initiate Payments with sensitive card data
- Initiate Payments with encrypted card data
- GooglePay with decrypted data
- GooglePay with original data
- ApplePay with decrypted data
- ApplePay with original data
curl -i -X POST \
https://openapi-sandbox.paykka.com/v3/payment/acq \
-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 '{
"trans_id": "174293243204408",
"merchant_id": "18356675194960",
"payment_type": "PURCHASE",
"authorisation_type": "FINAL_AUTH",
"capture_method": "AUTOMATIC",
"timestamp": 1746515589126,
"currency": "EUR",
"amount": 100,
"return_url": "https://your_url",
"payment": {
"payment_method": "BANKCARD",
"shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11",
"card_no": "4242424242424242",
"exp_year": "2029",
"exp_month": "03",
"cvv": "123",
"holder_name": "Winifred Reopell",
"holder_email": "zhangsan@test.com"
},
"browser": {
"user_agent": "Mozilla/5.0 (Linux; U; Android 12.0.0; zh-cn; SONY-7XT78X Build/2DKKUF) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 Chrome/74.0.3729.157 Mobile Safari/537.36",
"color_depth": "165",
"language": "ko-KR",
"java_enabled": true,
"device_type": "PC",
"terminal_type": "WEB",
"device_os": "WINDOWS",
"timezone_offset": "-12:10",
"screen_height": "128",
"screen_width": "255",
"cookies": "isg=BA4O1YD75-wYqlLAB-T9JZjXxxxJFHEUkjdslrlhj9 TB_TENANT_TYPE=organization",
"device_finger_print_id": "info.kbxqkxkzqgjmwj.qpxzwmwzbwwijkth"
},
"goods": [
{
"id": "6916003178438",
"name": "珠宝",
"category": "珠宝",
"brand": "周六福",
"link": "https://www.zlf.cn/",
"price": 170000,
"quantity": 1,
"delivery_date": "2024-12-26T03:22:09+08:00",
"picture_url": "https://www.zlf.cn/"
}
],
"bill": {
"billing_address_collection": "REQUIRED",
"first_name": "Dalene",
"last_name": "Hyrkas",
"address_line1": "199 28th Ave, San Mateo, CA 94403, United States",
"country": "US",
"state": "CA",
"city": "San Mateo",
"email": "example@google.com",
"postal_code": "94401",
"area_code": "1",
"phone_number": "6505551234",
"descriptor": "FHFXREM"
},
"shipping": {
"first_name": "Dalene",
"last_name": "Hyrkas",
"address_line1": "199 28th Ave, San Mateo, CA 94403, United States",
"country": "US",
"state": "CA",
"city": "San Mateo",
"email": "example@google.com",
"postal_code": "94401",
"area_code": "1",
"phone_number": "6505551234"
},
"customer": {
"order_ip": "183.238.13.170",
"pay_ip": "183.238.13.170"
},
"authentication": {
"challenge_indicator": "AUTO"
}
}'ok
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"
Authorization type, default FINAL_AUTH
Value"FINAL_AUTH"
Example: "FINAL_AUTH"
Transaction amount, minimum denomination of the country's currency
Example: 1250
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 amount, minimum denomination of the country's currency
Example: 1250
Currency; Pass the ISO 3166-1 supported currency three-letter code
Enum"CNY""USD""JPY""RUB""EUR""GBP""HKD""AUD""CAD""INR"
Example: "USD"
Recurring payment agreement ID, returned for recurring payments
Example: "RA37285619238472"
Customer reference, required when store_payment_method=true or token payment
Example: "user1234567890"
Response
application/json
- Purchase Request Success
- Recurring Request Success
- Payments Authorized
- Payments Failed
{ "ret_code": "000000", "ret_msg": "Success", "data": { "merchant_id": "18356675194960", "trans_id": "174293243204402", "order_id": "GW205905xxxx960982", "status": "PROCESSING", "authorisation_type": "FINAL_AUTH", "capture_method": "AUTOMATIC", "amount": 100, "currency": "EUR", "shopper_reference": "f4911bc8b17106a08f2f7a89a9fc4d11", "expire_time": "2025-05-06T14:40:43+08:00", "payment": { "payment_method": "BANKCARD" }, "card_info": { "bin": "424242", "last4": "4242", "card_brand": "VISA", "card_type": "DEBIT", "issuer_bank": "CIAGROUP", "issuer_country": "BR", "exp_year": "2045", "exp_month": "01" }, "balances": { "authed_amount": 100, "captured_amount": 100, "able_to_capture_amount": 0, "voided_amount": 0, "able_to_void_amount": 0, "refunded_amount": 0, "able_to_refund_amount": 0 } } }