페이업 | Developer Center

API

인증 토큰 발행

인증 토큰 발행 API를 호출하기 위해선 회원가입 후 가맹점 ID와 apiKey가 필요합니다.

URL	/auth/v1/accessToken
METHOD	POST
HEADER	application/json; charset=utf-8

필수 요청 파라미터

▪ merchantId / String / 20 - 가맹점 아이디
▪ apiKey / String / 32 - 가맹점 API서비스 오픈 시 전달 받은 apiKey


curl --request POST \
--url 'https://standard.payup.co.kr/auth/v1/accessToken' \
--header 'Content-Type: application/json' \
--data '{"merchantId":zlepang,"apiKey":"a4CWyWY5m89PNh7xJwhk1"}'

응답 파라미터

▪ status / String - 응답에 대한 상태
- 응답 성공 : SUCCESS
- 응답 실패 : ERROR
▪ messageCode / String - 응답에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ message / String - 응답에 대한 메시지
▪ data - 응답 데이터
▪ accessToken / String - 인증에 사용되는 토큰 값
▪ accessTokenValidityInSec - 인증에 사용되는 토큰의 유효기간(3600초)
▪ RefreshToken - 인증 토큰 만료 시 갱신에 사용되는 토큰 값
▪ refreshTokenValidityInSec - 인증 토큰 만료 시 갱신에 사용되는 토큰의 유효기간


{
    "status": "SUCCESS",
    "messageCode": "0000",
    "message": "성공",
    "data":{
        "accessToken": "Bearer-eyJhbGciOiJIUzUxMiJ9...",
        "accessTokenValidityInSec": 3600,
        "refreshToken": "Bearer-eyJhbGciOiJIUzUxMiJ9...",
        "refreshTokenValidityInSec": 2592000
    }
}

토큰 재발행

인증 토큰 만료 시 사용되며 인증 시 발급받은 갱신 토큰을 이용하여 인증 토큰을 갱신합니다.

URL	/auth/v1/refreshToken
METHOD	POST
HEADER	application/json; charset=utf-8

필수 요청 파라미터

▪ refreshToken / String / 256 - 토큰 인증 시 발급 받은 갱신 토큰 값


curl --request POST \
--url 'https://standard.payup.co.kr/auth/v1/refreshToken' \
--header 'Content-Type: application/json' \
--data '{"refreshToken":"Bearer-eyJhbGciOiJIUzUxMiJ9..."}'

응답 파라미터

▪ status / String - 응답에 대한 상태
- 응답 성공 : SUCCESS
- 응답 실패 : ERROR
▪ messageCode / String - 응답에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ message / String - 응답에 대한 메시지
▪ data - 응답 데이터
▪ accessToken / String - 인증에 사용되는 토큰 값
▪ accessTokenValidityInSec - 인증에 사용되는 토큰의 유효기간(3600초)
▪ refreshToken - 인증 토큰 만료 시 갱신에 사용되는 토큰 값
▪ refreshTokenValidityInSec - 인증 토큰 만료 시 갱신에 사용되는 토큰의 유효기간


{
    "status": "SUCCESS",
    "messageCode": "0000",
    "message": "성공",
    "data":{
        "accessToken": "Bearer-eyJhbGciOiJIUzUxMiJ9...",
        "accessTokenValidityInSec": 3600,
        "refreshToken": "Bearer-eyJhbGciOiJIUzUxMiJ9...",
        "refreshTokenValidityInSec": 2592000
    }
}

결제 승인

• 결제 인증이 완료된 후, 전달받은 페이업 거래번호를 이용하여 결제 승인 요청을 합니다.
1) 결제 승인 시, 데이터 검증을 위해 인증에 사용한 가맹점 주문번호와 금액이 필요합니다.
2) Autorization 헤더에 인증 토큰 값을 넣어야 합니다.

URL	/api/v1/payment
METHOD	POST
HEADER	application/json; charset=utf-8

필수 헤더 요청 파라미터

▪ Authorization / String - 가맹점 토큰 인증 통해 발급 받은 토큰 값

필수 요청 파라미터

▪ transactionId / String / 20 - 결제 인증 시 받은 페이업 거래 번호
▪ merchantId / String / 20 - 가맹점 ID 입니다.
▪ orderNumber / String / 128 - 가맹점에서 생성하는 주문 번호
▪ amount / String / 10 - 총 결제 금액


curl --request POST \
--url 'https://standard.payup.co.kr/api/v1/payment' \
--header 'Authorization: Bearer-eyJhbGciOiJIUzUxMiJ9...' \
--header 'Content-Type: application/json' \
--data '{"transactionId":"페이업 거래번호","merchatId":"가맹점ID","orderNumber":"가맹점 주문번호","amount":"총 결제금액"}'

응답 파라미터

