시작하기

개발자 센터

페이액션은 무통장입금 결제가 필요한 모든곳에 연동하여 사용하실 수 있는 커머스/뱅킹 SaaS입니다. 이용하실 수 있는 서비스는 아래와 같습니다.

  • 실시간 결제확인을 위한 1초 자동 입금확인, 결제내역 현금영수증 자동발행/취소
  • 계좌 실시간 거래데이터 수신을 위한 1초 입출금 데이터 수신
  • 페이액션의 모든 API는 REST API로 제공되며, HTTP 요청을 보낼 수 있는 환경이라면 OS나 DB에 관계없이 사용할 수 있습니다.
  • API는 SSL 보안이 적용된 HTTPS 프로토콜을 통해서만 호출할 수 있으며, 요청 결과는 JSON 형식으로 응답됩니다.
  • 요청과 응답에 포함되는 주요 데이터는 전송 구간에서 암호화됩니다.
  • API 인증에는 x-api-key와 x-mall-id가 사용되며, 민감한 키가 외부에 노출된 경우 즉시 재발급해 주세요.
  • API 요청이 서버 처리 단계에서 거절되는 경우 HTTP 상태 코드와 함께 오류코드 및 메시지를 반환합니다.

어떤 연동을 하시나요?

1초 자동 입금확인

주문 정보를 먼저 등록하고, 실제 입금이 들어오면 페이액션이 주문과 입금을 매칭한 뒤 결과를 웹훅으로 전달합니다.POST /orderPOST /orders/{order_number}/cancelPOST /order-excludePOST /cashbillsPOST /cashbills/{cashbill_id}/cancelWebhook

입출금 데이터 수신

주문 등록 없이 계좌의 입금/출금 이벤트를 고객사 서버로 수신합니다. 입출금 데이터 수신은 웹훅 연동 흐름 안에서 처리합니다.Webhook

서비스 연동 순서

  1. 1

    상점등록

    [설정] 메뉴에서 상점정보를 입력합니다.

  2. 2

    계좌등록

    계좌등록 및 해당은행SMS통지서비스 등 가이드에 따라 신청합니다.

  3. 3

    API정보 입력

    [API] 메뉴에서 API키를 생성하고 웹훅URL을 입력합니다.

  4. 4

    서비스 개발 및 연동

    아래 API 레퍼런스를 참고하여 서비스를 개발 및 연동합니다.

API

요청 방식과 헤더 설정

Base URL
https://api.payaction.app
Authentication
x-api-key + x-mall-id
Protocol
HTTPS / JSON

헤더 설정

HeaderValueNote
Content-Typeapplication/json-
x-api-keyyour-api-key[대시보드] > [API]의 ‘API키’ 에서 확인하실 수 있습니다.
x-mall-idyour-mall-id[대시보드] > [API]의 ‘상점ID’에서 확인하실 수 있습니다.

API 유형

입금 자동확인 API

주문을 제출하고, 입금 발생 시 매칭되는 경우 웹훅으로 받아 처리하는 API 유형입니다. 커머스나 서비스 등 발생되는 주문에 대응되는 입금발생건만 입금확인처리하는 경우에 적합합니다.

입금 자동확인 API 처리 흐름

입출금 데이터수신 API

주문제출 없이, 해당 계좌의 입금 및 출금 발생 시 웹훅으로 받을 수 있는 API 유형입니다. 페이액션에 주문입력 없이 입출금 내역 수신이 필요한 경우에 적합합니다.

입출금 데이터수신 API 처리 흐름

API 레퍼런스

MethodNamePath
POST주문입금 자동확인 API/order
POST주문취소입금 자동확인 API/orders/{order_number}/cancel
POST주문-매칭제외DEPRECATED입금 자동확인 API/order-exclude
POST현금영수증 발행현금영수증 API/cashbills
POST현금영수증 취소현금영수증 API/cashbills/{cashbill_id}/cancel
POST현금영수증-발행취소DEPRECATED입금 자동확인 API/cashbill-cancel
POST입금 자동확인 API

