개발자센터
V1
V2
API & SDK
릴리즈 노트 기술 블로그

API 연동

웰컴페이먼츠 API 연동 방법을 안내합니다.

지원 기능

  • 가상 계좌 발급, 회수
  • 현금영수증 발급, 취소, 조회
  • 외부 결제건 현금영수증 발급, 취소, 조회
  • 빌링키 발급
  • 예약결제
  • 에스크로 등록, 조회
  • 결제건 환불

추가된 파라미터

pay_method 파라미터 추가

  • 포트원을 통하지 않은 외부 결제건에 대한 현금영수증 발급시 필수로 요구되는 파라미터로 trans(계좌이체), vbank(가상계좌) 만 지정 가능합니다.

  • 사용가능한 API

    • 현금영수증 발급(외부) API

products 파라미터 추가

에스크로 배송 정보 등록 및 수정 시 상품들에 대한 정보를 입력하는 파라미터로 필수로 요구됩니다.

{
  "products": {
    "id": "상품 고유 아이디 (required)",
    "name": "상품 이름",
    "code": "상품 고유 코드",
    "amount": "상품 단위 가격 (required)",
    "currency": "상품 단위 가격 화폐 (default: KRW)",
    "quantity": "상품 수량 (defatul: 1)",
    "tag": "상품의 카테고리"
  }
}

corp_reg_no 파라미터 추가

외부 결제건의 현금영수증 발급 시, 사업자 등록번호를 입력하는 파라미터로 필수로 요구됩니다.

  • 계좌이체 : trans
  • 가상계좌 : vbank

API 별 상세 설명

빌링키 결제

  • 요청 URL: https://api.iamport.kr/subscribe/again

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • customer_uid
    • merchant_uid
    • amount
    • buyer_name

  • 주의사항

    • tax_free 파라미터는 부가세업체정함 설정 고객사에 한해 사용 가능합니다.

    • vat_amount 파라미터는 부가세업체정함 설정업체에 한해 사용 가능하며 전체금액의 10%이하로 설정 해야합니다. vat_amount 가 총 상품가격의 10% 초과할 경우는 결제가 거절됩니다.

키인 결제

  • 요청 URL: https://api.iamport.kr/subscribe/onetime

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • merchant_uid
    • card_number
    • expiry
    • buyer_name

  • 주의사항

    • tax_free 파라미터는 부가세업체정함 설정 고객사에 한해 사용 가능합니다.

    • vat_amount 파라미터는 부가세업체정함 설정업체에 한해 사용 가능하며 전체금액의 10%이하로 설정 해야합니다. vat_amount 가 총 상품가격의 10% 초과할 경우는 결제가 거절됩니다.

예약 결제

  • 요청 URL: https://api.iamport.kr/subscribe/schedule

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • schedules.merchant_uid
    • schedules.amount
    • schedules.buyer_name

  • 주의 사항

    • tax_free 파라미터는 부가세업체정함 설정 고객사에 한해 사용 가능합니다.

    • vat_amount 파라미터는 부가세업체정함 설정업체에 한해 사용 가능하며 전체금액의 10%이하로 설정 해야합니다. vat_amount 가 총 상품가격의 10% 초과할 경우는 결제가 거절됩니다.

가상계좌 발급

  • 요청 URL: https://api.iamport.kr/vbanks

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • merchant_uid
    • amount
    • vbank_code
    • vbank_due
    • buyer_name

  • 주의 사항

    • vbank_holder 경우 적용되지 않고 고객사명이 사용됩니다.

    • 계좌 발급 받거나 환불금액을 입금받을 수 있는 은행 목록과 코드는 https://api.iamport.kr/#vbank_codes에서 확인 가능합니다.

에스크로 배송 정보 등록

  • 요청 URL: https://api.iamport.kr/escrows/logis/{imp_uid}

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • imp_uid
    • sender.name
    • sender.tel
    • sender.postcode
    • sender.formed_address
    • receiver.name
    • receiver.tel
    • receiver.postcode
    • receiver.formed_address
    • logis.company
    • logis.invoice
    • logis.sent_at
    • products.id
    • products.name
    • products.amount

  • 주의 사항

    • welcome는 배송수정시, 지번주소/도로명주소와 상세주소를 구분하여 받고있기 때문에, 발신자의 주소와 수신자의 주소 정보를 기존의 sender.addr와 receiver.addr 파라미터 대신 새로 추가된 파라미터 formed_address의 address_line_1(지번주소 또는 도로명주소)와 address_line_2(상제주소)에 설정해야합니다.

에스크로 배송 정보 수정

  • 요청 URL: https://api.iamport.kr/escrows/logis/{imp_uid}

    • 요청 메소드: PUT

  • 웰컴페이먼츠 필수 파라미터

    • imp_uid
    • logis.company
    • logis.invoice
    • logis.sent_at
    • products.id
    • products.name
    • products.amount

  • 주의 사항

    • welcome는 배송 정보 수정시, 지번주소/도로명주소와 상세주소를 구분하여 받고있기 때문에, 발신자의 주소와 수신자의 주소 정보를 기존의 sender.addr와 receiver.addr 파라미터 대신 새로 추가된 파라미터 formed_address의 address_line_1(지번주소 또는 도로명주소)와 address_line_2(상제주소)에 설정해야합니다.

현금영수증 발급 (아임포트 결제건)

  • 요청 URL: https://api.iamport.kr/receipts/{imp_uid}

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • imp_uid
    • identifier
    • type
    • buyer_tel
    • corp_reg_no

현금영수증 발급 (외부 결제건)

  • 요청 URL: https://api.iamport.kr/receipts/external/{imp_uid}

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • merchant_uid
    • name
    • amount
    • identifier
    • type
    • buyer_tel
    • corp_reg_no
    • pay_method

결제 취소

  • 요청 URL: https://api.iamport.kr/payments/cancel

  • 요청 메소드: POST

  • 웰컴페이먼츠 필수 파라미터

    • imp_uid
    • refund_holder (가상계좌, 계좌이체 거래건)
    • refund_account (가상계좌, 계좌이체 거래건)
    • refund_bank (가상계좌, 계좌이체 거래건)
    • refund_tel (가상계좌, 계좌이체 거래건)

  • 주의 사항

    • 부분 취소는 지불수단 별로 부분환불 사용 서비스 신청 고객사에 한 해 지원 가능합니다. 부분 환불 사용 서비스 사용 신청 및 사용 여부 문의는 웰컴페이먼츠 계약 담당자에게 확인해주시기를 바랍니다.

    • tax_free 파라미터는 부가세업체정함 설정 고객사에 한 해 결제 시 면세 금액을 지정했던 경우 필수 입력 바랍니다.

    • vat_amount 파라미터는 부가세업체정함 설정 고객사에 한 해 결제 시 부가세를 지정했던 경우 필수 입력 바랍니다.