QR 결제 API 문서

API 헬퍼 클래스

<?php
/**
 * NEXVA QR 결제 API 클라이언트
 */
class NexvaQrPay
{
    private string $baseUrl = 'https://nexva.giftp2p.net/api/qr-pay';
    private string $token;

    public function __construct(string $token)
    {
        $this->token = $token;
    }

    /** QR 결제 생성 */
    public function createPayment(int $amount, array $options = []): array
    {
        return $this->request('POST', '/', array_merge([
            'amount' => $amount,
        ], $options));
    }

    /** 결제 상태 조회 */
    public function getStatus(string $paymentCode): array
    {
        return $this->request('GET', "/{$paymentCode}/status");
    }

    /** 결제 취소 */
    public function cancel(string $paymentCode): array
    {
        return $this->request('POST', "/{$paymentCode}/cancel");
    }

    /** 환전 신청 (금액 기반, 자동 분할) */
    public function redeem(int $amount, array $options = []): array
    {
        return $this->request('POST', '/redeem', array_merge([
            'amount' => $amount,
        ], $options));
    }

    /** 결제 목록 조회 */
    public function listPayments(int $page = 1, ?string $status = null): array
    {
        $query = ['page' => $page];
        if ($status) $query['status'] = $status;
        return $this->request('GET', '/my-payments?' . http_build_query($query));
    }

    /** 내 상품권 조회 */
    public function myCards(): array
    {
        return $this->request('GET', '/my-cards');
    }

    private function request(string $method, string $path, array $data = []): array
    {
        $ch = curl_init($this->baseUrl . $path);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 30,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->token,
                'Content-Type: application/json',
                'Accept: application/json',
            ],
        ]);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $result = json_decode($response, true) ?? [];
        $result['_http_code'] = $httpCode;
        return $result;
    }
}

// ──────── 사용 예시 ────────

$api = new NexvaQrPay('YOUR_API_TOKEN');

// 1. QR 결제 생성
$payment = $api->createPayment(50000, [
    'description' => '주문 #1234',
    'external_id' => 'ORDER-1234',
    'customer_id' => 'CUST-5678',
]);
echo "결제코드: " . $payment['payment']['payment_code'] . "\n";
echo "결제 URL: " . $payment['payment']['payment_url'] . "\n";
echo "QR 이미지: " . $payment['payment']['qr_image_url'] . "\n";

// 2. 상태 폴링 (결제 완료 대기)
do {
    sleep(3);
    $status = $api->getStatus($payment['payment']['payment_code']);
} while ($status['status'] === 'pending');

echo "결제 상태: " . $status['status'] . "\n";

// 3. 환전 신청
$redeem = $api->redeem(150000, [
    'external_id' => 'REDEEM-001',
    'customer_id' => 'CUST-5678',
]);
echo "환전 요청번호: " . $redeem['request_no'] . "\n";

콜백 수신 (webhook receiver)

<?php
// callback.php — 콜백 수신 서버
$payload = json_decode(file_get_contents('php://input'), true);

if (!$payload || !isset($payload['event'])) {
    http_response_code(400);
    exit('Invalid payload');
}

// 로그 기록
file_put_contents('webhook.log', date('Y-m-d H:i:s') . ' ' . json_encode($payload) . "\n", FILE_APPEND);

switch ($payload['event']) {
    case 'qr_payment_completed':
        // QR 결제 완료 처리
        $externalId = $payload['external_id'];  // 주문번호
        $customerId = $payload['customer_id'];  // 회원 식별자
        $amount     = $payload['paid_amount'];  // 결제 금액

        // TODO: 주문 완료 처리, 포인트 적립 등
        // updateOrder($externalId, 'paid', $amount);
        break;

    case 'redeem_gift_completed':
        // 가맹점이 환전 신청을 승인 → customer 에게 상품권 전달 완료
        $externalId = $payload['external_id'];
        $customerId = $payload['customer_id'];
        $amount     = $payload['amount'];
        // TODO: 포인트 적립 등
        // creditBalance($customerId, $amount);
        break;

    case 'redeem_cancelled':
        // 가맹점이 환전 신청을 취소
        $externalId = $payload['external_id'];
        // TODO: 주문 취소 처리
        break;

    case 'redeem_reverted':
        // 승인된 환전이 원복됨 (전달된 상품권 회수)
        $externalId      = $payload['external_id'];
        $recoveredCount  = $payload['recovered_count'];
        $failedCount     = $payload['failed_count'];
        // TODO: 포인트 회수 처리
        break;

    case 'redeem_failed':
        // customer_id 미매칭으로 환전 실패
        $externalId = $payload['external_id'];
        // TODO: 알림 / 재시도 안내
        break;
}

