Web SDK Integration

Payment Flow#

Refer following sequence diagram to get gist of payment flow via PortOne platform

Payment Flow Sequence Diagram

note

Both Sandbox and Production mode integration can be managed via same APIs and same account on PortOne platform.
Please refer following instructions to use appropriate environment flags while integration.

Embed Script#

Embed following JS snippet in your Checkout UI

New setup details#

For integration embed the following scripts in your Checkout UI code.

<script src="https://static.portone.cloud/portone.js"></script>

tip

Refer Integration Sheet to check the extensive list of available Payment Channels & Payment Methods for Integration in your country.

Parameter list for Payment Service#

Parameter	Datatype	Obligatory/Optional	Description
key	string	Obligatory	The unique PortOne key for merchant
pmt_channel	string	Obligatory	The Payment Channel Key listed in PortOne docs
pmt_method	string	Obligatory	The Payment Method Key listed in PortOne docs
environment	string	Obligatory	The environment of the transaction is either live OR sandbox
description	string	Obligatory	The description of the transaction
merchant_order_id	string	Obligatory	The unique merchant order reference generated by the merchant
amount	double	Obligatory	The amount of transaction, can be a floating-point number
currency	string	Obligatory	The currency of transaction
billing_details	object	Optional	The JSON object for billing details
shipping_details	object	Optional	The JSON object for shipping details
order_details	array of objects	Optional	Order Details like quantity, id, name, price are Obligatory, while image is Optional
success_url	string	Obligatory	The url of success page hosted by merchant.
failure_url	string	Obligatory	The url of failure page hosted by merchant.
pending_url	string	Obligatory	The url of pending page hosted by merchant.
signature_hash	string	Obligatory	Signature calculated using this link

Parameter list for Checkout Service#

Parameter	Datatype	Obligatory/Optional	Description
environment	string	Obligatory	The environment of the transaction is either live OR sandbox
description	string	Obligatory	The description of the transaction
merchant_order_id	string	Obligatory	The unique merchant order reference generated by the merchant
amount	double	Obligatory	The amount of transaction, can be a floating-point number
currency	string	Obligatory	The currency of transaction
billing_details	object	Optional	The JSON object for billing details
shipping_details	object	Optional	The JSON object for shipping details
merchant_details	object	Obligatory	The JSON object for merchant details
order_details	array of objects	Optional	TOrder Details like quantity, id, name, price are Obligatory, while image is Optional
success_url	string	Obligatory	The url of success page hosted by merchant.
failure_url	string	Obligatory	The url of failure page hosted by merchant.
signature_hash	string	Obligatory	Signature calculated using this link

Environment Flag#

Pass the environment flag in above payload. Environment is the mandatory field, by default the value of environment is sandbox while initiating payment.

Production

    "environment": "live"

Sandbox

    "environment": "sandbox"

Payment Service#

Use following JS code snippet to initiate the payment using the respective supported payment channels (e.g. MOMO, ZaloPay, Mastercard, etc).

To generate the signature hash, refer Generate Signature Hash link.

<script>
const portone = new window.PortOne({
    // Your PortOne Key
    portOneKey: 'pptafmcddmszvgXl'
})
portone.paymentService.payment({
    // new uniform payment request format example for Momopay
    "key": "pptafmcddmszvgXl",
    "pmt_channel": "STRIPE",
    "pmt_method": "STRIPE_CARD",
    "merchant_order_id":"MERCHANT1617366877238",
    "signature_hash": "10b664f803035a2146b26949041c2ce8c8693512e4b85159d3c43b001a714af0",
    "amount": 4000,
    "currency": "VND",
    "environment": "live",
    "description": "Product description",
    "response_type": "redirect_url_only",
    "success_url": "http://www.coolmate.me/result/success",
    "failure_url": "http://www.coolmate.me/result/failure",
    "pending_url": "http://www.coolmate.me/result/pending"
})
</script>

Detailed script for payment service (including optional fields.)

<script>
const portone = new window.PortOne({
    // Your PortOne Key
    portOneKey: 'pptafmcddmszvgXl'
})
portone.paymentService.payment({
    // new uniform payment request format example for Momopay
    "key": "pptafmcddmszvgXl",
    "pmt_channel": "STRIPE",
    "pmt_method": "STRIPE_CARD",
    "merchant_order_id":"MERCHANT1617366877238",
    "signature_hash": "10b664f803035a2146b26949041c2ce8c8693512e4b85159d3c43b001a714af0",
    "amount": 4000,
    "currency": "VND",
    "environment": "live",
    "description": "Product description",
    "billing_details": {
        "billing_name": "Mark Weins",
        "billing_email": "markweins@gmail.com",
        "billing_phone": "1234567890",
        "billing_address": {
            "city": "Ho Chi Minh City",
            "country_code": "VN",
            "locale": "en",
            "line_1": "address_1",
            "line_2": "address_2",
            "postal_code": "400202",
            "state": "Mah"
        }
    },
    "shipping_details": {
        "shipping_name": "Mark Weins",
        "shipping_email": "markweins@gmail.com",
        "shipping_phone": "1234567890",
        "shipping_address": {
            "city": "Ho Chi Minh City",
            "country_code": "VN",
            "locale": "en",
            "line_1": "address_1",
            "line_2": "address_2",
            "postal_code": "400202",
            "state": "Mah"
        }
    },
    "order_details": [
        {
          "id": "1",
          "price": 2000,
          "name": "Stubborn Attachments",
          "quantity": 1,
          "image":"https://cdn.portone.cloud/item1.png"
        },
        {
          "id": "2",
          "price": 2000,
          "name": "Stubborn Attachments",
          "quantity": 1,
          "image":"https://cdn.portone.cloud/item2.png"
        }
    ],
    "response_type": "redirect_url_only",
    "success_url": "http://www.coolmate.me/result/success",
    "failure_url": "http://www.coolmate.me/result/failure",
    "pending_url": "http://www.coolmate.me/result/pending"
})
</script>

