양도 코드 연동 가이드

핀락 연동으로 할 수 있는 일 #

핀락 고객이 상품권을 사면 주문 화면에 PLX-XXXX-XXXX-XXXX 형태의 양도 코드가 생깁니다. 이 고객(이하 판매자)은 PIN을 보지 않은 채 양도 코드와 직접 정한 양도 비밀번호(숫자 6자리)만 업체(중고 거래·재판매 마켓 등)에 넘깁니다.

업체 서버는 API로 코드를 확인하고 접수를 요청합니다. 판매자가 핀락에서 접수를 승인하면 그 코드는 업체가 독점하고, 업체 서비스에서 결제를 마친 구매자에게만 PIN 전달 링크를 만들어 보여 줍니다. 구매자가 링크를 열어 PIN을 확인하면 거래가 끝나고, 업체는 판매자에게 정산합니다.

• 판매자는 PIN을 보지 않습니다: PIN을 먼저 확인하고 되파는 일을 막습니다.
• 중복 등록 방지: 한 코드는 한 곳에서만 접수됩니다. 동시에 접수해도 하나만 성공합니다.
• 판매자 승인: 접수 요청은 판매자가 핀락에서 정해진 시간 안에 승인해야 확정되고, 승인하지 않으면 자동으로 취소됩니다.
• 판매자 취소 방지: 접수 중에는 판매자가 주문을 취소·환불할 수 없고, 코드도 바꿀 수 없습니다.
• PIN 전달: 업체가 만드는 전달 링크 + 비밀번호. 만든 시각부터 24시간 동안, 한 번만 열 수 있습니다. 업체 서버는 PIN을 받지 않습니다.
• 7일 자동 해제: 접수 후 7일 안에 전달되지 않으면 선점이 자동으로 풀립니다.

기본 주소와 요청 형식 #

모든 API는 아래 주소 아래에 있고, JSON으로 주고받습니다. 인증은 Authorization: Bearer <API 키> 헤더로 합니다.

curl https://api.pinlock.app/v1/me \
  -H "Authorization: Bearer pl_test_여기에_테스트_키"

const res = await fetch("https://api.pinlock.app/v1/me", {
  headers: { Authorization: `Bearer ${process.env.PINLOCK_API_KEY}` }
});
const body = await res.json();
console.log(body.data); // { partnerId, partnerName, mode: "test", serverTime }

import os, requests

res = requests.get(
    "https://api.pinlock.app/v1/me",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
    timeout=10,
)
print(res.json()["data"])

응답은 항상 같은 모양입니다. 성공이면 success: true 와 data, 실패면 success: false 와 code·error 가 옵니다.

{
  "success": true,
  "data": { "partnerId": "ptn_…", "partnerName": "예시상사", "mode": "test", "serverTime": "2026-09-23T09:00:00.000Z" }
}

{
  "success": false,
  "code": "UNAUTHORIZED",
  "error": "유효하지 않거나 폐기된 API 키입니다."
}

사용하는 API #

• GET /v1/me — 키가 어느 업체·모드(테스트/운영)인지 확인
• GET /v1/transfers/code/{code} — 코드 상태 확인 (선점하지 않음)
• POST /v1/transfers/claim — 코드 + 양도 비밀번호로 접수 요청 (판매자 승인 대기)
• GET /v1/transfers/{transferId} — 승인·전달 상태 조회
• POST /v1/transfers/{transferId}/share-link — 구매자용 PIN 전달 링크 만들기
• POST /v1/transfers/{transferId}/release — 거래가 깨졌을 때 선점 해제

테스트 키로는 POST /v1/test/transfers(테스트 양도 코드 만들기)와 POST /v1/test/transfers/{transferId}/approve(판매자 승인 처리)를 추가로 쓸 수 있습니다.

어디서부터 시작할까요? #