마카롱 페이먼츠 API

📋 개요

마카롱 페이먼츠는 전자상거래 사이트를 위한 안전하고 간편한 결제 시스템입니다.

🔐 인증

{
  "siteId": "your-site-id",
  "siteSecret": "your-site-secret"
}

💻 코드 예제

// 토큰 발급
async function getSiteToken(siteId, siteSecret) {
  const response = await fetch('/v1/site-auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ siteId, siteSecret })
  });
  return (await response.json()).data.accessToken;
}

// 입금 요청 생성
async function createDepositRequest(token, requestData) {
  const response = await fetch('/v1/deposit-requests', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(requestData)
  });
  return await response.json();
}

📡 웹훅 가이드

{
  "type": "MATCH_NOTIFICATION",
  "matchId": "match_xxx",
  "amount": 10000,
  "siteName": "사이트명",
  "depositRequest": {
    "depositRequestId": "dep_xxx",
    "amount": 10000,
    "siteUserId": "user123"
  },
  "withdrawalRequest": {
    "withdrawalRequestId": "with_xxx",
    "amount": 10000,
    "kakaoPayUrl": "https://...",
    "siteUserId": "user456"
  },
  "matchedAt": "2025-01-22T10:00:00Z"
}

{
  "type": "VERIFICATION_COMPLETED",
  "matchId": "match_xxx",
  "amount": 10000,
  "ocrExtractedAmount": 10000,
  "screenshotUrl": "https://...",
  "verifiedAt": "2025-01-22T10:05:00Z",
  "siteName": "사이트명",
  "depositRequest": { ... },
  "withdrawalRequest": { ... }
}

{
  "type": "MATCH_CANCELLED_BY_TIMEOUT",
  "matchId": "match_xxx",
  "amount": 10000,
  "reason": "검증 타임아웃 (10분 경과) - 입금 미완료",
  "cancelledBy": "timeout",
  "cancelledAt": "2025-01-22T10:10:00Z",
  "depositRequest": { ... },
  "withdrawalRequest": { ... }
}

{
  "type": "DEPOSIT_REQUEST_CANCELLED",
  "matchId": "match_xxx",
  "amount": 10000,
  "reason": "입금신청 취소: 사용자 요청",
  "cancelledBy": "deposit_cancelled",
  "cancelledAt": "2025-01-22T10:15:00Z",
  "depositRequest": { ... },
  "withdrawalRequest": { ... }
}

{
  "type": "WITHDRAWAL_REQUEST_CANCELLED",
  "matchId": "match_xxx",
  "amount": 10000,
  "reason": "출금신청 취소: 관리자 판단",
  "cancelledBy": "withdrawal_cancelled",
  "cancelledAt": "2025-01-22T10:20:00Z",
  "depositRequest": { ... },
  "withdrawalRequest": { ... }
}

{
  "type": "MATCH_CANCELLED_BY_ADMIN",
  "matchId": "match_xxx",
  "amount": 10000,
  "reason": "매칭 취소: 관리자 판단",
  "cancelledBy": "admin",
  "cancelledAt": "2025-01-22T10:25:00Z",
  "depositRequest": { ... },
  "withdrawalRequest": { ... }
}

웹훅 수신 예제

app.post('/webhook/macaron-payments', (req, res) => {
  const payload = req.body;
  
  console.log('웹훅 수신:', payload);
  
  switch (payload.type) {
    case 'MATCH_NOTIFICATION':
      // 매칭 완료 (2분 지연, 양쪽 발송)
      console.log(`매칭 완료: ${payload.matchId}, 금액: ${payload.amount}`);
      // 사용자에게 매칭 완료 알림 발송
      break;
    
    case 'VERIFICATION_COMPLETED':
      // 검증 완료 (즉시, 양쪽 발송)
      console.log(`검증 완료: ${payload.matchId}`);
      console.log(`OCR 금액: ${payload.ocrExtractedAmount}`);
      // 최종 완료 처리 및 사용자 알림
      break;
    
    case 'MATCH_CANCELLED_BY_TIMEOUT':
      // 타임아웃 취소 (즉시, 입금자만)
      console.log(`타임아웃 취소: ${payload.matchId}`);
      console.log(`사유: ${payload.reason}`);
      // 입금자에게 취소 알림 발송
      break;
    
    case 'DEPOSIT_REQUEST_CANCELLED':
      // 입금신청 취소 (즉시, 입금자만)
      console.log(`입금신청 취소: ${payload.matchId}`);
      console.log(`사유: ${payload.reason}`);
      // 입금자에게 취소 알림 발송
      break;
    
    case 'WITHDRAWAL_REQUEST_CANCELLED':
      // 출금신청 취소 (즉시, 출금자만)
      console.log(`출금신청 취소: ${payload.matchId}`);
      console.log(`사유: ${payload.reason}`);
      // 출금자에게 취소 알림 발송
      break;
    
    case 'MATCH_CANCELLED_BY_ADMIN':
      // 관리자 직접 취소 (즉시, 양쪽 발송)
      console.log(`관리자 취소: ${payload.matchId}`);
      console.log(`사유: ${payload.reason}`);
      // 양쪽 사용자에게 취소 알림 발송
      break;
    
    default:
      console.log('알 수 없는 이벤트:', payload.type);
  }
  
  res.status(200).json({ success: true });
});

📸 OCR 스크린샷 검증

매칭 완료 후 사용자가 업로드한 송금 완료 스크린샷을 OCR로 자동 검증합니다. OCR 기술을 사용하여 금액과 완료 메시지를 확인합니다.

// FormData를 사용한 multipart/form-data 전송
const formData = new FormData();
formData.append('matchLogId', 'cm5abc...');
formData.append('screenshot', imageFile); // File 객체

const response = await fetch('/v1/match-logs/verify-screenshot', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${siteToken}`
  },
  body: formData
});

{
  "message": "OCR 검증이 완료되었습니다",
  "data": {
    "matchLogId": "cm5abc...",
    "status": "VERIFICATION_COMPLETED",
    "ocrExtractedAmount": 50000,
    "verifiedAt": "2025-10-11T09:45:00.000Z",
    "hasCompletionMessage": true
  }
}

{
  "message": "금액 불일치 (추출: 45000원, 실제: 50000원)"
}

{
  "message": "\"송금을 완료했어요\" 등의 완료 메시지가 스크린샷에 포함되어야 합니다"
}

⭐ 모범 사례