▪ status / String - 응답에 대한 상태
- 응답 성공 : SUCCESS
- 응답 실패 : ERROR
▪ messageCode / String - 응답에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ message / String - 응답에 대한 메시지
▪ data - 응답 데이터
▪ responseCode / String - 결제 결과에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ responseMsg / String - 결제 결과에 대한 메시지
▪ transactionId / String - 거래 인증 시 받은 페이업 거래번호
▪ orderNumber / String - 가맹점에서 생성하는 주문번호
▪ authDatetime / String - 승인 일시
- YYYYMMDDHHMI24SS 형식
▪ authNumber / String - 승인 번호
▪ amount / String - 결제된 총 금액
▪ cardName / String - 결제카드 발급사명
▪ cardNo / String - 결제 한 카드 번호(마스킹 처리)
▪ quota / String - 결제 할부 개월
- 일시불 : 0
▪ noinf / String - 무이자 할부 적용 시 Y
▪ bypassValue / String - 주문 요청시 보낸 값

복합과세 응답 파라미터

▪ taxAmount / String - 과세금액
▪ vatAmount / String - 부가세
▪ freeAmount / String - 면세금액


{
    "status": "SUCCESS",
    "messageCode": "0000",
    "message": "성공",
    "data":{
        "transactionId": "20241217170823ST0013",
        "orderNumber": "20241217153147AB0005",
        "authDatetime": "20241217170849",
        "authNumber": "30067928",
        "amount": "1004",
        "issueCompanyName": "국민카드",
        "quota": "0",
        "noinf": "N",
        "bypassValue": "bypassValue",
              ⁝
    }
}

결제 취소

• 결제 승인 완료 후, 전달받은 페이업 거래번호를 이용하여 결제 취소 요청을 합니다.

URL	/api/v1/cancel
METHOD	POST
HEADER	application/json; charset=utf-8

필수 헤더 요청 파라미터

▪ Authorization / String - 가맹점 토큰 인증 통해 발급 받은 토큰 값

필수 요청 파라미터

▪ transactionId / String / 20 - 결제 인증 시 받은 페이업 거래 번호
▪ cancelReason / String / 256 - 취소 사유


curl --request POST \
--url 'https://standard.payup.co.kr/api/v1/cancel' \
--header 'Authorization: Bearer-eyJhbGciOiJIUzUxMiJ9...' \
--header 'Content-Type: application/json' \
--data '{"transactionId":"페이업 거래번호","cancelReason":"취소사유"}'

응답 파라미터

▪ status / String - 응답에 대한 상태
- 응답 성공 : SUCCESS
- 응답 실패 : ERROR
▪ messageCode / String - 응답에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ message / String - 응답에 대한 메시지
▪ data - 응답 데이터
▪ responseCode / String - 결제 결과에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ responseMsg / String - 결제 결과에 대한 메시지
▪ transactionId / String - 원 거래번호(=승인 거래번호)
▪ cancelDatetime / String - 결제 취소 일시 YYYYMMDDHHMI24SS


{
    "status": "SUCCESS",
    "messageCode": "0000",
    "message": "성공",
    "data":{
        "responseCode": "0000",
        "responseMsg": "결제취소 성공",
        "transactionId": "20240624091222ST0001",
        "cancelDatetime": "20240628122511"
    }
}

결제 부분 취소

• 결제 승인 완료 후, 전달받은 페이업 거래번호를 이용하여 결제 부분취소 요청을 합니다.

URL	/api/v1/partCancel
METHOD	POST
HEADER	application/json; charset=utf-8

필수 헤더 요청 파라미터

▪ Authorization / String - 가맹점 토큰 인증 통해 발급 받은 토큰 값

필수 요청 파라미터

▪ transactionId / String / 20 - 결제 인증 시 받은 페이업 거래 번호
▪ cancelAmount / String / 10 - 결제 부분 취소 금액
▪ cancelReason / String / 256 - 결제 부분 취소 금액


curl --request POST \
--url 'https://standard.payup.co.kr/api/v1/partCancel' \
--header 'Authorization: Bearer-eyJhbGciOiJIUzUxMiJ9...' \
--header 'Content-Type: application/json' \
--data '{"transactionId":"페이업 거래번호","cancelAmount":"결제 부분 취소 금액","cancelReason":"취소사유"}'

응답 파라미터

▪ status / String - 응답에 대한 상태
- 응답 성공 : SUCCESS
- 응답 실패 : ERROR
▪ messageCode / String - 응답에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ message / String - 응답에 대한 메시지
▪ data - 응답 데이터
▪ responseCode / String - 결제 결과에 대한 코드
- 성공 : 0000
* 그 외 실패
▪ responseMsg / String - 부분취소 결과에 대한 메시지
▪ transactionId / String - 원 거래번호(=승인거래번호)
▪ partTransactionId / String - 부분취소 거래번호
▪ cancelDatetime / String - 부분취소 일시
- YYYYMMDDHHMI24SS 형식
▪ cancelAmount / String - 부분취소 금액


{
    "status": "SUCCESS",
    "messageCode": "0000",
    "message": "성공",
    "data":{
        "responseCode": "0000",
        "responseMsg": "취소 성공",
        "transactionId": "20240624091222ST0001",
        "partTransactionId": "20240624091222ST0002",
        "cancelDatetime": "20240624091222",
        "cancelAmount": "1004"
    }
}