Payment Provider
Last updated
Last updated
1. Host create payment API via clientId and clientSecret
Request
Response
2. Initiate SDK and get paymentProvider.
3. Start payment process via paymentProvider after wallet connection. Use paymentId returned from response of step 1.
Webhook event occurs with POST method if you set 'lockURL' in step 1. The payment will be immediately failed and cancelled if you have not get HTTP Stats code 200 as response.
4. Await payment completed. There are two ways to confirm payment finalized. We provide both of them basically.
4-1. Await completion of SDK's startPayment promise.
4-2. Receive webhook event from server.
Webhook event will host four time interval with 1, 2, 4 and 8 seconds if HTTP Status code 200 is not received.
e. Host finalize payment API if you confirmed completion of payment. We recommend double check status of payment before hosting finalize payment API.
5. In case of payment canceled by system.
Webhook event occurs with POST method if you set 'unlockUrl' in the step 1. Webhook event will host four times interval with 1, 2, 4 and 8 seconds if HTTP Status code 200 is not received.
6. You can open payment history page via SDK. Promise will be completed if payment history page opens successfully.
1. async startPayment(paymentId: string): Promise<void>
Wallet connection and hosting create payment API call must be performed first. Pass id obtained response from API call as parameter. Promise can be finalized if the payment is successfully completed. You can host finalized payment API after promise finalized.
Error
-31001
Payment is canceled by user or timeout
-31002
Payment is failed
2. async openPaymentHistory(): Promise<void>
Open payment history page for the address with signature from user. There are two steps for this function and promise can be finalized.
Obtain signature from user
Open payment history page
Request
| Header
use clientId and clientSecret you've obtained from support team.
X-Client-Id
O
String
X-Client-Secret
O
String
| Body
buyerDappPortalAddress
O
String
Max length : 42
pgType
O
String
STRIPE
CRYPTO
currencyCode
O
String
USD
KRW
JPY
TWD
THB
KAIA
It should be equal to Item's currencyCode
price
O
String
STRIPE
100(cent) should be put if price is $1
Case1. Minumum unit equals to price unit
10,000 KRW = 10000
10,000 JPY = 10000
Case2. Minimum unit no equals to price unit
10,000 USD = 1000000 (10,000 * 100)
10,000 THB = 1000000 (10,000 * 100)
10,000 TWD = 1000000 (10,000 * 100)
CRYPTO
Put price as KAIA unit
1 $KAIA = 1.0
It should be equal to sum of each price of Items. - Decimal Policy STRIPE : no CRYPTO : Up to 4 decimal places
paymentStatusChangeCallbackUrl
O | X
String
Max length : 512 You can receive webhook whenever payment status was changed if you set paymentStatusChangerCallbackUrl.
lockUrl
X
String
Max length : 512
unlockUrl
X
String
Max length : 512
items(*)
O
String
Only the purchase of single item is supported under current version
testMode
O
Boolean
The payment methods according to testMode are as follows. - testMode : false stripe : realmode crypto : kaia - testMode : true stripe : testmode crypto : kairos
Items(*)
itemIdentifier
O
String
Max length : 256
name
O
String
Max length : 256
imageUrl
O
String
Max length : 512
price
O
String
For example, put 100(cent) if price is 1 Dollar.
currencyCode
O
String
USD
KRW
JPY
TWD
THB
KAIA
Response
payment_id
O
String
Error
400
1001
Invalid argument
401
1007
Invalid X-Client-Id or X-Client-Secret
403
4030
Access denied due to country restrictions.
500
500
Internal server error
Request
| Header
Use clientId and clientSecret you've obtained from support team.
X-Client-Id
Required when payment status is CONFIRMED or FINALIZED.
String
X-Client-Secret
Required when payment status is CONFIRM or FINALZED.
String
| QueryParam
id
O
String
Response
id
O
String
buyerDappPortalAddress
O
String
Max length : 42
pgType
O
String
STRIPE
CRYPTO
status
O
String
Payment status >
CREATED
STARTED
REGISTERED_ON_PG
CAPTURED
CONFIRMED
CONFIRM_FAILED
FINALIZED
CANCELED
currencyCode
O
String
USD
KRW
JPY
TWD
THB
KAIA
It should be equal to Item's currencyCode
price
O
String
usdExchangeRate
X
String
Fx rate at the completion of payment. It is only returned where pgType is STRIPE and status is CONFIRMED or FINALIZED.
usdExchangePrice
X
String
USD Price applied fx rate at the completion of payment. It is only returned where pgType is STRIPE and status is CONFIRMED or FINALIZED.
items(*)
O
String
Only the purchase of single item is supported under current version
testMode
O
Boolean
The payment methos according to testMode are as follows. - testMode : false stripe : realmode crypto : kaia - testMode : true stripe : testmode crypto : kairos
refund
X
object
refund.type
O (If refund object is existed)
String
CHARGEBACK
REFUND
refund.amount
O (If refund object is existed)
String
Items(*)
itemIdentifier
O
String
Max length : 256
name
O
String
Max length : 256
imageUrl
O
String
Max length : 512
price
O
String
For example, put 100(cent) if price is 1 Dollar.
currencyCode
O
String
USD
KRW
JPY
TWD
THB
KAIA
Error
Response of Refund
404
1002
Not found payment
401
1007
Invalid X-Client-Id or X-Client-Secret Header is not included when payment status is CONFIRMED or FINALIZED.
403
4030
Access denied due to country restrictions.
500
500
Internal server error
Request
| QueryParam
id
O
String
Response
status
O
String
Payment status >
CREATED
STARTED
REGISTERED_ON_PG
CAPTURED
CONFIRMED
CONFIRMED_FAILED
FINALIZED
CANCELED
Error
403
4030
Access denied due to country restrictions.
404
1002
Not found payment
500
500
Internal server error
It will be ready to be settlement after requesting finalize payment API.
You can't get settlement for STRIPE transaction if you did not request finalize payment API.
For CRYPTO, We recomment to request finalize payment API too.
Request
| Body
id
O
String
Response
Error
403
1004
Invalid payment status Current payment status cannot complete payment finalization.
403
4030
Access denied due to country restrictions.
404
1002
Not found payment
500
500
Internal server error
Each Webhook's callback URL should be set differently.
If there are any unused Webhooks, please enter null
.
If the 'lockUrl' parameter is included in the create payment request, a POST method request for the lock webhook event will be made.
When the payment is initiated using the SDK’s startPayment function, the webhook event is requested just before starting the user’s payment flow if it is determined that the payment can proceed normally.
If a request is made with the 'lockUrl' but a 200 response is not received, the payment will be immediately canceled and marked as failed automatically.
If the 'unlockUrl' parameter is included in the create payment request, a POST method request for the unlock webhook event will be made.
If the payment is automatically canceled by the system, a webhook event will be requested.
If a request is made with the 'unlockUrl' but a 200 response is not received, it will be retried up to 5 times at intervals of 1, 2, 4 and 8 seconds. If a 200 response is still not received after retries of 5 times, the payment cancellation will proceed.
When creating a payment request, a payment status change webhook event will be sent to the paymentStatusChangeCallbackUrl
you've provided.
An event occurs whenever the payment status changes, except when the status is CREATED.
If the status of the received webhook is CONFIRMED, you can call the finalize payment API.
If a request to the paymentStatusChangeCallbackUrl does not receive a 200 response, a maximum of 5 retries will be made at intervals of 1, 2, 4, and 8 seconds. Even if a 200 response is not received after 5 retries, the payment cancellation will not proceed.
CREATED
Hosted create payment API but not host startPayment of SDK
STARTED
Hosted startPayment but await payment approval from user (STRIPE/CRYPTO)
REGISTERED_ON_PG
(Only for pgType = CRYPTO) Transaction has been approved but await for enough block confirmation to prevent chain re-organization. - at least after 10 block confirmation from user's request for KAIA
CAPTURED
(Only for pgType = CRYPTO) Checking validity of the transaction after 10 blocks have confirmed from the user's transaction request
CONFIRMED
Payment approval is completed and await payment finalization from Mini Dapp
CONFIRM_FAILED
(Only for pgTye = CRYPTO) Failed to check validity of the transaction after 10 blocks have confirmed from user's transaction request
FINALIZED
Payment process is done with paymet approval and payment finialization from Mini Dapp - In case of pgType is CRYPTO, transactions will be automatically finalized after 5 minutes once it reachs the CONFIRMED status if the finalize payment API is not hosted.
CANCELED
Payment is cancelled as Policy for payment cancellation
REFUNDED
Payment has been refunded
CHARGEBACK
Users has claimed chargeback directly
Put minimum unit following
Put minimum unit following
Put minimum unit as . For example, put 100(cent) if price is 1 Dollar. It should be equal to sum of each price of Items. - Decimal Policy STRIPE : no CRYPTO : Up to 4 decimal places
Price policy follows .