Skip to main content

React Native SDK(v2) - Merchant's checkout

Please follow steps below to setup React Native SDK and start accepting payment via PortOne.

For initial SDK installation set up refer here


  1. After inital setup, Install the package

    npm install @iamport-intl/portone-sdk@latest
  2. Add peer dependencies

    npm install @react-native-async-storage/async-storage
    npm install react-native-localization
    npm install react-native-webview
    npm install react-native-linear-gradient

Access saved cards via React Native SDK#

  1. Import the chaiport-sdk library

    import { Checkout, helpers,} from '@iamport-intl/portone-sdk';
  2. Initialize the checkout instance as below

    <Checkout
    callbackFunction={this.afterCheckout}
    redirectUrl={"chaiport://"}
    env={"dev"} //Optional
    environment={'sandbox'} //Optional
    />
    // callback function will handle all the information of the transactions
  3. Capture the mobile number and OTP to fetch the saved cards for a particular user. To generate the OTP, call the method as below:

    let response = await helpers.getOTP(this.state.formattedText);

    Response: contains data, status

    Status code :

    200 - Success

    400 - Failed due to incorrect OTP or wrong params provideed

  4. After successfully entered the OTP, the captured mobile number and OTP should provide to the fetchSavedCards as below to fetch the saved cards for the particular number.

    let response = await helpers.fetchSavedCards(
    formattedText,
    OTP
    );

    formattedText: Contains mobile number with Country code. (eg: ⁨‭+16625655248 , +918341234123)

    OTP: OTP that received to the particular number given.

    response:

    Success case

    {
    "data": [
    {
    "token": "5ff6644dec554fdc8f6d2e161a0c662d",
    "partial_card_number": "450875******1019",
    "expiry_month": "05",
    "expiry_year": "2021",
    "type": "visa"
    },
    {
    "token": "5ff6644dec554fdc8f6d2e161a0c662d",
    "partial_card_number": "450875******1019",
    "expiry_month": "05",
    "expiry_year": "2021",
    "type": "visa"
    }
    ],
    "status": 200,
    }

    Failure case:

    {
    "message": "OTP is a required Query Param!",
    "status": 400,
    }

Payload parameter list#

ParameterDatatypeObligatory/OptionalDescription
portOneKeyTextObligatoryPortOne Key provided to merchants
paymentChannelTextObligatoryName of the payment channel
paymentMethodTextObligatoryPayment Method to be used
environmentTextObligatoryEnvironment of the payment
descriptionTextOptionalOrder description set in PSP order creation
merchantOrderIdTextObligatoryOrder reference given by merchant ID
amountNumeric[1,12]ObligatoryAmount for transaction
currencyTextObligatoryCurrency for transaction
billingDetailsOptionalDetails of billing
shippingDetailsOptionalDetails of shipping
merchantDetailsOptionalMerchant details
orderDetailsObligatoryOrder Details like quantity, id, name, price are Obligatory, while image is Optional
successUrlObligatoryRedirection url for success
failureUrlObligatoryRedirection url for failure
token_paramsObligatoryif saved cards or new cards flow, its Obligatory, token params like card_number, card_holder_name, cvv, expiry_month, expiry_year
signatureHashObligatorySignature calculated using this link

Environment Flag#

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

