게이트웨이 템플릿

게이트웨이 템플릿은 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 저장소에서 Use this template 버튼을 클릭하여 자신만의 사본을 만들 수 있습니다.

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}}	게이트웨이의 표시 이름	Cash Payment
{{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 설정에 따라 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/에서 폴더를 직접 교체합니다

팁

동일한 플러그인 이름의 zip 파일을 업로드하면 WordPress에서 기존 플러그인을 교체할지 묻습니다. 업로드된 파일로 현재 플러그인 교체를 클릭하여 업데이트하세요.

GitHub를 통한 자동 릴리스

게이트웨이를 GitHub 저장소에 푸시하면, 템플릿에 포함된 GitHub Actions 워크플로가 자동으로 릴리스를 생성합니다:

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

다른 사용자는 리포지토리의 Releases 페이지에서 ZIP 파일을 다운로드하여 일반 WordPress 플러그인처럼 설치할 수 있습니다.

문제 해결

Gateway doesn't appear in the POS

• WP Admin > 플러그인에서 플러그인이 활성화되어 있는지 확인합니다
• WP Admin > WCPOS > 설정 > 결제로 이동하여 게이트웨이가 활성화되어 있는지 확인합니다
• WooCommerce가 설치되어 있고 활성화되어 있는지 확인합니다

Gateway shows up on the web checkout

• 게이트웨이 생성자에서 $this->enabled = 'no';가 설정되어 있는지 확인합니다
• WCPOS는 POS 요청 시 이 설정을 재정의하므로, 게이트웨이는 POS에서만 표시됩니다

Orders stay in 'Processing' instead of 'Completed'

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

요구 사항

WCPOS: POS 결제에는 Pro 버전이 필요합니다

WordPress: WooCommerce가 설치된 WordPress

PHP: 게이트웨이 커스터마이징을 위한 기본 PHP 지식

리소스

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

게이트웨이 예제

아래 게이트웨이들은 동일한 방식으로 구축되었으며 좋은 참고 자료입니다:

• 이메일 인보이스 — 고객이 나중에 결제할 수 있도록 인보이스 이메일을 발송합니다
• 웹 결제 — 결제를 위해 웹 스토어로 리디렉션합니다