// 반드시 200 응답 (그 외 응답은 재시도 대상)
http_response_code(200);
echo json_encode(['received' => true]);

API 헬퍼 모듈

// nexva-qrpay.js
const BASE_URL = 'https://nexva.giftp2p.net/api/qr-pay';

class NexvaQrPay {
  constructor(token) {
    this.token = token;
  }

  /** QR 결제 생성 */
  async createPayment(amount, options = {}) {
    return this.request('POST', '/', { amount, ...options });
  }

  /** 결제 상태 조회 */
  async getStatus(paymentCode) {
    return this.request('GET', `/${paymentCode}/status`);
  }

  /** 결제 취소 */
  async cancel(paymentCode) {
    return this.request('POST', `/${paymentCode}/cancel`);
  }

  /** 환전 신청 (금액 기반, 자동 분할) */
  async redeem(amount, options = {}) {
    return this.request('POST', '/redeem', { amount, ...options });
  }

  /** 결제 목록 조회 */
  async listPayments(page = 1, status = null) {
    const params = new URLSearchParams({ page });
    if (status) params.set('status', status);
    return this.request('GET', `/my-payments?${params}`);
  }

  /** 내 상품권 조회 */
  async myCards() {
    return this.request('GET', '/my-cards');
  }

  async request(method, path, data = null) {
    const options = {
      method,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
    };
    if (data && method === 'POST') {
      options.body = JSON.stringify(data);
    }

    const res = await fetch(BASE_URL + path, options);
    const json = await res.json();
    json._http_code = res.status;
    return json;
  }
}

module.exports = NexvaQrPay;

사용 예시

const NexvaQrPay = require('./nexva-qrpay');
const api = new NexvaQrPay('YOUR_API_TOKEN');

(async () => {
  // 1. QR 결제 생성
  const payment = await api.createPayment(50000, {
    description: '주문 #1234',
    external_id: 'ORDER-1234',
    customer_id: 'CUST-5678',
  });
  console.log('결제코드:', payment.payment.payment_code);
  console.log('결제 URL:', payment.payment.payment_url);
  console.log('QR 이미지:', payment.payment.qr_image_url);

  // 2. 상태 폴링
  let status;
  do {
    await new Promise(r => setTimeout(r, 3000));
    status = await api.getStatus(payment.payment.payment_code);
  } while (status.status === 'pending');
  console.log('결제 상태:', status.status);

  // 3. 환전 신청
  const redeem = await api.redeem(150000, {
    external_id: 'REDEEM-001',
    customer_id: 'CUST-5678',
  });
  console.log('환전 요청번호:', redeem.request_no);
})();

콜백 수신 서버 (Express)

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/nexva', (req, res) => {
  const payload = req.body;
  console.log(`[${new Date().toISOString()}] ${payload.event}`, payload);

  switch (payload.event) {
    case 'qr_payment_completed':
      // QR 결제 완료
      const { external_id, customer_id, paid_amount } = payload;
      // TODO: 주문 완료 처리
      // await updateOrder(external_id, 'paid', paid_amount);
      break;

    case 'redeem_gift_completed':
      // 가맹점이 환전 신청을 승인 → customer 에게 상품권 전달 완료
      const { external_id: rid, customer_id: cid, amount } = payload;
      // TODO: 포인트 적립
      // await creditBalance(cid, amount);
      break;

    case 'redeem_cancelled':
      // 가맹점이 환전 신청을 취소
      // TODO: 주문 취소 처리
      break;

    case 'redeem_reverted':
      // 승인된 환전이 원복됨 (전달된 상품권 회수)
      const { recovered_count, failed_count } = payload;
      // TODO: 포인트 회수 처리
      break;

    case 'redeem_failed':
      // customer_id 미매칭으로 환전 실패
      // TODO: 알림 / 재시도 안내
      break;
  }

  // 반드시 200 응답
  res.json({ received: true });
});

app.listen(3000, () => console.log('Webhook server on :3000'));