주문

API Endpoint

https://api.payaction.app/order

Curl

curl -X POST "https://api.payaction.app/order" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "order_number": "1234567890",
    "order_amount": 19000,
    "tax_free_amount": 7000,
    "order_date": "2023-07-26T11:31:00+09:00",
    "auto_cancel_date": "2023-07-27T11:31:00+09:00",
    "billing_name": "홍길동",
    "orderer_name": "홍길동",
    "orderer_phone_number": "01012345678",
    "orderer_email": "hong@gildong.kr",
    "trade_usage": "소득공제용",
    "identity_number": "01012345678"
}'

Request Body

{
    "order_number": "1234567890",
    "order_amount": 19000,
    "tax_free_amount": 7000,
    "order_date": "2023-07-26T11:31:00+09:00",
    "auto_cancel_date": "2023-07-27T11:31:00+09:00",
    "billing_name": "홍길동",
    "orderer_name": "홍길동",
    "orderer_phone_number": "01012345678",
    "orderer_email": "hong@gildong.kr",
    "trade_usage" : "소득공제용",
    "identity_number" : "01012345678"
}
FieldDescriptionRequired
order_number주문번호22자 이하 권장, 초과시 알림톡 발송불가Yes
order_amount주문금액.Yes
tax_free_amount면세금액.0이면 전액 과세, 주문금액과 같으면 전액 면세, 그 사이는 과세·면세 혼합주문No
order_date주문일시Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00Yes
auto_cancel_date자동취소일시Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00No
billing_name입금자명자동매칭시 매칭여부 판단 항목Yes
orderer_name주문자명Yes
orderer_phone_number주문자 전화번호하이픈(-) 및 국가코드(+82)를 미포함 전송예시 : 01012345678No
orderer_email주문자 이메일No
trade_usage현금영수증-거래구분 (택1)소득공제용지출증빙용No
identity_number현금영수증-식별번호숫자만 입력소득공제용 : 휴대폰번호 입력지출증빙용 : 사업자번호 입력No

같은 상점에서 같은 order_number로 다시 요청하면 기존 주문을 현재 요청값으로 변경합니다.

주문자에게 결제완료(입금확인) 알림 메시지 발송을 원하는 경우에는 주문자 전화번호 및 주문자 이메일 필드를 포함하여 요청해야 합니다.알림톡 발송 : orderer_phone_number 필드 포함이메일 발송 : orderer_email 필드 포함

현금영수증 자동발행을 원하는 경우에는 현금영수증-거래구분 및 현금영수증-식별번호 필드를 포함하여 요청해야 합니다.

현금영수증을 면세 또는 과세·면세 혼합으로 발행을 원하는 경우에는 tax_free_amount(면세금액) 필드를 포함하여 요청해야 합니다.

유효하지 않은 API 요청을 지속적으로 과다 제출하는 경우 서비스 이용이 제한될 수 있습니다.ex) 주문자 전화번호에 문자값 입력 등

Response Body

{
    "status": "success",
    "response": {}
}

Error Response

필수값 누락 예시:
{
    "status": "error",
    "response": {
        "message": "누락된 필드가 존재합니다."
    }
}
POST입금 자동확인 API

주문취소

API Endpoint

https://api.payaction.app/orders/{order_number}/cancel

Curl · 전체취소

curl -X POST "https://api.payaction.app/orders/1234567890/cancel" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id"

Curl · 부분취소

curl -X POST "https://api.payaction.app/orders/1234567890/cancel" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "request_id": "cancel-20260807-001",
    "cancel_amount": 5000,
    "tax_free_amount": 0
}'
FieldDescriptionRequired
order_number취소할 주문번호Yes
request_id부분취소 요청을 구분하는 고유 식별값부분취소 시 필수, 고객사에서 생성하여 제출No
cancel_amount이번에 취소할 총금액부분취소 시 필수 · 생략하면 남은 금액 전체취소No
tax_free_amount이번 취소금액 중 면세금액전액 과세주문인 경우 0으로 입력 또는 생략No

