아임포트(Iamport)로 결제기능 구현하기 - 일반결제
이전 포스트에 이어서 라라벨에 아임포트를 연동해보자. 마이그레이션, 모델, 컨트롤러가 준비되었다면 이제 해야 할 일은 아임포트의 개발가이드를 보면서 코드를 구현하는 일 뿐이다. 개발가이드에서 일반결제 부분에 보면 Node.js 를 사용한 구현 방법이 나와있는데, 이를 PHP로 표현하는 것은 어려운 일이 아니다.
장바구니
장바구니에 해당하는 Order 를 만들고(Create), 읽는(Read)코드를 작성해보자. 수정과 삭제는 주제를 벗어나므로 구현하지 않는다.
쓰기
쓰기는 컨트롤러에서 OrderController::create(), OrderController::store() 에서 진행한다. OrderController::create() 에는 사용자에게 보여지는 뷰를 반환하면 되고, OrderController::store() 에는 리소스를 실제로 생성하는 행위를 해주면 된다.
namespace App\Http\Controllers;
use App\Models\Order;
use Illuminate\Http\Request;
class OrderController extends Controller
{
/**
* Show the form for creating a new resource.
*
* @return \Illuminate\Http\Response
*/
public function create()
{
return view('orders.create');
}
/**
* Store a newly created resource in storage.
*
* @param \Illuminate\Http\Request $request
* @return \Illuminate\Http\Response
*/
public function store(Request $request)
{
$request->validate([
'amount' => 'required|numeric|min:100'
]);
Order::create([
'amount' => $request->amount
]);
return redirect()->route('orders.index');
}
}OrderController::create() 에서 orders.create 뷰를 반환한다. 즉, resources/views/orders/create.blade.php 를 이야기한다. OrderController::store() 에서는 상품의 가격을 받아오고 주문을 저장하는게 전부다. 끝나면 주문목록이 있는 orders.index 라우트로 이동한다.
뷰
쓰기에서 뷰는 orders.create 만 신경쓰면 된다. 이상해보이겠지만, 이 부분은 일반적인 쇼핑몰이라면 상품상세페이지로 대체된다. 이 코드는 단순히 100원의 가격을 가진 무언가를 장바구니에 담으라는 이야기다.
<form action="{{ route('orders.store') }}" method="POST">
@csrf
<input type="number" name="amount" value="{{ old('amount', 100) }}">
<button type="submit">장바구니에 담기</button>
</form>KG이니시스에서 카드결제를 이용할 때 최소결제 금액이 100원이라는 점을 잊지말자.
읽기
읽는 것은 주문 목록을 표시하는 것이 전부다. 그를 위해서는 아직 결제가 처리되지 않은(Unpaid) 주문의 목록을 전부 표시해주면 된다. 또한 merchant_uid, amount 의 경우 결제할 때 반드시 필요한 정보이기 때문에 전달해야한다. merchant_uid 는 서버에서 주문에 대한 유일한 값이어야하며 같은 값으로 주문된 경우 이미 처리된 것으로 간주하여 에러를 발생시킨다. 실제로 결제가 진행되면 merchant_uid 가 payments 테이블에 기본 키로 입력된다.
namespace App\Http\Controllers;
use App\Models\Order;
use Illuminate\Support\Str;
class OrderController extends Controller
{
/**
* Display a listing of the resource.
*
* @return \Illuminate\Http\Response
*/
public function index()
{
$orders = Order::unpaid()->get();
$unpaidPayment = Payment::create([
'amount' => $orders->reduce(function ($amount, $order) {
return $amount += $order->amount;
})
]);
return view('orders.index', [
'orders' => $orders,
'merchant_uid' => $unpaidPayment->merchant_uid,
'amount' => $unpaidPayment->amount
]);
}
}주문번호(merchant_uid) 생성하기
IMP.request_pay를 호출하기 전에 서버에서 데이터베이스에 주문 레코드를 생성하여 해당 레코드의 주문번호를 param.merchant_uid 에 지정하기를 권장합니다. 결제 프로세스 완료 후 해당 주문번호를 서버에서 조회하여 결제 위변조 여부를 검증하는데 필요합니다.
뷰
orders.index 뷰를 살펴보자. 단순하게 주문목록을 표기하고 결제하기 버튼만이 있을 뿐이다. 이 버튼의 동작에 대해서는 바로 아래에서 다룬다.
<ul>
@foreach ($orders as $order)
<li>{{ $order->amount }}</li>
@endforeach
</ul>
<button type="button" id="payment">결제하기</button>아임포트 서버에 결제요청 보내기
결제는 꽤 단순하게 처리될 수 있는데, 위에서 만든 결제하기 버튼을 누르면 KG이니시스의 결제화면이 나타나도록 만들어보자. 결제의 구현에 대해서는 아임포트의 개발가이드에서 일반결제를 참고한다.
결제화면을 띄우기 위해서는 아임포트의 Javascript SDK 를 참고해야 할 필요가 있다. 핵심 함수는 IMP.request_pay() 이다. IMP.init() 으로 초기화를 시켜주고 요청해보자. 호출에 요구되는 파라매터 목록은 Javascript SDK 에서 request_pay 에 나와있으니 참고하자.
<!-- jQuery -->
<script type="text/javascript" src="https://code.jquery.com/jquery-3.6.0.min.js" ></script>
<!-- iamport.payment.js -->
<script type="text/javascript" src="https://cdn.iamport.kr/js/iamport.payment-1.2.0.js"></script>
<script>
IMP.init("{{ config('services.iamport.merchant_id') }}");
$('#payment').click(() => {
IMP.request_pay({
pg: '{{ config('services.iamport.pg') }}',
pay_method: 'card',
merchant_uid: '{{ $merchant_uid }}',
name: '테스트',
amount: {{ $amount }}, // 최소금액
buyer_email: 'pronist@naver.com',
buyer_name: '정상우'
}, rsp => {
if (! rsp.success) alert(rsp.error_msg)
})
})
</script>이제 결제하기 버튼을 누르면 PG사에 해당하는 결제화면이 나타난다. 결제의 성공실패 여부에 관계없이 두 번째 매개변수로 설정한 콜백이 호출된다. 성공여부는 rsp.success 에서 분기할 수 있다. 결제에 성공한 경우 서버에 반영을 해야한다. 그럼 어떻게 해야할까? 사실 그냥 AJAX 를 요청하면 그만이다. 예를 들면 아래와 같다.
$.ajax('/iamport-webhook', {
method: 'POST',
data: {
imp_uid: rsp.imp_uid,
merchant_uid: rsp.merchant_uid
},
success: data => {}
})그러나 우리는 이 방법이 아닌 아임포트에서 제공하는 웹훅(Webhook)으로 처리해보고자한다. 아임포트 Webhook 을 사용하면 사용자가 브라우저에서 결제시 아임포트 서버에서 직접 우리 서버로 요청을 보내게 된다. 웹훅을 사용하면 클라이언트 측 네트워크 문제로 결제만 처리되고 서버에 적용이 안 되는 경우를 방지할 수 있다.
아임포트 Webhook
관리자 콘솔 - 시스템 설정 - 웹훅(Notification)설정에서 할 수 있는데, 아임포트에서는 다음과 같이 요청을 보낸다. imp_uid, merchant_uid 가 가장 중요한 정보임을 잊지말자.
curl -H "Content-Type: application/json" -X POST -d '{ "imp_uid": "imp_1234567890", "merchant_uid": "order_id_8237352", "status": "paid" }' { NotificationURL }로컬 서버에서 웹훅 테스트를 해보려면 다른 방법이 필요한데, 아임포트 문서에도 나와있듯이 ngrok 를 사용하는 것이다.
$ ngrok http localhost:8000
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Account Sangwoo Jeong (Plan: Free)
Version 2.3.40
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://9ff1-183-91-206-236.ngrok.io -> http://localhost:8000
Forwarding https://9ff1-183-91-206-236.ngrok.io -> http://localhost:8000
Connections ttl opn rt1 rt5 p50 p90
6 0 0.00 0.00 4.19 5.19이렇게 처리하고 https://9ff1-183-91-206-236.ngrok.io 로 접속하면 올바른 화면이 나와야 한다. 하지만 문제가 발생했다면 AuthToken 을 설정해야 한다. https://dashboard.ngrok.com/get-started/your-authtoken
에 진입하고 지시순서에 따르자.
ngrok authtoken <authtoken>자 이제 다시 관리자 콘솔로가서 설정해보자.
CSRF
라라벨에서는 요청시 CSRF TOKEN 이 포함되는 것이 기본이다. 그러나 웹훅은 CSRF TOKEN 을 포함하지 않는다. 따라서 제외시켜줄 필요가 있다. App\Http\Middleware\VerifyCsrfToken::$except 에서 설정하자.
namespace App\Http\Middleware;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;
class VerifyCsrfToken extends Middleware
{
/**
* The URIs that should be excluded from CSRF verification.
*
* @var array<int, string>
*/
protected $except = [
'/iamport-webhook'
];
}결제상태에 따라 서버에서 처리하기
이제 우리 서버에 결제 상태에 따라 처리만 해주면 된다. 장바구니 담은 상품을 결제하게되면 Payment 를 생성하고 해당 주문들은 생성된 Payment 의 merchant_uid 를 가지고 있도록 해보자.
검증하기
하지만 그 전에 결제를 검증해야한다. 자바스크립트 코드는 조작하기 아주 쉽기때문에 사용자가 실제로 결제한 금액과 결제된 금액에 상응하는 서버의 처리가 달라서는 안 되기 때문이다. 따라서 이 경우에는 아임포트 API 를 통해 결제된 정보를 얻어온 다음 실제 결제금액과 서버에 저장된 결제된 금액을 대조해야 한다. 두 과정을 거쳐야하는데, 하나는 엑세스 토큰(Access Token)을 얻어오는 것이고 또 하나는 해당 엑세스토큰을 가지고 아임포트 API 에 요청하여 결제정보를 얻어오는 것이다.
Iamport
App\Traits\Iamport 를 하나 만들고 엑세스 토큰을 얻어오는 것과 결제정보를 얻어오는 것을 래핑해보자. Iamport::getAccessToken() 으로는 엑세스 토큰을 얻어오고 Iamport::getPayment() 에서는 결제정보를 얻어온다.
namespace App\Traits;
use GuzzleHttp\Client;
use Illuminate\Support\Facades\Http;
trait Iamport
{
/**
* Get AccessToken
*
* @return string|false
*/
private function getAccessToken()
{
$response = Http::iamport()->post('users/getToken', [
'imp_key' => config('services.iamport.client_id'),
'imp_secret' => config('services.iamport.client_secret')
]);
if ($response->ok()) {
return $response->object()->response->access_token;
}
return false;
}
/**
* Get Payment Information
*
* @param string $accessToken
* @param string $impUid
* @return mixed|false
*/
private function getPayment(string $accessToken, string $impUid)
{
$response = Http::iamport()->withToken($accessToken)->get("payments/{$impUid}");
if ($response->ok()) {
return $response->object()->response;
}
return false;
}
}Http 파사드를 사용하면 Http 요청을 손쉽게 처리할 수 있으며 Http::iamport() 처럼 매크로(Macro)를 만들어내려면 App\Providers\AppServiceProvider::boot() 에서 등록을 해야한다.
namespace App\Providers;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
Http::macro('iamport', function () {
return Http::baseUrl('https://api.iamport.kr');
});
}
}IamportController
이제 IamportController::webhook() 에서 결제를 처리하되, 검증을 위한 메서드인 IamportController::verify() 를 하나 만들자. 결제정보를 얻어와서 서버에서 결제되어야 했던 정보와 비교하고 정상적인 처리라면 결제정보를 반환하자. 만들어둔 Iamport 트레이트를 포함하는 것을 잊지말자.
namespace App\Http\Controllers;
use App\Models\Order;
use App\Models\Payment;
use App\Traits\Iamport;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Http\Request;
class IamportController extends Controller
{
use Iamport;
/**
* Verify payment
*
* @param string $impUid
* @param int $amountToBePaid
* @return mixed|false
*/
private function verify(string $impUid, int $amountToBePaid)
{
$accessToken = $this->getAccessToken();
$data = $this->getPayment($accessToken, $impUid);
if ($amountToBePaid !== $data->amount) {
return false;
}
return $data;
}
}이제 IamportController::webhook() 에서 실제로 결제를 처리해보자. 코드가 제법 길지만 차근차근 살펴보면 별거 아니다.
namespace App\Http\Controllers;
use App\Models\Order;
use App\Models\Payment;
use App\Traits\Iamport;
use Illuminate\Http\Request;
class IamportController extends Controller
{
use Iamport;
/**
* Iamport Webhook
*
* @param \Illuminate\Http\Request $request
* @return \Illuminate\Http\JsonResponse
*/
public function webhook(Request $request)
{
$request->validate([
'merchant_uid' => 'required',
'imp_uid' => 'required'
]);
$payment = Payment::findOrFail($request->merchant_uid);
if ($data = $this->verify($request->imp_uid, $payment->amount)) {
$payment->update([
'imp_uid' => $request->imp_uid,
'amount' => $data->amount,
'cancel_amount' => $data->cancel_amount,
'pay_method' => $data->pay_method,
'status' => $data->status
]);
switch ($data->status) {
// 가상계좌가 발급되었을 때
// case 'ready':
// 결제가 승인되었을 때, 예약결제가 시도되었을 때, 가상계좌에 결제 금액이 입금되었을 때
case 'paid':
return $this->paid($payment);
// 예약결제가 시도되었을 때
case 'failed':
return $this->failed();
// 관리자 콘솔에서 환불되었을 때
case 'cancelled':
return $this->cancelled($payment, $data);
}
}
return response()->json([
'status' => 'forgery', 'message' => __('iamport.forgery')
], 400);
}
/**
* Verify
*
* @param string $impUid
* @param int $amountToBePaid
* @return mixed|false
*/
private function verify(string $impUid, int $amountToBePaid)
{
//
}
/**
* Paid
*
* @param Payment $payment
* @return \Illuminate\Http\JsonResponse
*/
private function paid(Payment $payment)
{
$payment->orders()->saveMany(Order::unpaid()->get());
return response()->json([
'status' => 'paid', 'message' => __('iamport.paid')
]);
}
/**
* Cancelled
*
* @param Payment $payment
* @return \Illuminate\Http\JsonResponse
*/
private function cancelled(Payment $payment, $data)
{
// 관리자 콘솔에서 부분환불 되었을 때
if ($payment->amount > $data->cancel_amount) {
return response()->json([
'status' => 'uncancelled', 'message' => __('iamport.uncancelled')
]);
}
$payment->orders()->delete();
return response()->json([
'status' => 'cancelled', 'message' => __('iamport.cancelled')
]);
}
/**
* Failed
*
* @return \Illuminate\Http\JsonResponse
*/
private function failed()
{
return response()->json([
'status' => 'failed', 'message' => __('iamport.failed')
]);
}
}먼저 검증을 처리하기 위해 IamportController::verify() 를 호출한다. 서버에서 결제가 되어야하는 금액과 실제금액을 비교해야하는데, 실제 결제된 금액은 아임포트 API 로 얻어왔으니 서버에서 결제가 되길 바라는 금액만 얻어오면 된다. 결제를 하기 전에 미리 저장해둔 것이 있으니 얻어오면 된다.
결제가 잘 처리되었으면 status 에 결제 상태가 기재되는데, ready, paid 등 여러 상태가 존재한다. 아임포트 가이드북에 따르면 다음과 같다.
- 결제가 승인되었을 때(모든 결제 수단) - (status : paid)
- 가상계좌가 발급되었을 때 - (status : ready)
- 가상계좌에 결제 금액이 입금되었을 때 - (status : paid)
- 예약결제가 시도되었을 때 - (status : paid or failed)
- 관리자 콘솔에서 환불되었을 때 - (status : cancelled)
이에 따라 switch 문을 구성할 수 있고, paid 가 결제가 승인되었을 때를 의미하므로 paid 상태에서 결제를 저장하고 주문에 대해서도 결제처리를 해주면 된다. 이 구현은 관리자 콘솔에서 환불되었을 때를 포함하여 구현한다. 사용자가 아임포트 서버에 요청하여 부분환불을 할 수 있게하려면 다른 구현이 필요하다.