Checkout Service#

Use following JS code snippet to initiate the payment in checkout service using the respective supported payment channels (e.g. MomoPay, ZaloPay, Mastercard, etc).

To generate the signature hash, refer Generate Signature Hash link.

To generate the jwt token, refer Generate JWT Token link.

<script>
const portone = new window.PortOne({
    // Your PortOne Key
    portOneKey: 'pptafmcddmszvgXl',
    jwtToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJOUFNrWlpZZWZHeUt2QnhpIiwiaXNzIjoiQ0hBSVBBWSIsImlhdCI6MTYzMzMzOTAzMiwiZXhwIjoxNjczMzM5MDMy',
})
portone.checkoutService.checkout({
    "merchant_details": {
        "name": "Downy",
        "logo": "images/v184_135.png",
        "back_url": "https://demo.portone.cloud/checkout",
        "promo_code": "Downy350",
        "promo_discount": 0.0,
        "shipping_charges": 0.0
    },
    "merchant_order_id":"MERCHANT1617366877238",
    "signature_hash": "10b664f803035a2146b26949041c2ce8c8693512e4b85159d3c43b001a714af0",
    "amount": 4000,
    "currency": "VND",
    "environment": "live",
    "description": "Product description",
    "country_code": "VN",
    "expiry_hours":24,
    "is_checkout_embed": true,
    "show_back_button": false,
    "show_shipping_details": false,
    "default_guest_checkout": true,
    "show_items": false,
    "success_url": "http://www.coolmate.me/result/success",
    "failure_url": "http://www.coolmate.me/result/failure"
})
</script>

Detailed script for checkout service (including optional fields).

<script>
const portone = new window.PortOne({
    // Your PortOne Key
    portOneKey: 'pptafmcddmszvgXl',
    jwtToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJOUFNrWlpZZWZHeUt2QnhpIiwiaXNzIjoiQ0hBSVBBWSIsImlhdCI6MTYzMzMzOTAzMiwiZXhwIjoxNjczMzM5MDMy',
})
portone.checkoutService.checkout({
    "merchant_details": {
        "name": "Downy",
        "logo": "images/v184_135.png",
        "back_url": "https://demo.portone.cloud/checkout",
        "promo_code": "Downy350",
        "promo_discount": 0.0,
        "shipping_charges": 0.0
    },
    "merchant_order_id":"MERCHANT1617366877238",
    "signature_hash": "10b664f803035a2146b26949041c2ce8c8693512e4b85159d3c43b001a714af0",
    "amount": 4000,
    "currency": "VND",
    "environment": "live",
    "description": "Product description",
    "order_details": [{
        "id":"1",
        "price": 2000,
        "name": "Stubborn Attachments",
        "quantity": 1
        },
        {
            "id":"2",
            "price": 2000,
            "name": "Stubborn Attachments",
            "quantity": 1,
            "image":"https://cdn.portone.cloud/item2.png"
        }
    ],
    "billing_details": {
        "billing_name": "Test mark",
        "billing_email": "markweins@gmail.com",
        "billing_phone": "9998878788",
        "billing_address": {
          "city": "VND",
          "country_code": "VN",
          "locale": "en",
          "line_1": "address",
          "line_2": "address_2",
          "postal_code": "400202",
          "state": "Mah"
        }
    },
    "shipping_details": {
        "shipping_name": "xyz",
        "shipping_email": "xyz@gmail.com",
        "shipping_phone": "1234567890",
        "shipping_address": {
          "city": "abc",
          "country_code": "VN",
          "locale": "en",
          "line_1": "address_1",
          "line_2": "address_2",
          "postal_code": "400202",
          "state": "Mah"
      }
    },
    "country_code": "VN",
    "expiry_hours":24,
    "is_checkout_embed": true,
    "show_back_button": false,
    "show_shipping_details": false,
    "default_guest_checkout": true,
    "show_items": false,
    "success_url": "http://www.coolmate.me/result/success",
    "failure_url": "http://www.coolmate.me/result/failure"
})
</script>