현금영수증이 없으면 cashbill은 생략됩니다.

Response Body · 전체취소 성공

{
    "status": "success",
    "order": {
        "order_number": "1234567890",
        "cancellation_status": "cancelled",
        "cancel_amount": 19000,
        "cumulative_cancelled_amount": 19000,
        "remaining_amount": 0
    },
    "cashbill": {
        "id": 12345,
        "status": "cancelled",
        "cancel_amount": 19000,
        "cumulative_cancelled_amount": 19000,
        "remaining_amount": 0
    }
}

Response Body · 부분취소 성공

{
    "status": "success",
    "order": {
        "order_number": "1234567890",
        "cancellation_status": "partially_cancelled",
        "cancel_amount": 5000,
        "cumulative_cancelled_amount": 5000,
        "remaining_amount": 14000
    },
    "cashbill": {
        "id": 12345,
        "status": "partially_cancelled",
        "cancel_amount": 5000,
        "cumulative_cancelled_amount": 5000,
        "remaining_amount": 14000
    }
}

Response Body · 연결된 현금영수증 없음

{
    "status": "success",
    "order": {
        "order_number": "1234567890",
        "cancellation_status": "cancelled",
        "cancel_amount": 19000,
        "cumulative_cancelled_amount": 19000,
        "remaining_amount": 0
    }
}

Response Body · 주문취소 성공 · 현금영수증 최종 실패

{
    "status": "success",
    "order": {
        "order_number": "1234567890",
        "cancellation_status": "partially_cancelled",
        "cancel_amount": 5000,
        "cumulative_cancelled_amount": 5000,
        "remaining_amount": 14000
    },
    "cashbill": {
        "id": 12345,
        "status": "cancel_failed"
    },
    "error": {
        "code": "<현금영수증 실패 코드>",
        "message": "<현금영수증 실패 메시지>"
    }
}
POST입금 자동확인 APIDEPRECATED

주문-매칭제외

API Endpoint

https://api.payaction.app/order-exclude

Curl

curl -X POST "https://api.payaction.app/order-exclude" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "order_number": "1234567890"
}'

Request Body

{
    "order_number": "1234567890"
}
FieldDescriptionRequired
order_number주문번호Yes

DEPRECATED: 이 API는 종료 예정입니다.

주문 정보를 고치려면 같은 order_number로 POST /order를 다시 요청해 주세요. 매칭제외를 먼저 호출하지 않아도 됩니다.

주문을 취소하려면 POST /orders/{order_number}/cancel을 사용해 주세요.

Response Body

{
    "status": "success",
    "response": {}
}

Error Response

{
    "status": "error",
    "response": {
        "message": "누락된 필드가 존재합니다."
    }
}
POST현금영수증 API

현금영수증 발행

API Endpoint

https://api.payaction.app/cashbills

발행 방식 안내

- 주문 기반 발행 : 주문제출시 전달한 금액과 현금영수증 발행 정보를 사용한 발행

- 독립발행 : 주문제출과 관계없이 현금영수증 발행 요청시 입력한 정보로 발행

두 발행 방식 모두 페이액션 사이트에서 화면을 통한 수동발행과 매칭시 자동발행 토글 설정(대시보드 > 설정)과 관계없이 사용할 수 있습니다. 다만 프리미어 이상 플랜과 정상 등록된 현금영수증 발행정보가 있어야 합니다.

두 발행 방식 모두 발행 응답의 cashbill.id를 사용하여 주문 기반 또는 독립발행 현금영수증을 동일하게 전체·부분취소할 수 있습니다.

Curl · 주문 기반 발행

curl -X POST "https://api.payaction.app/cashbills" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "order_number": "1234567890"
}'

Curl · 독립발행

curl -X POST "https://api.payaction.app/cashbills" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "request_id": "CASHBILL-20260807-001",
    "customer_name": "홍길동",
    "total_amount": 19000,
    "taxation_type": "과세",
    "trade_usage": "소득공제용",
    "identity_number": "01012345678",
    "transaction_type": "일반"
}'