Initiate payment with a new credit card for a particular number#

  1. Collect the card details and provide them to startPaymentWithNewCard method as below:

    // @param {object} cardDetails
    // @param {object} payload
    // @param {string} JWTToken
    // @param {string} clientKey
    // @param {string} customerUUID - provide it when merchant card vault enabled
    // @param {string} subMerchantKey - provide it when subMerchant flow enabled
    let response = await Checkout.startPaymentWithNewCard(
    cardDetails,
    payload,
    JWTToken,
    clientKey,
    customerUUID,
    subMerchantKey
    );
    • Params:

      • cardDetails: Contains card name, card number, expiry month, expiry year and CVV

      • Payload : provide the transaction payload

      • JWTToken: provide the JWT token

      • client key: provide the provided Client key

      • customerUUID: provide the customer UUId if merchant card vault is enabled

      • subMerchantKey: provide the sub merchant key for sub merchant flow

        //Card details
        {
        card_number: data.cardNumber,
        card_holder_name: data.name || 'NGUYEN VAN A',
        cvv: data.cvv,
        expiry_month: data.expirationMonth,
        expiry_year: data.expirationYear,
        saved_card: data?.saveForLater,
        }
      • data

        let orderDetails = [
        {
        id: `${item.key}`,
        price: item.price,
        name: item.name,
        quantity: item.quantity,
        image: item.img,
        }
        ]
        let totalAmount = sum of orderDetails + shipping - promoDiscount
        let payload = {
        portOneKey: PORTONEKEY,
        amount: totalAmount,
        merchantOrderId: merchantOrderId,
        paymentChannel: "MASTERCARD",
        paymentMethod: `MASTERCARD_CARD`,
        currency: CURRENCY,
        environment: ENVIRONMENT,
        merchantDetails: {
        name: 'Chaipay Cart',
        logo: 'https://demo.portone.cloud/images/chikku-loafers.jpg',
        back_url: 'https://demo.chaipay.io/checkout.html',
        promo_code: 'Downy350',
        promo_discount: promoDiscount,
        shipping_charges: shipping,
        },
        signatureHash: "123"
        billingDetails: {
        billing_name: 'Test React native',
        billing_email: 'markweins@gmail.com',
        billing_phone: '+660956425564',
        billing_address: {
        city: 'VND',
        country_code: 'VN',
        locale: 'en',
        line_1: 'address',
        line_2: 'address_2',
        postal_code: '400202',
        state: 'Mah',
        },
        },
        shippingDetails: {
        shipping_name: 'xyz-Testing',
        shipping_email: 'xyz@gmail.com',
        shipping_phone: '+910830443596',
        shipping_address: {
        city: 'testing city',
        country_code: 'VN',
        locale: 'en',
        line_1: 'Testing line 1',
        line_2: 'Testing line 2',
        postal_code: '400202',
        state: 'Mah',
        },
        },
        orderDetails: orderDetails,
        successUrl: successURL,
        failureUrl: failureURL,
        redirectUrl: 'demo://checkout1',
        source: 'mobile',
        token_params: {
        card_number: "data.cardNumber",
        card_holder_name: 'NGUYEN VAN A',
        cvv: "data.cvv",
        expiry_month: "data.expirationMonth", // "dd"
        expiry_year: "data.expirationYear", // "yy"
        saved_card: true,
        }
        }
    • Response

      • Success case

        {
        "data": {
        "is_success": "true",
        "redirect_url": "",
        "channel_order_ref": "1xAEm5eZ4sbhzqaPEIV4tVoAXMm",
        "merchant_order_ref": "MERCHANT1629789647638",
        "order_ref": "1xAEm5eZ4sbhzqaPEIV4tVoAXMm",
        "message": "",
        "deep_link": "",
        "additional_data": null
        },
        "status": 200,
        }
      • Failure case:

        {
        "data": {
        "is_success": "false",
        "redirect_url": "",
        "channel_order_ref": "1xAFIwrpWxarXuHGu3PMe0syPg0",
        "merchant_order_ref": "MERCHANT1629789909578",
        "order_ref": "1xAFIwrpWxarXuHGu3PMe0syPg0",
        "message": "",
        "deep_link": "",
        "additional_data": null
        },
        "status": 400,
        }

