Payment Provider

00. Payment API Execution Process

1. Define itemIdentifier in a mini DApp.

2. When the user clicks the purchase button on the FE, the item information is transmitted to the BE.

3. Request create payment API from BE to payment server with clientSecret.

4. Transmit payment_id received from payment server to FE

5. Start payment process with payment_id from FE

6. If user has succeed in payment, BE receives webhook. If this response with normal, call finalize API to payment server and assign item to user

01. Payment

1. Host create payment API via clientId and clientSecret

Request

curl --location 'https://payment.dappportal.io/api/payment-v1/payment/create' \
--header 'X-Client-Id: {your_client_id}' \
--header 'X-Client-Secret: {your_client_secret}' \
--header 'Content-Type: application/json' \
--data '{
    "buyerDappPortalAddress": "{user_wallet_address}",
    "pgType": "{pg_type}",
    "currencyCode": "{currency_code}",
    "price": "{price}",
    "paymentStatusChangeCallbackUrl": "{url_to_get_confirm_callback}",
    "lockUrl": "{url_to_get_item_lock_callback}",
    "unlockUrl": "{url_to_get_item_unlock_callback}",
    "items": [
        {
            "itemIdentifier": "{your_item_identifier}",
            "name": "{your_item_name}",
            "imageUrl": "{your_item_image_url}",
            "price": "{price}",
            "currencyCode": "{currencyCode}"
        }
    ],
    "testMode": {true | false}
}'

You can confirmCallbackUrl instead of paymentStatusChangeCallbackUrl until separate guidance is provided.

Response

{
    "id": {payment_id}
}

2. Initiate SDK and get paymentProvider.

import DappPortalSDK from '@linenext/dapp-portal-sdk'
 
const sdk = await DappPortalSDK.init({ clientId: '<CLIENT_ID>' });
const paymentProvider = sdk.getPaymentProvider()

3. Start payment process via paymentProvider after wallet connection. Use paymentId returned from response of step 1.

await this.walletProvider.request({method: 'kaia_requestAccounts'});
await paymentProvider.startPayment(paymentId)

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.

method: POST
url: {lockUrl}
body : {
    "paymentId": "{payment_id}",
    "itemIdentifiers": ["{your_item_identifier}"]
}

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.

await provider.startPayment(paymentId);

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.

method : POST
url: {confirmCallbackUrl}
body : {
    "paymentId": "{payment_id}",
    "status": "CONFIRMED"
}

e. Host finalize payment API if you confirmed completion of payment. We recommend double check status of payment before hosting finalize payment API.

curl --location --request 
POST 'https://payment.dappportal.io/api/v1/payment/finalize?id={payment_id}'

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.

method: POST
url: {unlockUrl}
body : {
    "paymentId": "{payment_id}",
    "itemIdentifiers": ["{your_item_identifier}"]
}

6. You can open payment history page via SDK. Promise will be completed if payment history page opens successfully.

await paymentProvider.openPaymentHistory()

02. class PaymentProvider

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

{code: -31001, message: 'Payment is canceled'}

Code	Description
-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

03. Payment API

1. create payment

curl --location 'https://payment.dappportal.io/api/payment-v1/payment/create' \
--header 'X-Client-Id: {your_client_id}' \
--header 'X-Client-Secret: {your_client_secret}' \
--header 'Content-Type: application/json' \
--data '{
    "buyerDappPortalAddress": "{user_wallet_address}",
    "pgType": "{pg_type}",
    "currencyCode": "{currency_code}",
    "price": "{price}",
    "paymentStatusChangeCallbackUrl": "{url_to_get_confirm_callback}",
    "lockUrl": "{url_to_get_item_lock_callback}",
    "unlockUrl": "{url_to_get_item_unlock_callback}",
    "items": [
        {
            "itemIdentifier": "{your_item_identifier}",
            "name": "{your_item_name}",
            "imageUrl": "{your_item_image_url}",
            "price": "{price}",
            "currencyCode": "{currencyCode}"
        }
    ],
    "testMode": {true | false}
}'

You can confirmCallbackUrl instead of paymentStatusChangeCallbackUrl until separate guidance is provided.

Request

