Appearance

결제하기 ​

지원환경: React NativeWebView
실행환경: Toss App

createOneTimePurchaseOrder ​

createOneTimePurchaseOrder 함수는 인앱 결제 결제창을 띄우고, 사용자가 결제를 진행해요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.

시그니처 ​

typescript
function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;

파라미터 ​

typescript

interface IapCreateOneTimePurchaseOrderOptions {
  options: {sku: string; processProductGrant: (params: { orderId: string }) => boolean | Promise<boolean> };
  onEvent: (event: SuccessEvent) => void | Promise<void>;
  onError: (error: unknown) => void | Promise<void>;
}

interface IapCreateOneTimePurchaseOrderResult {
  orderId: string;
  displayName: string;
  displayAmount: string;
  amount: number;
  currency: string;
  fraction: number;
  miniAppIconUrl: string | null;
}

interface SuccessEvent {
  type: 'success';
  data: IapCreateOneTimePurchaseOrderResult;
}
  • options필수

    인앱 결제를 필요한 옵션이에요.

    • params.sku필수 · string

      주문할 상품의 ID예요.

    • params.processProductGrant필수 · (params: { orderId: string }) => boolean | Promise<boolean>

      주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요. `orderId`를 받아서 지급 성공 여부를 true 또는 Promise<true>로 반환해요. 지급에 실패하면 false를 반환해요.

  • onEvent필수 · (event: SuccessEvent) => void | Promise<void>

    결제가 성공했을 때 호출해요.

    • event.type필수 · "success"

      이벤트의 타입이에요. "success"를 반환해요.

    • event.data필수 · IapCreateOneTimePurchaseOrderResult

      인앱 결제가 완료되면 결제 세부 정보와 상품 정보를 담아 반환해요. 반환된 정보로 결제한 상품의 정보를 화면에 표시할 때 사용할 수 있어요.

      • event.data.orderId필수 · string

        결제 주문 ID이에요. 결제 완료 후 결제 상태를 조회할 때 사용해요.

      • event.data.displayName필수 · string

        화면에 표시할 상품 이름이에요.

      • event.data.displayAmount필수 · string

        통화 단위가 포함된 가격 정보예요.

      • event.data.amount필수 · number

        상품 가격 숫자 값이에요.

      • event.data.currency필수 · string

        상품 가격 통화 단위예요.

      • event.data.fraction필수 · number

        가격을 표시할 때 소수점 아래 몇 자리까지 보여줄지 정하는 값이에요.

      • event.data.miniAppIconUrlstring | null

        미니앱 아이콘 이미지의 URL이에요.

  • onError필수 · (error: unknown) => void | Promise<void>

    결제 과정에서 에러가 발생했을 때 호출해요. 에러 객체를 받아서 로깅하거나 복구 절차를 실행할 수 있어요.

에러코드 ​

  • INVALID_PRODUCT_ID : 유효하지 않은 상품 ID이거나, 해당 상품이 존재하지 않습니다. 상품 ID를 확인해주세요.

    유효하지 않은 상품 ID이거나, 해당 상품이 존재하지 않을 때 발생해요.


    PAYMENT_PENDING : 결제 승인이 대기 중입니다. 결제 승인을 기다려주세요.

    사용자가 요청한 결제가 아직 승인을 기다리고 있을 때 발생해요.


    NETWORK_ERROR : 네트워크 오류가 발생했습니다. 잠시 후 다시 시도해주세요.

    서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.


    INVALID_USER_ENVIRONMENT : 이 상품은 현재 기기, 계정 또는 설정 환경에서는 구매가 지원되지 않습니다.

    특정 기기, 계정 또는 설정 환경에서 구매할 수 없는 상품일 때 발생해요.


    APP_MARKET_VERIFICATION_FAILED : 앱스토어에서 사용자 정보 검증에 실패했습니다. 환불이 필요합니다.

    사용자가 결제를 완료했지만, 앱스토어에서 사용자 정보 검증에 실패했을 때 발생해요. 사용자가 앱스토어에 문의해서 환불을 요청해야해요.


    TOSS_SERVER_VERIFICATION_FAILED : 결제가 완료되었지만, 서버 전송에 실패했습니다.

    사용자가 결제를 완료했지만, 서버 전송에 실패해서 결제 정보를 저장할 수 없을 때 발생해요.


    INTERNAL_ERROR : 내부 오류가 발생했습니다. 잠시 후 다시 시도해주세요.

    서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.


    KOREAN_ACCOUNT_ONLY : 한국 계정만 사용 가능합니다. 다른 계정을 사용해주세요.

    iOS 환경에서 사용자의 계정이 한국 계정이 아닐 때 발생해요.


    USER_CANCELED : 사용자가 결제를 취소했습니다.

    사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.


    PRODUCT_NOT_GRANTED_BY_PARTNER : 파트너사의 상품 지급이 실패했습니다

    파트너사의 상품 지급이 실패했을 때 발생해요. 토스앱 5.230.0 이상에서만 발생해요.


반환값 ​

  • () => void

    앱브릿지 cleanup 함수를 반환해요. 인앱결제 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.

예제 ​

특정 인앱결제 주문서 페이지로 이동하기 ​

tsx
import { IAP } from "@apps-in-toss/web-framework";
import { Button } from "@toss-design-system/mobile";
import { useCallback } from "react";
 
 interface Props {
   sku: string;
 }
 
 function IapCreateOneTimePurchaseOrderButton({ sku }: Props) { 
  const handleClick = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
        },
      onEvent: (event) => {
        console.log(event);
      },
      onError: (error) => {
        console.error(error);
      },
    });

    return cleanup;
  }, []);

   return <Button onClick={handleClick}>구매하기</Button>;
 }
tsx
import { IAP } from "@apps-in-toss/framework";
import { Button } from "@toss-design-system/react-native";
import { useCallback } from "react";
 
 interface Props {
   sku: string;
 }
 
 function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
  const handleClick = useCallback(() => {
    const cleanup = IAP.createOneTimePurchaseOrder({
      options: {
        sku,
        processProductGrant: ({ orderId }) => {
          // 상품 지급 로직을 작성해요.
          return true; // 상품 지급 여부를 반환해요.
        }
        },
      onEvent: (event) => {
        console.log(event);
      },
      onError: (error) => {
        console.error(error);
      },
    });

    return cleanup;
  }, []);

   return <Button onPress={handleClick}>구매하기</Button>;
 }

예제 앱 체험하기 ​

apps-in-toss-examples 저장소에서 with-in-app-purchase 코드를 내려받아 체험해 보세요.