VibeFox Pagar.me for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

WooCommerce: 8.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인을 활성화할 수 없습니다.

PHP: 8.0 이상.

통화: 브라질 레알(BRL). 쇼핑몰 통화(Pay for order 페이지에서는 주문 통화)가 BRL이 아니면 결제 방법이 표시되지 않습니다.

Pagar.me 계정: Pagar.me 계정의 비밀 키가 필요합니다. 테스트 키(sk_test_...)와, 운영 전환 시 사용할 운영 키(sk_...)입니다. Pagar.me 대시보드의 Development > Keys에서 확인할 수 있습니다. 비밀 키만 사용하며, 공개 키(pk_...)는 필요하지 않습니다. Pagar.me 계정에서 활성화된 결제 수단만 제공할 수 있습니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 1개는 도메인 1개에서 사용할 수 있습니다.

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택한 뒤 Install Now를 클릭합니다. FTP로 wcp_pagarme_gateway 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Payments > Pagar.me > Manage. 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

4. 페이지 상단의 라이선스 블록에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

5. 테스트 비밀 키를 입력하고, 운영을 시작할 때 운영 비밀 키를 입력합니다.

6. Pagar.me 대시보드에서 설정에 표시된 URL로 웹훅을 생성합니다(구성 항목 참조).

7. Enable / Disable을 켜고 저장합니다. Test mode를 켠 상태에서 테스트 결제를 진행한 뒤, 실제 결제를 받으려면 끕니다.

구성

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Pagar.me. 제목 아래에 페이지는 현재 모드를 표시합니다: TEST MODE(테스트 비밀 키로 결제가 생성되며 실제 청구는 없습니다) 또는 LIVE. 현재 모드의 비밀 키가 없으면(이 경우 결제 방법은 체크아웃에서 숨겨집니다), 테스트 키가 sk_test_로 시작하지 않으면, 운영 키가 sk_로 시작하지 않거나 테스트 키이면, 쇼핑몰 통화가 BRL이 아니면 경고합니다. 결제 방법 목록에서는 현재 모드의 키를 입력할 때까지 Pagar.me가 설정이 필요한 상태로 표시되며, 테스트 모드가 켜져 있는 동안에는 테스트 모드 배지가 표시됩니다.

일반

Enable / Disable: Enable Pagar.me payments는 결제 방법을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 체크아웃에서 보는 결제 방법 이름. 기본값: Pagar.me.

Description: 체크아웃에서 결제 방법 아래에 표시되는 텍스트. 기본값: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

API 키

Pagar.me 대시보드(Development > Keys)에서 비밀 키를 복사합니다. Pagar.me는 테스트 결제와 운영 결제에 하나의 API 주소를 사용하며, 결제가 테스트인지 실결제인지는 키가 결정합니다.

Test mode: Use the test secret key (no real charges). 테스트 모드가 켜져 있는 동안 체크아웃에 TEST MODE 안내가 표시됩니다. 주문의 상태 조회와 환불은 항상 해당 결제가 이루어진 모드의 키를 사용합니다. 기본값: 켬.

Test secret key: Pagar.me 테스트 비밀 키(sk_test_...). 테스트 모드가 켜져 있을 때 사용됩니다.

Live secret key: Pagar.me 운영 비밀 키(sk_...). 테스트 모드가 꺼져 있을 때 사용됩니다. 비밀로 유지하십시오.

버전 1.0의 단일 비밀 키는 자동으로 옮겨집니다. 테스트 키는 Test secret key로 옮겨지고 테스트 모드가 켜집니다. 그렇지 않으면 운영 키로 남고 테스트 모드는 꺼집니다.

결제 페이지

Payment methods: Pagar.me 결제 페이지에서 제공되는 결제 수단. Pagar.me 계정에서 활성화된 수단만 선택하십시오. 기본값: Credit card, PIX, Boleto.

