시작하기

개발자 센터

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

실시간 결제확인을 위한 1초 자동 입금확인, 결제내역 현금영수증 자동발행/취소
계좌 실시간 거래데이터 수신을 위한 1초 입출금 데이터 수신

페이액션의 모든 API는 REST API로 제공되며, HTTP 요청을 보낼 수 있는 환경이라면 OS나 DB에 관계없이 사용할 수 있습니다.
API는 SSL 보안이 적용된 HTTPS 프로토콜을 통해서만 호출할 수 있으며, 요청 결과는 JSON 형식으로 응답됩니다.
요청과 응답에 포함되는 주요 데이터는 전송 구간에서 암호화됩니다.
API 인증에는 x-api-key와 x-mall-id가 사용되며, 민감한 키가 외부에 노출된 경우 즉시 재발급해 주세요.
API 요청이 서버 처리 단계에서 거절되는 경우 HTTP 상태 코드와 함께 오류코드 및 메시지를 반환합니다. 단, /order 등 일부 공개 API의 업무 검증 실패는 HTTP 200 응답 본문에 status: "error"로 반환될 수 있습니다.

어떤 연동을 하시나요?

1초 자동 입금확인

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

입출금 데이터 수신

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

서비스 연동 순서

1
상점등록
[설정] 메뉴에서 상점정보를 입력합니다.
2
계좌등록
계좌등록 및 해당은행SMS통지서비스 등 가이드에 따라 신청합니다.
3
API정보 입력
[API] 메뉴에서 API키를 생성하고 웹훅URL을 입력합니다.
4
서비스 개발 및 연동
아래 API 레퍼런스를 참고하여 서비스를 개발 및 연동합니다.

API

요청 방식과 헤더 설정

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

헤더 설정

Header	Value	Note
Content-Type	application/json	-
x-api-key	your-api-key	[대시보드] > [API]의 ‘API키’ 에서 확인하실 수 있습니다.
x-mall-id	your-mall-id	[대시보드] > [API]의 ‘상점ID’에서 확인하실 수 있습니다.

API 유형

입금 자동확인 API

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

입출금 데이터수신 API

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

API 레퍼런스

Method	Name	Path
POST	주문입금 자동확인 API	/order
POST	주문-매칭제외입금 자동확인 API	/order-exclude
POST	현금영수증-발행취소입금 자동확인 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,
    "order_date": "2023-07-26T11: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,
    "order_date": "2023-07-26T11:31:00+09:00",
    "billing_name": "홍길동",
    "orderer_name": "홍길동",
    "orderer_phone_number": "01012345678",
    "orderer_email": "hong@gildong.kr",
    "trade_usage" : "소득공제용",
    "identity_number" : "01012345678"
}

Field	Description	Required
order_number	주문번호 *22자 이하 권장, 초과시 알림톡 발송불가	Yes
order_amount	주문금액	Yes
order_date	주문일시 *Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00	Yes
billing_name	입금자명 *자동매칭시 매칭여부 판단 항목	Yes
orderer_name	주문자명	Yes
orderer_phone_number	주문자 전화번호 *하이픈(-) 및 국가코드(+82)를 미포함 전송 - 예시 : 01012345678	No
orderer_email	주문자 이메일	No
trade_usage	현금영수증-거래구분 (택1) - 소득공제용 - 지출증빙용	No
identity_number	현금영수증-식별번호 *숫자만 입력 - 소득공제용 : 휴대폰번호 입력 - 지출증빙용 : 사업자번호 입력	No

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

현금영수증-거래구분 및 현금영수증-식별번호 필드는 선택항목입니다. 현금영수증 자동발행 기능을 사용하는 경우에만 해당필드를 포함하여 요청해야 합니다. 현금영수증 자동발행 기능은 프리미어 플랜 이상 이용 시 지원됩니다.

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

필수값 누락과 중복 주문은 HTTP 200 응답 본문에 status: "error"로 반환됩니다. 인증 정보나 상점 조건이 맞지 않는 요청은 HTTP 400으로 거절될 수 있습니다.

Response Body

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

Error Response

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

중복 주문 예시:
{
    "status": "error",
    "response": {
        "message": "이미 해당 주문번호의 주문이 존재합니다."
    }
}

POST입금 자동확인 API

주문-매칭제외

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"
}

Field	Description	Required
order_number	주문번호	Yes

Response Body

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

Error Response

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

POST입금 자동확인 API

현금영수증-발행취소

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"
}

Field	Description	Required
order_number	주문번호	Yes

현금영수증 자동발행취소 기능은 프리미어 플랜 이상 이용 시 지원됩니다.

Response Body

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

Error Response

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

웹훅(Webhook)

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

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

인증정보

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

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

Webhook Header

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

프로세스

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

응답결과 반환

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

웹훅을 정상적으로 수신한 경우 Response Body를 JSON타입으로 아래와 같이 반환해야 합니다.반환하지 않아 실패 처리된 웹훅이 지속적으로 일정 수준 이상 발생 시 웹훅 발송이 중단됩니다.

유형	결과값	상태코드
Response Body	`{ "status": "success" }`	200

실패 및 재시도

웹훅 전송 실패 시 재전송 정책을 따릅니다. 최종 시도까지 실패 시 알림 이메일이 발송됩니다.

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

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

전송내역 확인

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

재전송 정책

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

웹훅 상세

WEBHOOK입금 자동확인 API

매칭완료

Webhook Body

{
    "order_number": "1234567890",
    "order_status": "매칭완료",
    "processing_date": "2023-07-26T11:31:00+09:00"
}

Field	Description
order_number	주문번호
order_status	주문상태
processing_date	처리일시 *Dates 속성 ISO_8601 Format YYYY-MM-DDTHH:MM:SS+09:00

Header

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

※ 목차의 Webhook 섹션을 반드시 참고해 주세요.

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"
}

Field	Description
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

Header

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

※ 목차의 Webhook 섹션을 반드시 참고해 주세요.

도움말

자주 묻는 질문

기타 일반문의사항은 [고객센터]에서 확인하실 수 있습니다.

개발자 센터

어떤 연동을 하시나요?

1초 자동 입금확인

입출금 데이터 수신

서비스 연동 순서

상점등록

계좌등록

API정보 입력

서비스 개발 및 연동

요청 방식과 헤더 설정

헤더 설정

API 유형

입금 자동확인 API

입출금 데이터수신 API

API 레퍼런스

주문

API Endpoint

Curl

Request Body

Response Body

Error Response

주문-매칭제외

API Endpoint

Curl

Request Body

Response Body

Error Response

현금영수증-발행취소

API Endpoint

Curl

Request Body

Response Body

Error Response

웹훅(Webhook)

인증정보

Webhook Header

프로세스

응답결과 반환

실패 및 재시도

전송내역 확인

재전송 정책

웹훅 상세

매칭완료

Webhook Body

Header

입출금

Webhook Body

Header

자주 묻는 질문