게이트웨이 템플릿

게이트웨이 템플릿은 자체 POS 전용 결제 게이트웨이를 구축하기 위한 시작점을 제공합니다. 필요한 대로 설치하고 사용자 정의할 수 있는 PHP 파일 하나로 작동하는 WordPress 플러그인을 생성합니다.

기능

최소화된 코드

필수 요소만 포함된 하나의 PHP 파일 — 읽기와 수정을 쉽게 할 수 있습니다.

POS 전용

기본적으로 웹 체크아웃에서는 비활성화되어 있으며, WCPOS 설정을 통해 활성화됩니다.

자동 설정

쉘 스크립트가 모든 자리 표시자 교체를 처리합니다.

GitHub 릴리스

버전 변경을 푸쉬하면 GitHub Actions가 다운로드 가능한 ZIP 파일을 빌드합니다.

시작하기

1

템플릿 리포지토리 복제하기

git clone https://github.com/wcpos/woocommerce-gateway-template.git
cd woocommerce-gateway-template

또는 GitHub 리포지토리에서 이 템플릿 사용 버튼을 클릭하여 자신의 복사본을 만듭니다.

2

설정 스크립트 실행하기

./create-gateway.sh

스크립트는 몇 가지 세부 정보를 요청합니다 — 게이트웨이 이름, 간단한 설명, GitHub 사용자 이름 — 이후 사용할 준비가 된 플러그인을 원하는 디렉토리에 생성합니다.

3

플러그인 설치하기

두 가지 옵션이 있습니다:

옵션 A — 폴더를 직접 복사하기 (서버 접근 권한이 있는 경우): 생성된 게이트웨이 폴더를 사이트의 wp-content/plugins/ 디렉토리에 복사합니다.

옵션 B — 압축 후 업로드하기 (대부분의 사람들에게 가장 쉬움):

1. 생성된 폴더를 .zip 파일로 압축합니다.
2. WordPress에서 플러그인 > 새로 추가 > 플러그인 업로드로 이동합니다.
3. ZIP 파일을 선택하고 지금 설치를 클릭합니다.

4

WCPOS에서 활성화하기

1. WP Admin > WCPOS > 설정 > 체크아웃으로 가세요.
2. 목록에서 새 게이트웨이를 찾아 활성화하세요.

참고

게이트웨이는 기본적으로 일반 웹 체크아웃에서 비활성화되어 있습니다. WCPOS는 자체 설정을 통해 POS에 표시되는 게이트웨이를 제어합니다.

수동 설정

스크립트를 사용하고 싶지 않다면 자리 표시자를 직접 교체할 수 있습니다. 텍스트 편집기에서 각 파일을 열고 다음과 같은 내용을 찾은 후 교체합니다:

자리 표시자	입력할 내용	예시
{{GATEWAY_NAME}}	게이트웨이의 표시 이름	현금 결제
{{GATEWAY_SLUG}}	URL 안전 식별자 (소문자, 하이픈)	cash-payment
{{GATEWAY_DESCRIPTION}}	게이트웨이에 대한 간단한 설명	WCPOS에서 현금 결제를 수락합니다.
{{GATEWAY_DEFAULT_DESCRIPTION}}	체크아웃 시 사용자에게 표시되는 텍스트	결제 시 현금으로 지불하세요.
{{GITHUB_USERNAME}}	GitHub 사용자 이름	kilbot
{{REPO_NAME}}	리포지토리 이름	cash-payment-gateway
{{AUTHOR_NAME}}	이름	kilbot
{{GATEWAY_ID}}	하이픈 대신에 밑줄이 있는 슬러그	cash_payment
{{GATEWAY_CLASS_NAME}}	각 단어의 첫 글자가 대문자인 형식으로 밑줄로 연결	Cash_Payment
{{GATEWAY_FUNCTION_PREFIX}}	게이트웨이 ID와 동일	cash_payment

그런 다음 wcpos-{{GATEWAY_SLUG}}.php의 이름을 슬러그와 동일하게 변경합니다 (예: wcpos-cash-payment.php).

팁

설정 스크립트는 이름과 슬러그에서 자동으로 GATEWAY_ID, GATEWAY_CLASS_NAME, GATEWAY_FUNCTION_PREFIX를 추출하므로, 수동 설정 시에만 이들에 대해 고민하면 됩니다.

작동 방식