Boleto due in (days): boleto 납부 기한까지의 일수(1~30). Pagar.me가 결제를 확인할 때까지 주문은 On hold 상태로 남습니다. 기본값: 3.

결제 알림(웹훅)

Pagar.me 대시보드에서 Settings > Webhooks를 열고, 이 섹션에 표시된 URL로 웹훅을 생성합니다. 형태는 https://your-site/wc-api/webhook_wc_pagarme/와 같습니다. 설정에 표시된 그대로 정확히 복사하십시오.

다음 이벤트를 선택합니다:

웹훅에는 비밀번호나 서명이 필요하지 않습니다. 웹훅의 내용은 결코 신뢰되지 않습니다. 쇼핑몰은 웹훅에서 Pagar.me 주문 ID만 가져오고, 그 주문을 생성된 모드의 키로 Pagar.me API에서 읽습니다. 같은 Pagar.me 계정의 다른 쇼핑몰 주문에 대한 알림은 무시됩니다. 웹훅이 없으면 나중에 이루어진 PIX와 boleto 결제는 고객이 쇼핑몰로 돌아올 때에만 확인됩니다.

고급

Debug log: Log API requests and notifications는 WooCommerce > Status > Logs에 세부 정보를 기록합니다(소스: wcp_pagarme_gateway). 오류는 항상 기록됩니다. 로그에는 키나 고객 데이터가 없습니다. 기본값: 끔.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. 기본값: 끔.

체크아웃