Request Parameters · 주문 기반 발행

FieldDescriptionRequired
order_number현금영수증을 발행할 주문번호Yes

Request Parameters · 독립발행

FieldDescriptionRequired
request_id독립발행 요청을 구분하는 고유 식별값고객사에서 생성하여 제출Yes
customer_name구매자명Yes
total_amount거래금액Yes
taxation_type과세형태"과세" 또는 "면세"Yes
trade_usage거래구분"소득공제용" 또는 "지출증빙용"Yes
identity_number식별번호소득공제용: 휴대폰번호 · 지출증빙용: 사업자번호Yes
transaction_type거래유형"일반", "도서공연", "대중교통"Yes

Response Body

{
    "status": "success",
    "cashbill": {
        "id": 12345,
        "status": "issued"
    }
}

Error Response

{
    "status": "error",
    "cashbill": {
        "id": 12345,
        "status": "issue_failed"
    },
    "error": {
        "code": "-99999999",
        "message": "팝빌 오류 메시지"
    }
}
POST현금영수증 API

현금영수증 취소

API Endpoint

https://api.payaction.app/cashbills/{cashbill_id}/cancel

Curl · 전체취소

curl -X POST "https://api.payaction.app/cashbills/12345/cancel" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id"

Curl · 부분취소

curl -X POST "https://api.payaction.app/cashbills/12345/cancel" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "request_id": "refund-20260802-001",
    "cancel_amount": 5000,
    "tax_free_amount": 0
}'
FieldDescriptionRequired
cashbill_id발행 응답 또는 매칭완료 웹훅에서 받은 cashbill.id 경로 변수Yes
request_id부분취소 요청을 구분하는 고유 식별값부분취소 시 필수, 고객사에서 생성하여 제출No
cancel_amount이번에 취소할 총금액부분취소 시 필수 · 생략하면 남은 금액 전체취소No
tax_free_amount이번 취소금액 중 면세금액전액 과세주문인 경우 0으로 입력 또는 생략No

Response Body · 전체취소 성공

{
    "status": "success",
    "cashbill": {
        "id": 12345,
        "status": "cancelled"
    }
}

Response Body · 부분취소 성공

{
    "status": "success",
    "cashbill": {
        "id": 12345,
        "status": "partially_cancelled",
        "cancel_amount": 5000,
        "cumulative_cancelled_amount": 5000,
        "remaining_amount": 14000
    }
}

Error Response

{
    "status": "error",
    "cashbill": {
        "id": 12345,
        "status": "cancel_failed"
    },
    "error": {
        "code": "-99999999",
        "message": "팝빌 오류 메시지"
    }
}
POST입금 자동확인 APIDEPRECATED

현금영수증-발행취소

API Endpoint

https://api.payaction.app/cashbill-cancel

Curl

curl -X POST "https://api.payaction.app/cashbill-cancel" \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-H "x-mall-id: your-mall-id" \
-d '{
    "order_number": "1234567890"
}'

Request Body

{
    "order_number": "1234567890"
}
FieldDescriptionRequired
order_number주문번호Yes

DEPRECATED: 신규 연동은 POST /cashbills/{cashbill_id}/cancel을 사용해 주세요.

이 API는 종료 예정입니다.

Response Body

{
    "status": "success",
    "response": {}
}

Error Response

{
    "status": "error",
    "response": {
        "message": "누락된 필드가 존재합니다."
    }
}

API

페이위젯

주문 즉시 무통장입금 안내 창을 띄우고, 입금이 확인되면 구매자 화면에 바로 알려줍니다.

동작 방식

  1. 1

    주문 등록

    기존 주문 API를 그대로 호출합니다.

  2. 2

    위젯 호출

    결제 완료 페이지에 스크립트를 넣고 상점 ID와 주문번호를 넘깁니다.

  3. 3

    입금 확인

    입금이 잡히면 위젯이 스스로 완료 화면으로 바뀝니다.

SDK 설치