생성된 플러그인은 WooCommerce 결제 게이트웨이 클래스를 등록합니다. 알아야 할 주요 사항은 다음과 같습니다:

• $this->enabled = 'no' — 게이트웨이는 웹 체크아웃에서 숨겨져 있습니다. WCPOS는 POS 설정에 따라 활성화합니다.
• process_payment() — $order->payment_complete()를 호출하여 주문을 결제됨으로 표시하고 재고 감소를 자동으로 처리합니다.
• init_form_fields() — WooCommerce 설정에 나오는 제목 및 설명 필드를 정의합니다.

게이트웨이 사용자 정의하기

결제 필드 추가하기

게이트웨이가 계산원으로부터 입력이 필요하다면 (예: 참조 번호), payment_fields() 메서드를 재정의합니다:

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

그런 다음 process_payment()에서 $_POST['my_gateway_reference']를 통해 제출된 값을 읽을 수 있습니다. 입력된 내용을 반드시 sanitize_text_field()로 정리해야 합니다.

결제 동작 변경하기

기본 템플릿은 주문을 즉시 결제 완료로 표시합니다. 워크플로우에서 나중에 결제가 필요하다면 (예: 인보이스), payment_complete()를 상태 업데이트로 교체합니다:

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

수정 및 업데이트 하기

게이트웨이를 설치한 후 플러그인 파일을 계속 편집하여 결제 로직을 조정할 수 있습니다. 업데이트된 버전을 설치하려면:

1. 생성된 폴더의 wcpos-your-slug.php를 수정합니다.
2. 플러그인 헤더의 Version: 번호를 업데이트합니다 (예: 0.1.0에서 0.2.0으로).
3. 폴더를 압축하고 다시 플러그인 > 새로 추가 > 플러그인 업로드를 통해 업로드하거나, wp-content/plugins/ 디렉토리에 직접 교체합니다.

팁

WordPress는 동일한 플러그인 이름을 가진 zip 파일을 업로드할 때 기존 플러그인을 교체하겠냐고 묻습니다 — 업로드된 것으로 현재 교체를 클릭하여 업데이트하세요.

GitHub를 통한 자동 릴리스

게이트웨이를 GitHub 리포지토리에 푸시하면 템플릿에 GitHub Actions 워크플로가 포함되어 자동으로 릴리스를 생성합니다:

1. 플러그인 헤더의 Version: 번호를 업데이트합니다.
2. main 브랜치에 커밋하고 푸시합니다.
3. GitHub Actions가 버전 변경을 감지하고 다운로드 가능한 ZIP이 포함된 새 릴리스를 생성합니다.

다른 사용자는 그런 다음 리포지토리의 릴리스 페이지에서 ZIP을 다운로드하고 WordPress 플러그인처럼 설치할 수 있습니다.

문제 해결

게이트웨이가 POS에 나타나지 않음

• WP Admin > 플러그인에서 플러그인이 활성화되어 있는지 확인합니다.
• WP Admin > WCPOS > 설정 > 체크아웃으로 가서 게이트웨이가 활성화되어 있는지 확인합니다.
• WooCommerce가 설치되어 있고 활성화되어 있는지 확인합니다.

게이트웨이가 웹 체크아웃에 나타남

• 게이트웨이 생성자에서 $this->enabled = 'no';로 설정되어 있는지 확인합니다.
• WCPOS는 POS 요청에 대해 이 설정을 덮어쓰므로, 게이트웨이는 POS에서만 나타납니다.

주문이 '처리 중' 상태로 남아있음 대신 '완료' 상태로 변경되지 않음

• WooCommerce는 제품 유형에 따라 주문 상태를 설정합니다. 물리적 제품을 포함하는 주문은 "처리 중" 상태로 유지됩니다 — 이는 정상적인 WooCommerce 동작입니다. 독점적으로 가상 또는 다운로드 가능한 제품으로만 구성된 주문만 자동으로 "완료"로 표시됩니다.

자원

• GitHub: woocommerce-gateway-template
• WooCommerce 결제 게이트웨이 API: WC_Payment_Gateway docs

예제 게이트웨이

다음은 같은 접근 방식으로 구축된 기존 게이트웨이이며, 좋은 참조가 됩니다:

• 이메일 청구서 — 고객이 나중에 지불할 수 있도록 청구서 이메일을 전송합니다.
• 웹 체크아웃 — 결제를 위해 웹 스토어로 리디렉션합니다.