메인 콘텐츠로 건너뛰기

결제 거래

MarkdownChatGPTClaude

시작하기 전에​

API 요청은 액세스 토큰을 사용하여 인증됩니다. 유효한 액세스 토큰을 포함하지 않는 요청은 오류를 반환합니다. 인증에서 자세히 알아보세요.

기본 URL
  • UAT: https://transactions.transactional.uat.unico.app/api/public/v1
  • 프로덕션: https://transactions.transactional.unico.app/api/public/v1

거래 생성​

POST /credit/transaction — 새 거래를 생성합니다.

위험

더 나은 전환율을 보장하려면, 비대면 카드 검증 경험 이전에 작업을 종료시킬 수 있는 사전 인증이나 검증을 완료한 후에만 거래를 생성하세요.

위험

orderNumber 필드에는 전자상거래 시스템에서 해당 구매의 고유한 주문 번호를 입력해야 합니다 — 별도의 트랜잭션 ID를 사용하는 것은 올바르지 않습니다. 이를 재사용하면 전환율이 낮아질 수 있으며(주문 번호는 최종 사용자가 흐름을 완료하는 데 도움이 됩니다), 동일한 주문 번호, CPF, BIN, 마지막 4자리를 사용하는 경우 replicated transaction과 같은 API 오류가 발생할 수 있습니다.

헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
본문
{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "order-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/checkout/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 199.90,
  "mainContacts": [
    { "key": "phone", "value": "5543999999999" }
  ],
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}
필드타입필수설명
identityobject예사용자 식별 데이터입니다.
identity.keystring예사용자 식별 키의 유형입니다. 전환율이 더 높은 cpf를 권장합니다.
identity.valuestring예점이나 대시 없이 입력하는 사용자 식별 키 값입니다.
orderNumberstring예거래와 연결된 주문 번호입니다. 포털에서 색인으로 사용되며 귀사 시스템과 비대면 카드 검증 간의 외래 키 역할을 합니다.
companystring예Unico가 제공하는, 거래를 담당하는 회사의 ID입니다.
redirectUrlstring아니요거래 완료 후 사용자를 리디렉션할 URL입니다(웹의 경우 HTTPS URL, 네이티브 모바일 앱의 경우 URL 스킴).
cardobject예거래에 사용된 카드 정보입니다.
card.binDigitsstring예카드의 처음 8자리입니다.
card.lastDigitsstring예카드의 마지막 4자리입니다.
card.expirationDatestring아니요카드 만료일입니다.
card.namestring예카드 소유자의 이름입니다. 인코딩 문제를 피하기 위해 정확하게 전송하세요 — 이 데이터는 사용자 경험 및 커뮤니케이션에 사용됩니다.
valuenumber예총 구매 금액입니다.
mainContactsarray아니요비대면 카드 검증이 알림을 담당하는 경우 사용자에게 알리기 위해 사용되는 주요 연락처(이메일 및/또는 전화번호) 목록입니다.
fallbackContactsarray아니요주요 연락처로의 알림 시도가 실패할 경우 트리거되는 대체 연락처 목록입니다.
additionalInfoobject아니요이 거래에 대해 Silent Verification을 활성화하려면 externalUserID와 함께 이 객체를 전송하세요.
additionalInfo.externalUserIDstring예 (additionalInfo가 전송된 경우)디바이스 메타데이터를 수집할 때 SDK의 externalUserId를 통해 구성한 것과 동일한 식별자입니다. 무음 검증을 트리거하는 데 필요합니다 — 이 값이 없으면 거래는 정상적으로 생성되지만 항상 표준 시각적 흐름을 따릅니다.
200 OK
{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-07-22T15:30:00Z"
}
필드설명
id생성된 거래의 ID입니다.
status현재 거래 상태입니다.
link거래와 관련된 링크입니다.
token비대면 카드 검증 웹 SDK를 초기화하는 데 필요한 파라미터가 포함된 서명된 토큰입니다.
expiresAt거래 만료 일시입니다, ISO 8601(UTC) 형식.
경고

검증 결과 생체 인식 캡처가 필요하지 않다고 판단되면, 응답의 상태가 다르며 캡처 링크가 생성되지 않습니다.

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

이는 기능에 따라 체크아웃용 Pre 또는 Super Pre 모듈을 사용하는 경우에 발생합니다.

참고

additionalInfo.externalUserID가 전송되고 거래가 백그라운드에서 자동으로 승인된 경우, 응답에서도 캡처 링크가 생략됩니다:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

SDK 설정 및 타이밍 요구 사항을 포함한 전체 흐름은 Silent Verification을 참조하세요.

오류 응답에 대해서는 오류 — 거래 생성을 참조하세요.

거래 상태 조회​

GET /credit/transactions/{transaction_id} — 특정 거래의 현재 상태를 확인합니다.

헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
200 OK
{
  "status": "processing"
}
필드설명
status거래의 현재 상태입니다.

가능한 모든 상태는 열거형을 참조하세요. 성능을 최적화하려면 이 엔드포인트를 폴링하는 대신 웹훅을 구현하세요.

오류 응답에 대해서는 오류 — 거래 상태 조회를 참조하세요.

거래 증빙 세트 조회​

GET /credit/transactions/{transaction_id}/probative — 특정 거래의 증빙 세트를 조회합니다.

경고

증빙 세트는 승인된(approved) 거래에 대해서만 생성할 수 있습니다.

위험

증빙 세트에 대해 반환되는 링크는 발급 후 5분 동안만 유효합니다 — 저장하지 말고 즉시 증빙 세트를 다운로드하는 데 사용하세요.

헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
200 OK
{
  "link": "https://unico.io/probative.pdf"
}
필드설명
link증빙 파일의 URL입니다.

오류 응답에 대해서는 오류 — 거래 증빙 세트 조회를 참조하세요.

거래 알림 재전송​

POST /credit/transactions/{transaction_id}/notify — 특정 거래에 대해 이메일 및/또는 전화로 알림을 재전송합니다.

참고

API로 구현하지 않고도 포털을 통해 알림 재전송을 구성할 수 있습니다. 가능한 방법에 대해서는 프로젝트 담당자에게 문의하세요.

헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
본문
{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}
필드타입필수설명
phonestring예알림을 보낼 전화번호입니다.
emailstring예알림을 보낼 이메일 주소입니다.
200 OK
{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}
필드설명
id생성된 알림의 고유 ID입니다.
link알림에 대해 생성된 링크입니다.

오류 응답에 대해서는 오류 — 거래 알림 재전송을 참조하세요.

마지막 업데이트 에