결제 완료 페이지에 아래 한 줄을 넣습니다. 별도 빌드나 패키지 설치가 필요하지 않습니다.

<script src="https://payaction.app/widget/v1/pay-widget.js"></script>

위젯 호출

주문이 만들어진 뒤 상점 ID와 주문번호를 넘겨 위젯을 엽니다.

<script>
  const orderId = "상점의 주문 ID";

  PayActionWidget.open({
    mallId: "상점 ID",
    orderNumber: "주문번호",
    completionHref: `/orders/${orderId}`,
    onClose: function () {
      // X 또는 PayActionWidget.close()로 위젯을 닫았을 때 실행됩니다.
      // 완료 버튼을 누른 경우에는 실행되지 않습니다.
    }
  });
</script>
옵션필수설명
mallIdYes대시보드 > API의 상점 ID
orderNumberYes주문 등록에 사용한 주문번호
completionHrefNo완료 버튼을 눌렀을 때 이동할 주문별 주소. root-relative 경로 또는 https 주소를 개발 단계에서 생성합니다.
onCloseNoX 또는 PayActionWidget.close()로 위젯을 닫았을 때 호출됩니다. 완료 버튼에서는 호출되지 않습니다.

닫은 위젯을 다시 열려면 PayActionWidget.open()을 같은 값으로 다시 호출합니다.

참고 사항

입금이 확인되면 위젯이 스스로 입금확인(결제완료) 상태로 표시됩니다.

구매자가 위젯에서 현금영수증을 신청하면 입금 확인 시 자동으로 발행됩니다.

결제 완료 알림은 기존 구매자 알림 설정을 따릅니다. 위젯 때문에 추가로 발송되지 않습니다.

완료 버튼 문구와 화면 표시 항목은 대시보드 > 페이위젯에서 설정하고, 주문별 완료 이동 주소는 개발 단계에서 completionHref로 전달합니다.

웹훅

개요

웹훅(Webhook)이란 특정 이벤트 발생 시 고객사 서버로 이벤트 정보를 자동전송하는 기능입니다. 데이터 조회를 위해 매번 API를 호출하지 않고도, 이벤트 발생 즉시 정보를 전송받기에 보다 효율적인 시스템 운영에 도움이 됩니다.

특정 이벤트 발생 시 HTTP POST 요청을 통해, 미리 등록된 고객사의 콜백 URL로 실시간으로 정보를 전송합니다. 고객사는 이 JSON 형식의 이벤트 정보를 받아 즉시 시스템에 반영할 수 있습니다.

인증정보

이벤트 수신 시 함께 전송되는 인증정보입니다. 페이액션 WebHook 인증 정보는 x-webhook-key 헤더에 포함되어 다음과 같은 형식으로 전송됩니다.

발신자가 페이액션임을 검증하는 중요한 정보이므로 관리에 주의하시고, 외부에 노출된 경우 즉시 재발급받아 사용하시기 바랍니다.

Webhook Header

KeyDescription
Content-Typeapplication/json
x-webhook-keyyour-webhook-key (대시보드 > API > 웹훅키에서 확인 가능)
x-mall-idyour-mall-id (대시보드 > API > 상점ID에서 확인 가능)
x-trace-id트랜잭션 고유 ID

프로세스

웹훅 전송 프로세스
  1. 1이벤트 발생이벤트 발생 즉시 미리 등록한 웹훅 URL로 HTTP POST 요청을 보내 이벤트 정보를 전달합니다.
  2. 2웹훅 수신 및 응답 발신고객사는 수신한 JSON 데이터를 시스템에 반영합니다. 즉시 응답 메시지를 반환합니다.
  3. 3응답 확인성공 상태의 결과값을 반환합니다. 성공 응답이 아닌 경우로 [재전송 정책]에 따라 웹훅이 다시 전송될 수 있습니다.

응답결과 반환

고객사는 웹훅 수신 시 처리 결과를 HTTP Response로 반환해야 합니다. 페이액션은 반환한 응답값으로 정상적으로 수신했는지를 확인합니다. 정상 수신 결과값을 제외한 모든 응답은 실패로 간주되며, 재전송 정책을 따릅니다.