Initiate payment with a saved credit card for a particular number#

  1. Collect the card details and provide them to the startPaymentWithSavedCard method as below:

    // @param {String} cardDetails
    // @param {object} payload
    // @param {string} JWTToken
    // @param {string} clientKey
    let response = await Checkout.startPaymentWithSavedCard(
    cardDetails,
    payload,
    JWTToken,
    clientKey
    );
    • Params:

      • cardDetails: Contains card name, card number, expiry month, expiry year and CVV

      • Payload : provide the transaction payload

      • JWTToken: provide the JWT token

      • client key: provide the provided Client key

        {
        partial_card_number: "";
        expiry_year: "";
        expiry_month: "";
        cardType: "";
        token: ""
        }
      • data

        let orderDetails = [
        {
        id: `${item.key}`,
        price: item.price,
        name: item.name,
        quantity: item.quantity,
        image: item.img,
        }
        ]
        let totalAmount = sum of orderDetails + shipping - promoDiscount
        let payload = {
        portOneKey: PORTONEKEY,
        amount: totalAmount,
        merchantOrderId: merchantOrderId,
        paymentChannel: "MASTERCARD",
        paymentMethod: `MASTERCARD_CARD`,
        currency: CURRENCY,
        environment: ENVIRONMENT,
        countryCode: 'VN',
        merchantDetails: {
        name: 'Chaipay Cart',
        logo: 'https://demo.portone.cloud/images/chikku-loafers.jpg',
        back_url: 'https://demo.chaipay.io/checkout.html',
        promo_code: 'Downy350',
        promo_discount: promoDiscount,
        shipping_charges: shipping,
        },
        signatureHash: "123"
        billingDetails: {
        billing_name: 'Test React native',
        billing_email: 'markweins@gmail.com',
        billing_phone: '+660956425564',
        billing_address: {
        city: 'VND',
        country_code: 'VN',
        locale: 'en',
        line_1: 'address',
        line_2: 'address_2',
        postal_code: '400202',
        state: 'Mah',
        },
        },
        shippingDetails: {
        shipping_name: 'xyz-Testing',
        shipping_email: 'xyz@gmail.com',
        shipping_phone: '+910830443596',
        shipping_address: {
        city: 'testing city',
        country_code: 'VN',
        locale: 'en',
        line_1: 'Testing line 1',
        line_2: 'Testing line 2',
        postal_code: '400202',
        state: 'Mah',
        },
        },
        orderDetails: orderDetails,
        successUrl: successURL,
        failureUrl: failureURL,
        redirectUrl: 'demo://checkout1',
        source: 'mobile',
        token_params: {
        partial_card_number: "";
        expiry_year: ""; // "yyyy"
        expiry_month: ""; // "dd"
        cardType: "";
        token: ""
        }
        }
    • Response

      • Success case

        {
        "data": {
        "is_success": "true",
        "redirect_url": "",
        "channel_order_ref": "1xAEm5eZ4sbhzqaPEIV4tVoAXMm",
        "merchant_order_ref": "MERCHANT1629789647638",
        "order_ref": "1xAEm5eZ4sbhzqaPEIV4tVoAXMm",
        "message": "",
        "deep_link": "",
        "additional_data": null
        },
        "status": 200,
        }
      • Failure case:

        {
        "data": {
        "is_success": "false",
        "redirect_url": "",
        "channel_order_ref": "1xAFIwrpWxarXuHGu3PMe0syPg0",
        "merchant_order_ref": "MERCHANT1629789909578",
        "order_ref": "1xAFIwrpWxarXuHGu3PMe0syPg0",
        "message": "",
        "deep_link": "",
        "additional_data": null
        },
        "status": 400,
        }

