연동 흐름

등장하는 주체 #

• 판매자: 핀락에서 상품권을 산 핀락 고객. PIN을 보지 않고 양도 코드와 양도 비밀번호만 업체에 넘기며, 업체의 접수 요청을 핀락에서 승인합니다.
• 업체 서버: 핀락 API로 코드를 확인·접수하고, 결제를 마친 구매자에게 PIN 전달 링크를 만들어 줍니다. API 키는 이 서버에만 둡니다. 업체 서버는 PIN을 직접 받지 않습니다.
• 핀락: 코드가 한 곳에서만 접수되도록 막고, 판매자 승인을 받고, 비밀번호로 보호된 링크로 구매자에게 PIN을 보여 줍니다.
• 구매자: 업체 서비스에서 매물을 사고 업체에 결제하는 사람. 전달 링크를 열어 PIN을 확인합니다.

전체 순서 #

양도 한 건은 아래 순서로 진행됩니다. 업체가 직접 구현해야 하는 부분은 업체 서버가 보내거나 받는 단계입니다.

1. 1
   판매자 핀락 상품권 구매 · 양도 비밀번호 설정

   판매자가 핀락에서 상품권을 사고 입금을 마칩니다. 주문 화면에 PLX-XXXX-XXXX-XXXX 양도 코드가 보이고, 판매자는 숫자 6자리 양도 비밀번호를 한 번 정합니다. 판매자는 PIN을 보지 않습니다.

2. 2
   판매자 업체 서버 코드 · 비밀번호 전달

   판매자가 업체 매물 등록 화면에 양도 코드와 양도 비밀번호를 입력합니다.

3. 3
   업체 서버 핀락 코드 확인

   GET /v1/transfers/code/{code} 로 상태를 봅니다. 선점하지 않습니다. claimable 이 true 인지, items·faceTotal 이 매물과 같은지, passwordSet 이 true 인지 확인합니다.

4. 4
   업체 서버 핀락 접수 요청

   POST /v1/transfers/claim 에 code·password(·externalRef)를 보냅니다. 성공하면 status 가 pending_approval 이고, 응답의 transferId 를 저장합니다. 이 순간부터 다른 업체는 이 코드를 접수할 수 없습니다.

5. 5
   핀락 판매자 승인 요청 알림

   핀락이 판매자에게 업체의 등록 요청을 알립니다. 판매자가 승인 기한(approval.expiresAt) 안에 승인하지 않거나 거절하면 접수 요청은 자동으로 취소되고 코드는 다시 available 이 됩니다.

6. 6
   판매자 핀락 접수 승인

   판매자가 핀락 주문 화면에서 승인합니다. status 가 claimed_by_you 가 되고, 이때부터 7일(claimExpiresAt) 동안 업체가 코드를 독점합니다.

7. 7
   업체 서버 핀락 승인 확인 (조회)

   GET /v1/transfers/{transferId} 를 몇 초 간격으로 조회해 claimed_by_you 가 되면 매물을 공개합니다. 승인 기한이 지나 요청이 취소되면 조회가 404 가 됩니다.

8. 8
   구매자 업체 서버 구매 · 결제

   구매자가 업체 서비스에서 매물을 사고 업체에 결제합니다. 이 결제는 핀락을 거치지 않습니다.

9. 9
   업체 서버 핀락 PIN 전달 링크 만들기

   결제가 확인되면 POST /v1/transfers/{transferId}/share-link 에 sharePassword(6~20자)를 보내 링크를 만듭니다. share.url 은 이 응답에서만 받을 수 있습니다. 링크는 만든 시각부터 24시간 동안 열 수 있습니다.

10. 10
    업체 서버 구매자 링크 · 비밀번호 전달

    링크와 비밀번호를 구매자에게만, 서로 다른 경로로 보여 줍니다. 판매자에게는 절대 보여 주지 않습니다.

11. 11
    구매자 핀락 링크 열기 · PIN 확인

    구매자가 브라우저에서 링크를 열고 비밀번호를 입력하면 PIN이 한 번 표시됩니다. 양도 상태가 delivered 가 됩니다.

12. 12
    업체 서버 핀락 전달 확인 (조회)

    링크를 만든 거래는 GET /v1/transfers/{transferId} 를 30~60초 간격으로 조회해 delivered 인지 확인합니다.

13. 13
    업체 서버 판매자 판매자 정산

    전달이 확인되면 업체가 판매자에게 대금을 정산합니다. 정산은 핀락을 거치지 않습니다.

양도 상태 전이 #

업체 입장에서 정상적으로 끝나는 양도는 아래 순서로 status 가 바뀝니다. pending_approval 은 판매자가 핀락에서 승인하기를 기다리는 단계이고, 구매자가 PIN 전달 링크를 열면 delivered 가 됩니다.

그 밖에 아래 상태를 만날 수 있습니다.

상태별 의미와 업체 대응은 양도 상태에 정리되어 있습니다.

판매자 승인 기다리기 #

접수 응답의 approval.expiresAt 이 승인 기한입니다. 기다리는 시간은 핀락 운영 설정을 따릅니다(기본 30분). 그 사이 판매자에게 "핀락 주문 화면에서 등록을 승인해 주세요"라고 안내하세요.

• 승인되면 status 가 claimed_by_you 가 되고, claimExpiresAt(승인 시각부터 7일)까지 업체가 코드를 독점합니다.
• 기한까지 승인되지 않거나 판매자가 거절하면 접수 요청이 취소되어 조회가 404 가 됩니다. 매물 등록을 취소하세요.
• 승인 전에 링크를 만들려고 하면 409 APPROVAL_PENDING 입니다.

// 접수 직후 — 판매자 승인을 기다립니다
const res = await fetch(`https://api.pinlock.app/v1/transfers/${transferId}`, {
  headers: { Authorization: `Bearer ${process.env.PINLOCK_API_KEY}` }
});

if (res.status === 404) {
  // 승인 기한이 지났거나 판매자가 거절함 — 매물 등록을 취소하고 판매자에게 알립니다
  return cancelListing(transferId);
}
const { data: transfer } = await res.json();

if (transfer.status === "claimed_by_you") {
  // 판매자가 승인함 — 매물을 공개합니다. transfer.claimExpiresAt 까지 팔아야 합니다
  await publishListing(transferId, transfer.claimExpiresAt);
} else if (transfer.status === "pending_approval") {
  // 아직 대기 중 — 화면에 승인 기한(transfer.approval.expiresAt)을 보여 주고 잠시 뒤 다시 조회
}

전달 이후와 거래 취소 #

• 구매자가 링크를 열면 delivered 가 되고 deliveredAt 이 채워집니다. 이 시점 이후 판매자에게 정산하세요.
• 구매자 결제 취소 등으로 거래가 깨지면 POST /v1/transfers/{transferId}/release 로 선점을 풉니다. 열리지 않은 링크는 바로 폐기됩니다.
• claimExpiresAt 까지 전달되지 않으면 핀락이 선점을 자동으로 풉니다. 매물 노출 기간을 7일보다 짧게 잡으세요.

다음 단계 #