고객은 결제 방법(기본값 Pagar.me)을 선택하고 주문을 완료합니다. 유효한 청구 이메일 주소가 필요합니다. 플러그인은 주문 합계를 BRL로 하여 Pagar.me 주문을 생성하며, 주문 항목, 배송비 및 수수료를 포함합니다(항목을 정확히 합산할 수 없으면 주문 번호가 들어간 Order # 한 줄로 대체합니다). 그런 다음 고객을 Pagar.me 결제 페이지로 보냅니다. 고객의 이름, 이메일, 브라질의 경우 전화번호와 청구 주소가 Pagar.me로 전달됩니다. CPF 또는 CNPJ는 Brazilian Market on WooCommerce 플러그인의 항목이 있으면 거기서 가져오고, 없으면 고객이 Pagar.me 페이지에서 입력합니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Pagar.me가 확인한 후에야 결제 완료로 표시됩니다. 쇼핑몰은 API에서 Pagar.me 주문을 읽으며, 결제된 금액과 통화는 주문과 일치해야 합니다. 카드, PIX 또는 boleto 결제가 완료되면 주문은 결제 완료가 됩니다. 발급되었지만 아직 결제되지 않은 PIX 또는 boleto는 Pagar.me가 웹훅으로 결제를 확인할 때까지 주문을 On hold 상태로 둡니다.

고객이 결제하지 않고 돌아오거나, 결제가 거절되었거나 취소된 경우, 고객은 Pay for order 페이지로 이동하며 The Pagar.me payment was not completed. You can pay the order below. 또는 The Pagar.me payment was declined or canceled. You can try again below. 메시지가 표시됩니다.

고객이 다시 결제하면, 금액과 모드가 같을 경우 열려 있는 Pagar.me 결제 페이지를 재사용합니다. 그렇지 않으면 새 결제 페이지를 만들기 전에 Pagar.me에서 그 페이지를 닫습니다. 그 사이 이전 시도가 결제되었거나 해당 PIX 또는 boleto가 아직 대기 중이라면, 추가 결제 없이 주문이 업데이트됩니다. 이전 페이지를 닫을 수 없으면 그 페이지는 주문과 계속 연결되어 있어, 그 페이지에서 이루어진 결제도 기록됩니다.

Pagar.me가 결제를 시작할 수 없으면 고객에게 Could not connect to Pagar.me. Please try again in a moment.와 같은 짧은 메시지나, 청구 정보가 잘못되었다는 Pagar.me 메시지가 표시됩니다. 기술적인 이유는 주문 메모에 추가됩니다.

결제 방법은 클래식 체크아웃, Checkout 블록, Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다.

이 플러그인은 체크아웃에 카드 입력 양식이 없으며, 저장된 카드, 구독 또는 정기 결제, 할부 규칙, 분할 결제(마켓플레이스), 승인 전용 카드 결제, Pagar.me Hub 연동을 지원하지 않습니다.

주문 및 환불

주문 상태

Pending payment: 고객이 Pagar.me로 이동했지만 아직 결제하지 않았거나 PIX 또는 boleto를 발급하지 않았습니다. 메모에는 Pagar.me 주문 ID와 모드가 표시됩니다.

Processing: 결제가 확인되었습니다. 결제 후 WooCommerce의 기본 상태입니다. 다운로드 가능한 가상 상품만 있는 주문은 Completed가 됩니다. 주문 메모에는 Pagar.me 주문 ID와 결제 수단이 표시됩니다. 거래 ID는 Pagar.me 주문 ID(or_...)입니다.

On hold: PIX 또는 boleto가 발급되었거나(또는 카드 결제가 심사 중이며) 결제를 기다리고 있습니다. boleto가 일부만 결제되었거나, 결제된 금액 또는 통화가 주문과 다르거나, 주문이 취소된 후 결제가 도착했거나, 고객이 다른 결제 수단으로 바꾼 뒤 Pagar.me에서 주문이 결제되었거나, 결제 완료된 주문에 차지백이 열린 경우입니다. 주문 메모에 이유가 설명되어 있습니다. 주문을 검토한 후 Processing으로 설정하거나, Pagar.me에서 결제를 환불하십시오.

Failed: 결제가 실패했거나, Pagar.me 주문이 취소되었거나 만료되었습니다(예: 결제되지 않은 boleto). 결제되지 않은 주문의 최신 시도만 주문을 Failed로 만들 수 있습니다. 고객은 다시 결제할 수 있습니다.

Refunded: Pagar.me에서 결제가 환불되었거나 취소되었습니다.

각 Pagar.me 상태는 한 번만 적용되므로, 반복되는 웹훅이나 복귀로 메모, 이메일 또는 재고 차감이 추가되지 않습니다. 결제 완료된 주문이 다시 대기 또는 실패 상태로 되돌려지는 일은 없으며, 취소되었거나 환불된 주문이 다시 열리는 일도 없습니다. 같은 WooCommerce 주문에 속한 두 번째 Pagar.me 주문이 결제되면, 메모가 Pagar.me 대시보드에서 중복분을 환불하라고 알려 줍니다.

환불

주문을 열고 Refund를 클릭하여 금액을 입력한 뒤 Refund via Pagar.me를 클릭합니다(버튼에는 결제 방법의 제목이 표시됩니다). 카드 및 PIX 결제의 전액 및 부분 환불을 지원하며, Pagar.me에서 아직 환불 가능한 금액까지 가능합니다. 환불은 결제가 이루어진 모드의 키로 전송됩니다. Pagar.me가 확인한 경우에만 환불이 기록됩니다. 그렇지 않으면 WooCommerce가 Pagar.me refused the refund: ... 또는 Pagar.me did not confirm the refund와 같은 오류를 표시하며, 환불은 기록되지 않습니다. 성공한 환불은 청구 ID와 함께 주문 메모에 추가됩니다.

boleto 결제는 고객의 은행 계좌로만 환불할 수 있습니다. Pagar.me 대시보드에서 환불한 후, Refund via Pagar.me를 사용하지 않고 WooCommerce에 환불을 수동으로 기록하십시오.

Pagar.me 대시보드에서 이루어진 전액 환불 또는 취소는 웹훅으로 전달되어 주문을 Refunded로 설정합니다. 차지백은 메모를 추가하고, Processing 또는 Completed 주문을 On hold로 만듭니다.

라이선스 키

이 플러그인은 vibefox.net에서 발급받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Pagar.me 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭하십시오. 블록에는 라이선스 유효 기간이나 도메인 등의 상태가 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 1개는 도메인 1개에서 사용할 수 있습니다. 사이트에서 키를 제거해도 해당 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

활성 키가 없으면 체크아웃에서 고객에게 Pagar.me가 표시되지 않습니다. 그럼에도 결제가 시작되면 고객은 This payment method is not available. Please choose another one.를 보게 됩니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only) 표시와 함께 결제 방법이 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 나타납니다. 기존 주문에는 영향이 없으며, 이미 시작된 결제는 계속 확인되고 환불도 작동합니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만, 업데이트와 지원을 받으려면 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