Initiate payment with a wallet#

  1. Collect the payload and provide them to the startPaymentWithWallets method as below:

    // @param {object} payload
    // @param {string} subMerchantKey - provide it when sub merchant flow is enabled
    let data = await Checkout.startPaymentWithWallets(payload, subMerchantKey);
    • payload
    let orderDetails = [
    {
    id: `${item.key}`,
    price: item.price,
    name: item.name,
    quantity: item.quantity,
    image: item.img,
    }
    ]
    let totalAmount = sum of orderDetails + shipping - promoDiscount
    let payload = {
    portOneKey: PORTONEKEY,
    amount: totalAmount,
    merchantOrderId: merchantOrderId,
    paymentChannel: "ZALOPAY",
    paymentMethod: `ZALOPAY_WALLET`,
    currency: CURRENCY,
    environment: ENVIRONMENT,
    countryCode: 'VN',
    merchantDetails: {
    name: 'Chaipay Cart',
    logo: 'https://demo.portone.cloud/images/chikku-loafers.jpg',
    back_url: 'https://demo.chaipay.io/checkout.html',
    promo_code: 'Downy350',
    promo_discount: promoDiscount,
    shipping_charges: shipping,
    },
    signatureHash: "123"
    billingDetails: {
    billing_name: 'Test React native',
    billing_email: 'markweins@gmail.com',
    billing_phone: '+660956425564',
    billing_address: {
    city: 'VND',
    country_code: 'VN',
    locale: 'en',
    line_1: 'address',
    line_2: 'address_2',
    postal_code: '400202',
    state: 'Mah',
    },
    },
    shippingDetails: {
    shipping_name: 'xyz-Testing',
    shipping_email: 'xyz@gmail.com',
    shipping_phone: '+910830443596',
    shipping_address: {
    city: 'testing city',
    country_code: 'VN',
    locale: 'en',
    line_1: 'Testing line 1',
    line_2: 'Testing line 2',
    postal_code: '400202',
    state: 'Mah',
    },
    },
    orderDetails: orderDetails,
    successUrl: successURL,
    failureUrl: failureURL,
    redirectUrl: 'demo://checkout1',
    source: 'mobile',
    token_params: {
    partial_card_number: "";
    expiry_year: ""; // "yy"
    expiry_month: ""; // "dd"
    cardType: "";
    token: ""
    }
    }
    ```

Initiate payment with a non tokenization flow#

Collect the payload and provide them to the startPaymentWithoutTokenization method as below:

// @param {object} newPayload
// @param {string} subMerchantKey - provide it when sub merchant flow is enabled
let data = await Checkout.startPaymentWithoutTokenization(newPayload, subMerchantKey);

Fetch available payment methods for a merchant#

Collect the portOneKey, currency and provide them to the getAvailablePaymentMethods method as below:

// @param {String} portOneKey
// @param {string} currency
// @param {string} subMerchantKey - provide it when sub merchant flow is enabled
let data = await Checkout.getAvailablePaymentMethods(portOneKey, currency, subMerchantKey);

Merchant centric card vault#

  1. Collect the customerId, clientKey, JWTToken and cardData and provide them to the addCardForCustomerId method as below:

    import {helpers} from '@iamport-intl/portone-sdk';
    // @param {String} customerId
    // @param {string} clientKey
    // @param {string} JWTToken
    // @param {object} cardData
    // @param {string} subMerchantKey - provide it when sub merchant flow is enabled
    let data = await helpers.addCardForCustomerId(customerId, clientKey, JWTToken, cardData, subMerchantKey);
    • cardData
    {
    "card_number": "42424242424244242",
    "expiry_month": "07",
    "expiry_year": "31",
    "type": "visa"
    }
  2. Collect the customerId, clientKey, JWTToken and cardData and provide them to the deleteCardForCustomerId method as below:

    // @param {String} customerId
    // @param {string} clientKey
    // @param {string} JWTToken
    // @param {object} cardData
    // @param {string} subMerchantKey - provide it when sub merchant flow is enabled
    let data = await helpers.deleteCardForCustomerId(customerId, clientKey, JWTToken, cardData, subMerchantKey);
    • cardData
    {
    "token": "cdec91449d3a4b4bae9144d586a2b972",
    }
  3. Collect the customerId, clientKey, JWTToken and provide them to the fetchCustomerCards method as below:

    // @param {String} customerId
    // @param {string} clientKey
    // @param {string} JWTToken
    // @param {object} cardData
    // @param {string} subMerchantKey - provide it when sub merchant flow is enabled
    let data = await helpers.fetchCustomerCards(customerId, clientKey, JWTToken, subMerchantKey);
  4. Collect the customerData, clientKey, JWTToken and provide them to the addCustomer method as below:

    // @param {object} customerData
    // @param {string} clientKey
    // @param {string} JWTToken
    // @param {string} subMerchantKey - provide it when sub merchant flow is enabled
    let data = await helpers.addCustomer(customerData, clientKey, JWTToken, subMerchantKey);
    • customerData

      {
      "name": " User",
      "phone_number": "+9183414691",
      "email_address": "user@email.io",
      "customer_ref": "867348767863w5877"
      }
  5. Collect the customerID, customerData, clientKey, JWTToken and provide them to the getCustomerData method as below:

    let data = await helpers.getCustomerData(customerID, clientKey, JWTToken);

Failover Routing#

To support failover routing add the following two parameters to payload:

  • isRoutingEnabled= true

  • Routing Param type should be failover.

  • provide the Routing Ref which is set in the merchant portal.

let payload = getDefaultPayload()
payload.isRoutingEnabled = true
payload.routingParams={
type: "failover",
routeRef: "1233"
}
  1. To Fetch the List of Routes which are created from merchant portal

    • Collect the clientKey, JWTToken and provide them to the fetchRoutes method as below:
    let data = await helpers.fetchRoutes(clientKey, JWTToken);

PreAuth and Capture Payment#

  1. To implement PreAuth one parameter has to be set: transactionType= PREAUTH || PURCHASE

    let payload = getDefaultPayload()
    payload.transactionType = "PREAUTH"
  2. To Capture the Payment

    • Collect the transactionOrderRef, clientKey, JWTToken and provide them to the captureTransactionAPI method as below:
    let data = await helpers.captureTransactionAPI(transactionOrderRef, clientKey, JWTToken);
  • Steps for Signature Hash Generation

    createHash: (
    key,
    amount,
    currency,
    failureUrl,
    merchantOrderId,
    successUrl,
    secretKey,
    ) => {
    let mainParams =
    'amount=' +
    encodeURIComponent(amount) +
    '&client_key=' +
    encodeURIComponent(key) +
    '&currency=' +
    encodeURIComponent(currency) +
    '&failure_url=' +
    encodeURIComponent(failureUrl) +
    '&merchant_order_id=' +
    encodeURIComponent(merchantOrderId) +
    '&success_url=' +
    encodeURIComponent(successUrl);
    let hash = HmacSHA256(mainParams, secretKey);
    let signatureHash = Base64.stringify(hash);
    return signatureHash;
    }