웹훅을 정상적으로 수신한 경우 Response Body를 JSON타입으로 아래와 같이 반환해야 합니다.반환하지 않아 실패 처리된 웹훅이 지속적으로 일정 수준 이상 발생 시 서비스 이용이 제한될 수 있습니다.
유형결과값상태코드
Response Body{ "status": "success" }200

실패 및 재시도

웹훅 전송 실패 시 5분, 30분 간격으로 재전송합니다. 최종 시도까지 실패 시 알림 이메일이 발송됩니다.

※ 고객사 시스템 정상화 이후 페이액션 사이트에서 웹훅 재전송 요청하여 다시 전송 받을 수 있습니다.

  • 응답결과 미반환
  • Response Body 형식 불일치
  • HTTP 통신 오류
  • 기타

전송내역 확인

Webhook 로그 화면
Webhook 로그와 재전송 버튼 위치
  • 대시보드 > API > Webhook로그
  • 최근 1달 이내 발송된 웹훅 내역을 조회하실 수 있습니다.
  • [재전송] 버튼 클릭시 해당 웹훅이 즉시 발송됩니다.
  • 3회 이상 웹훅 수신 실패로 알림 이메일 수신한 경우 고객사 서버 정상화 후 해당기능으로 재수신 하실 수 있습니다.

재전송 정책

페이액션은 웹훅 누락이나 지연을 방지하기 위해 최초 전송 포함 최대 3회까지 웹훅을 재전송합니다. 마지막 시도까지 실패하면, 알림 이메일이 발송됩니다.

웹훅 재전송 프로세스
웹훅 실패 후 재전송 흐름

웹훅

웹훅 레퍼런스

WEBHOOK입금 자동확인 API

매칭완료

Webhook Body

자동발행 성공:
{
    "order_number": "1234567890",
    "order_status": "매칭완료",
    "processing_date": "2023-07-26T11:31:00+09:00",
    "cashbill": {
        "id": 12345,
        "status": "issued"
    }
}

자동발행 실패:
{
    "order_number": "1234567890",
    "order_status": "매칭완료",
    "processing_date": "2023-07-26T11:31:00+09:00",
    "cashbill": {
        "id": 12345,
        "status": "issue_failed",
        "error": {
            "code": "-99999999",
            "message": "팝빌 오류 메시지"
        }
    }
}
FieldDescriptionRequired
order_number주문번호
order_status주문상태
processing_date처리일시Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00
cashbill현금영수증 자동발행 대상일 때만 포함되는 발행 결과 요약No
cashbill.id현금영수증 ID.취소 API의 cashbill_id로 사용No
cashbill.status자동발행 확정 결과"issued" 또는 "issue_failed"No
cashbill.error.code발행 실패 코드issue_failed일 때만 포함No
cashbill.error.message발행 실패 메시지issue_failed일 때만 포함No

cashbill은 현금영수증 자동발행 기능 사용 시에만 추가로 전달되는 필드입니다. 사용하지 않는 주문에서는 생략됩니다.

WEBHOOK입출금 데이터수신 API

입출금

Webhook Body

{
    "transaction_type": "deposited",
    "bank_account_id": "1689197615581x256615117901486500",
    "bank_account_number": "12345678901234",
    "bank_code": "003",
    "amount": 100000,
    "transaction_date": "2024-04-15T15:03:00+09:00",
    "transaction_name": "홍길동",
    "balance": 111222333,
    "processing_date": "2024-04-15T15:03:01+09:00"
}
FieldDescription
transaction_type거래 구분"deposited" (입금) 또는 "withdrawn" (출금)
bank_account_id은행계좌id
bank_account_number은행계좌번호
bank_code은행코드하단의 기관코드표 참조
amount거래금액
transaction_date거래일시Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00
transaction_name거래자명
balance잔액
processing_date처리일시Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00

도움말

자주 묻는 질문