LogoLogo
  • LINE's Mini Dapp & Dapp Portal
    • Join Us
    • How to build successful Mini Dapp
  • Mini Dapp
    • Overview
      • Sample Mini Dapp
    • LINE Integration
      • LINE Developers
      • LINE Front-end Framework (LIFF)
        • Essential Settings
      • Official Account
      • Invite Friends
    • Mini Dapp SDK
      • How to Get SDK Authorization
      • Wallet Provider
      • Payment Provider
        • Settlement
        • Policy
          • Payment
          • Refund
          • Cancellation
        • Flow
      • Release Note
        • v1.2.12
        • v1.2.11
        • v1.2.10
        • v1.2.9
        • v1.2.8
        • v1.2.6
        • v1.2.5
        • v1.2.4
        • v1.2.3
        • v1.2.2
        • v1.2.1
        • v1.2.0
    • Integration Guide for Game Engine
      • for Unity
      • for Cocos Creator
    • Design Guide
  • Dapp Portal
    • Mini Dapp Information
    • Collection & Drops
      • Collection Information
      • Upload NFT Information
      • Drops Information
      • Fungible Token Information
      • How to mint NFT
    • Reward
      • Reward System Flow
      • Launching Promotion
  • Extra Packages
    • Gas Fee Delegation
    • Growth Competition
      • Playbook for Teams
      • Historical Data
  • Review Guidelines
  • Update Note
  • Contact Us
Powered by GitBook
On this page
  • 00. Payment API Execution Process
  • Polling
  • Webhook
  • 01. Payment
  • 02. class PaymentProvider
  • 03. Payment API
  • 1. create payment
  • 2. get payment information
  • 3. get payment status
  • 4. finalized payment
  • 04. Payment Webhook
  • 1. lock event
  • 2. unlock event
  • 3. payment status change event
  • 05. Payment Status
  1. Mini Dapp
  2. Mini Dapp SDK

Payment Provider

PreviousWallet ProviderNextSettlement

Last updated 1 hour ago

00. Payment API Execution Process

Polling

Webhook

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}
}'

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: {paymentStatusChangeCallbackUrl}
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/payment-v1/payment/finalize' \
--header 'Content-Type: application/json' \
--data '{
    "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}
}'

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

      • 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(*)

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

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

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(*)

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
}

Response of Refund

"refund": {
        "type": "REFUND",
        "amount": "1000.0000000000000000000000000000"
    }
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 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|REFUNDED|CHARGEBACK"
}

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

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 .

here
here
here
here