| Header

use clientId and clientSecret you've obtained from support team.

field	mandatory	type
X-Client-Id	O	String
X-Client-Secret	O	String

| Body

field	madatory	type	limitation
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 Put minimum unit following here 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
confirmCallbackUrl	O | X	String	If paymentStatusChangeCallbackUrl is not set, it is a mandatory Max length : 512 You can receive webhook when payment status was changed to 'CONFIRMED' if you set confirmCallbackUrl. You can't put it with paymentStatusChangeCallbackUrl. It will be deprecated from SDK v1.2.0
paymentStatusChangeCallbackUrl	O | X	String	If confirmCallbackUrl is not set, it is a mandatory Max length : 512 You can receive webhook whenever payment status was changed if you set paymentStatusChangerCallbackUrl. You can't put it with confirmCallbackUrl.
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(*)

field	mandatory	type	limitation
itemIdentifier	O	String	Max length : 256
name	O	String	Max length : 256
imageUrl	O	String	Max length : 512
price	O	String	Put minimum unit following here For example, put 100(cent) if price is 1 Dollar.
currencyCode	O	String	USD KRW JPY TWD THB KAIA

Response

{
    "id": {payment_id}
}

field	mandatory	type
payment_id	O	String

Error

{
    "code": 500,
    "detail": "Internal server error",
    "cause": null
}

HTTP Status code	code	Description
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

2. get payment information

curl --location 'https://payment.dappportal.io/api/payment-v1/payment/info?id={payment_id}' \
--header 'X-Client-Id: {your_client_id}' \
--header 'X-Client-Secret: {your_client_secret}'

Request

| Header

Use clientId and clientSecret you've obtained from support team.

field	mandatory	type
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

field	mandatory	type
id	O	String

Response

field	madatory	type	limitation
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	Put minimum unit as here. 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
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

Items(*)

field	mandatory	type	limitation
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

{
    "code": 500,
    "detail": "Internal server error",
    "cause": null
}

HTTP Status code	code	description
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

3. get payment status

curl --location 'https://payment.dappportal.io/api/payment-v1/payment/status?id={payment_id}'

Request

| QueryParam

field	mandatory	type
id	O	String

Response

{
    "status": {status}
}

field	mandatory	type	limitation
status	O	String	Payment status > CREATED STARTED REGISTERED_ON_PG CAPTURED CONFIRMED CONFIRMED_FAILED FINALIZED CANCELED

Error

{
    "code": 500,
    "detail": "Internal server error",
    "cause": null
}

HTTP Status code	code	description
403	4030	Access denied due to country restrictions.
404	1002	Not found payment
500	500	Internal server error

4. finalized payment

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.

curl --location 'https://payment.dappportal.io/api/payment-v1/payment/finalize'

Request

| Body

field	madatory	type
id	O	String

Response

Error

{
    "code": 500,
    "detail": "Internal server error",
    "cause": null
}

HTTP Status code	code	description
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

04. Payment Webhook

Each Webhook's callback URL should be set differently.

If there are any unused Webhooks, please enter null.

1. lock event

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.

{
    "paymentId": "{payment_id}",
    "itemIdentifiers": [
        {
            "{your_item_identifier}"
        }
    ]
}

2. unlock event

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.

{
    "paymentId": "{payment_id}",
    "itemIdentifiers": [
        {
            "{your_item_identifier}"
        }
    ]
}

3. payment confirmed event

You can confirmCallbackUrl until separate guidance is provided. It will be deprecated.

A Payment confirmed webhook event will be requested at the confirmCallbackUrl provided in the create payment request.

The webhook event will be requested when the payment is completed in Stripe or when the crypto transaction request is securely completed.

Once the webhook is received, you can call the finalize payment API.

If a request is made with the confirmCallbackUrl 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 not proceed.

{
    "paymentId": "{payment_id}",
    "status": "CONFIRMED"
}

4. payment status change event

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.

{
    "paymentId": "{payment_id}"
    "status": "STARTED|REGISTERED_ON_PG|CAPTURED_CONFIRMED_CONFIRM_FAILED|FINALIZED|CANCELED"
}

05. Payment Status

Status	Description
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