체크아웃에 Pagar.me가 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드의 비밀 키(테스트 모드에서는 Test secret key, 운영 모드에서는 Live secret key)가 설정되어 있는지, 쇼핑몰 통화가 BRL인지 확인하십시오. 설정 페이지는 각 경우에 대해 경고를 표시합니다.

결제는 완료되었지만 주문이 Pending payment 또는 On hold 상태로 남아 있음: 웹훅이 제대로 작동하지 않습니다. Pagar.me 대시보드에서 사용 중인 계정과 모드에 웹훅이 있는지, URL이 설정에 표시된 것과 정확히 같은지, 위에 나열된 이벤트가 선택되어 있는지 확인하십시오. 고객이 쇼핑몰로 돌아오면 주문도 확인됩니다.

웹훅이 verification failed, retry later로 응답함: 쇼핑몰이 API에서 Pagar.me 주문을 읽지 못했습니다. 예를 들어 해당 모드의 키가 없거나 API가 응답하지 않은 경우입니다. Pagar.me는 웹훅을 재시도합니다.

웹훅이 busy, retry later로 응답함: 같은 순간 다른 요청이 주문을 업데이트하고 있었습니다. Pagar.me는 웹훅을 재시도합니다.

웹훅이 unknown order로 응답함: 이 Pagar.me 주문은 이 쇼핑몰이 생성한 것이 아닙니다. 예를 들어 같은 계정의 다른 쇼핑몰 주문입니다. 아무것도 변경되지 않습니다.

고객이 This order is already being processed를 봄: 웹훅이나 고객의 복귀가 같은 순간 주문을 업데이트하고 있었습니다. 고객은 잠시 후 다시 시도할 수 있습니다.

고객이 Pagar.me payments are not available right now를 봄: 비밀 키가 잘못되었거나 없습니다. 현재 모드의 키를 확인하십시오.

고객이 Pagar.me could not start the payment를 봄: Pagar.me가 청구 정보를 거절했습니다. 메시지에 문제가 표시되며, 전체 이유는 주문 메모에 있습니다.

고객이 Pagar.me only supports payments in Brazilian Real (BRL)을 봄: 주문이 다른 통화입니다(예: 통화 전환 플러그인 때문일 수 있습니다).

결제 후 주문이 On hold 상태임: 주문 메모를 읽으십시오. PIX 또는 boleto가 결제를 기다리고 있거나, 결제된 금액 또는 통화가 달랐거나, 주문 취소 후 결제가 도착한 경우입니다.

boleto 환불 실패: boleto 결제는 API로 환불할 수 없습니다. Pagar.me 대시보드에서 환불하고 수동으로 기록하십시오.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르십시오. 예를 들어 키가 이미 다른 도메인에서 사용 중이라면, vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하십시오. 사이트 주소가 바뀌었다면 Check now를 클릭하여 새 도메인에 키를 활성화하십시오. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 작동합니다.

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 완전히 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 플러그인 로그는 Delete data on uninstall이 켜져 있을 때에만 삭제됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 남아 있습니다. 기존 주문은 결제 메모, 거래 ID, Pagar.me 데이터를 유지합니다.

Pagar.me는 해당 소유자의 상표입니다. 이 플러그인은 Pagar.me와 제휴하거나 Pagar.me의 승인을 받은 것이 아닙니다.