subscribe integration - nicepayments/nicepay-manual GitHub Wiki
๋์ด์คํ์ด๋จผ์ธ for StartUp ์๋น์ค๋ ๊ฐ๋งน์ ์ ์ ๊ธฐ๊ฒฐ์ ์๋น์ค๋ฅผ ์ํด ์ธ ๊ฐ์ง API๋ฅผ ์ ๊ณตํ๊ณ ์์ต๋๋ค.
๊ฐ๋งน์ ์ ์ ๊ธฐ๊ฒฐ์ ์๋น์ค๋ฅผ ๊ณ ๊ฐ์๊ฒ ์ ๊ณตํ๊ธฐ ์ํด ๋นํค ๋ฐ๊ธ API๋ฅผ ์ฌ์ฉํ์ฌ์ผ ํฉ๋๋ค.
๋์ผํ ๊ฒฐ์ ์๋จ์ผ๋ก ๋ค์์ ๋นํค๋ฅผ ๋ฐ๊ธ ๋ฐ์ ์ ์์ต๋๋ค.
๋นํค ๋ฐ๊ธ API๋ฅผ ์ฌ์ฉํ๊ธฐ ์ํด์๋ ์ฌ์ ์ ๊ณ ๊ฐ์ ๊ฒฐ์ ์ ๋ณด๋ฅผ ๋ฐ์ encData ๊ฐ์ ๋ง๋ค์ด ๋ณด๋ด์ผ ํฉ๋๋ค.
๊ฐ์ธ์ ๋ณด๋ณดํธ๋ฒ์ ๋ฐ๋ผ ๊ณ ๊ฐ์ ๊ฐ์ธ์ ๋ณด ๋ฐ ๊ฒฐ์ ์ ๋ณด๊ฐ ์ ์ฅ๋๊ณ ์ฌ์ฌ์ฉ๋จ์ ๊ณ ๊ฐ์๊ฒ ๋ช ํํ ์๋ ค์ผ ํฉ๋๋ค.
curl -X POST 'https://api.nicepay.co.kr/v1/subscribe/regist' # (1) ๋นํค๋ฐ๊ธ์ ์ํ endpoint
-H 'Content-Type: application/json'
-H 'Authorization: Basic ZWVjOGQzNTA4Y2IwNDI1ZGI5NTViMzBiZjM5...'
-D '{
"encData":"{์ํธํ๋ ๊ฒฐ์ ์ ๋ณด ๋ฐ์ดํฐ}" # (2) ๊ฒฐ์ ์ ๋ณด ์ํธํ AES128 or AES256
, "orderId":"{์์ ๊ฑฐ๋ ๊ณ ์ ๋ฒํธ}" # (3) ๊ฒฐ์ ์์ฒญ์ด ์ค๋ณต์ผ๋ก ๋ฐ์ํ์ง ์๋๋ก ๊ฐ๋งน์ ์์ ์์ฑํ๋ ์ ๋ํฌํ ID
, "encMode":"{null or A2}" # null: AES128, A2: AES256 # (4) ์ํธํ ๋ชจ๋ (null: AES128, A2: AES256)
}'
-
(1):
curl -X POST 'https://api.nicepay.co.kr/v1/subscribe/regist'
- ๋นํค ๋ฐ๊ธ์ ์ํ endpoint
-
(2):
"encData":"{์ํธํ๋ ๊ฒฐ์ ์ ๋ณด ๋ฐ์ดํฐ}"
- ๊ณ ๊ฐ์ ๊ฒฐ์ ์ ๋ณด๋ฅผ AES128, AES256 ์๊ณ ๋ฆฌ์ฆ ๋ฐฉ์์ผ๋ก ์ํธํํ ๋ฐ์ดํฐ
- encMode ๊ฐ์ด null๋ก ๋น ๊ฐ์ ๋ณด๋ด๋ ๊ฒฝ์ฐ AES128๋ก ์ํธํ ํด์ผํ๊ณ , encMode์ ๊ฐ์ A2๋ก ์ค์ ํ๋ค๋ฉด encData๋ AES256 ์๊ณ ๋ฆฌ์ฆ์ผ๋ก ์ํธํ
- encData ๋ช ์ธ์
-
(3):
orderId":"{์์ ๊ฑฐ๋ ๊ณ ์ ๋ฒํธ}"
- ๊ฐ๋งน์ ์ ์์ฒญ์ด ์ค๋ณต์ฒ๋ฆฌ ๋์ง ์๋๋ก, ๊ฐ๋งน์ ์ uniqueํ ID ๊ฐ์ ์ค์
- ๋์ด์คํ์ด๋จผ์ธ ๋ ๊ฐ๋งน์ ์ API ์์ฒญ์ orderId์ ์ค๋ณต์ ๊ฒ์ฆํ์ฌ ๋์ผํ ์์ฒญ์ ๋ณด๊ฐ ์ฌ๋ฌ ์ฐจ๋ก ๋ฐ์ํ์ง ์๋๋ก ํจ
-
(4):
"encMode":"{null or A2}"
- ์ํธํ ์๊ณ ๋ฆฌ์ฆ์ ์ฌ์ฉํ์ฌ ๋ง๋ encData๋ก ๋นํค ๋ฐ๊ธ์ ์์ฒญํ๋ ค๊ณ ํ ๋, ๋์ด์คํ์ด๋จผ์ธ ์ encData๋ฅผ ์ด๋ค ๋ฐฉ์์ผ๋ก ๋ง๋ค์๋์ง๋ฅผ ์ ๋ฌํ๋ ํ๋ ๊ฐ
- encMode ํ๋์ ๊ฐ์ ์ค์ ํ์ง ์๋ ๊ฒฝ์ฐ, ๋์ด์คํ์ด๋จผ์ธ ๋ AES128 ์๊ณ ๋ฆฌ์ฆ ๋ฐฉ์์ด๋ผ ํ๋จํ๊ณ ๊ฒ์ฆํ๊ณ , A2๋ก ์ค์ ํ๋ ๊ฒฝ์ฐ AES256 ์๊ณ ๋ฆฌ์ฆ ๋ฐฉ์์ด๋ผ ํ๋จํ๊ณ ๊ฒ์ฆ
{
"resultCode": "0000",
"resultMsg": "์ ์ ์ฒ๋ฆฌ๋์์ต๋๋ค.",
"tid": "{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค ๋ฐ๊ธ์ ๋ํ TransactionId}",
"orderId": "{๊ฐ๋งน์ ์ฃผ๋ฌธ ๊ณ ์ ์๋ณ์}",
"bid": "BIKY{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค}", # (1) ๋นํค ๋ฐ๊ธ ์ฑ๊ณต์ ๋ฐ๊ธ๋ ๋นํค(ํด๋น ํค๋ฅผ ํตํด ๋นํค ์น์ธ ์์ฒญ์ด ๊ฐ๋ฅํฉ๋๋ค.)
"authDate": "2023-12-26T00:00:00.000+0900",
"cardCode": "06",
"cardName": "[์ ํ]",
"messageSource": "nicepay"
}
- (1):
"bid": BIKY{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค}
- ์ ์์ ์ธ ๋นํค ๋ฐ๊ธ ์์ฒญ์ ๋ํ ์๋ต์ผ๋ก ๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค
- ํด๋น ๋นํค๋ฅผ ํตํด ์ ๊ธฐ์ ์ธ ๋นํค์น์ธ ์์ฒญ์ผ๋ก ์ ๊ธฐ๊ฒฐ์ ์๋น์ค ๊ตฌํ์ด ๊ฐ๋ฅํฉ๋๋ค.
encData์ ๊ตฌ์ฑ์์๋ ์นด๋๋ฒํธ, ์ ํจ๊ธฐ๊ฐ(YY, MM), ์๋ ์์ผ / ์ฌ์ ์๋ฒํธ, ์นด๋ ๋น๋ฐ๋ฒํธ๋ก ๊ตฌ์ฑ๋์ด ์์ต๋๋ค.
๊ธฐ๋ณธ ๊ฐ์ผ๋ก ๋ชจ๋ ํ๋๋ฅผ ์ฌ์ฉํด์ผํ๋ฉฐ ์ผ๋ถ ๊ณ์ฝ์กฐ๊ฑด์ ๋ฐ๋ผ ๋ฌ๋ผ์ง ์ ์์ต๋๋ค.
-
encData ํ๋ ์ํธํ ์์ (AES-128)
- secretKey๋ฅผ ์ํธํค๋ก ์ฌ์ฉ
- ํ๋ฌธ : cardNo=1234567890123456&expYear=25&expMonth=12&idNo=800101&cardPw=12
- ์ํธํค : 2dcc2a0d63bf4694 (SecretKey ์16์๋ฆฌ)
- ์ํธํ๊ฒฐ๊ณผ : `2127975b6d82c36136ba8197a997a994f6c086ff75a6d35e514c54a1e686545e60b76f11bec706de1082e43dd74ae5c5f0709dc1eca6c3cd20e1c0e9e9b7a85c6505461c91c865d82072e41ba5284bd7`
-
encData ํ๋ ์ํธํ ์์ (AES-256)
- secretKey๋ฅผ ์ํธํค๋ก ์ฌ์ฉ
- secretKey์ ์ 16์๋ฆฌ๋ฅผ IV ๊ฐ์ผ๋ก ์ฌ์ฉ
- ํ๋ฌธ : cardNo=1234567890123456&expYear=25&expMonth=12&idNo=800101&cardPw=12
- ์ํธํค : 2dcc2a0d63bf469490bb19a201be3735
- IV : 2dcc2a0d63bf4694 (SecretKey ์16์๋ฆฌ)
- ์ํธํ๊ฒฐ๊ณผ : `6ecfe97e521bc67c3053d74a9dbdba53033d343fc9e8e38e730964b22ef2e4a59607171b00a9da977141b3f79fffa1e80a16c08bc58666b479f554a966a363414347e62f2621f8df220c7a4a545592d0`
๋นํค ๋ฐ๊ธ API ๋ํ F&Q
Q1. PKCS7 ์ ์์๋ช ๊ฒ์ฆ ์คํจ
๋นํค ์น์ธ์ ์ ๊ธฐ ๊ฒฐ์ ์๋น์ค๋ฅผ ๊ตฌ์ถํ๊ธฐ ์ํด ์ค์ ์น์ธ ์์ฒญํ๋ ๊ณผ์ ์ API ์ ๋๋ค.
๋นํค ๋ฐ๊ธ์ ํตํด ๋ฐ๊ธ ๋ฐ์ BID๋ฅผ ํตํด ๋นํค ์น์ธ์ ์์ฒญํฉ๋๋ค.
curl --request POST --url 'https://api.nicepay.co.kr/v1/subscribe/{bid}/payments' # (1) ๋นํค ์น์ธ์ ์ํ endpoint
--header 'Content-Type: application/json'
--header 'Authorization: Basic ZWVjOGQzNTA4Y2IwNDI1ZGI5NTViMzBi...'
--data '{
"orderId":"{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}" # (2) ๊ฐ๋งน์ ์์ ๋นํค ์น์ธ ์์ฒญ์ ์ํ ๊ณ ์ ์์ฒญ ์๋ณ์
,"amount":1004
,"goodsName":"์ ๊ธฐ๊ฒฐ์ ์ํ"
,"cardQuota":0 # (3) ํ ๋ถ๊ฐ์์ (0: ์ผ์๋ถ, 01~12: ๊ฐ์์)
,"useShopInterest":false # (4) ์์ ๋ถ๋ด ๋ฌด์ด์ ์ค์ ์ฌ๋ถ (true: ๋ฌด์ด์ , false: ์ ์ด์)
}'
-
(1):
curl --request POST --url 'https://api.nicepay.co.kr/v1/subscribe/{bid}/payments'
- ๋นํค ์น์ธ์ ์ํ endpoint
- {bid}๋ ๋นํค ๋ฐ๊ธ API๋ฅผ ํตํด ๋ฐ๊ธ ๋ฐ์ BID ๊ฐ์ผ๋ก ๋์ฒด
-
(2):
"orderId":"{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}"
- ๊ฐ๋งน์ ์์ ๋นํค ์น์ธ ์์ฒญ์ ์ํ ๊ณ ์ ์์ฒญ ์๋ณ์
- ์์ฒญ ๋ฐ์ดํฐ์ ์ ํฉ์ฑ์ ๊ฒ์ฆ ํ๊ธฐ ์ํ SignData๋ฅผ ์์ฑํ๊ธฐ ์ํ ํ์ ์์
-
(3):
"cardQuota":0
- ํ ๋ถ๊ฐ์์ (0: ์ผ์๋ถ, 01~12: ๊ฐ์์)
-
(4):
"useShopInterest":false
- ์์ ๋ถ๋ด ๋ฌด์ด์ ์ค์ ์ฌ๋ถ (true: ๋ฌด์ด์ , false: ์ ์ด์)
๋นํค ์น์ธ ์๋ต์ ์ ์ฉ์นด๋ ๊ฒฐ์ ์ฒ๋ฆฌ์ ๋ํ ๊ฒฐ๊ณผ๋ฅผ ๋ํ๋ ๋๋ค.
{
"resultCode": "0000",
"resultMsg": "์ ์ ์ฒ๋ฆฌ๋์์ต๋๋ค.",
"tid": "{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค ์น์ธ์ ๋ํ TransactionId}", # (1) ๋นํค ์น์ธ ์ฑ๊ณต์ ๋ฐ๊ธ๋ TransactionId
"cancelledTid": null,
"orderId": "{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}", # (2) ๊ฐ๋งน์ ์์ ๋นํค ์น์ธ ์์ฒญ์ ์ํ ๊ณ ์ ์์ฒญ ์๋ณ์
"ediDate": "2023-12-26T10:53:30.151+0900",
"signature": "{๋ฐ์ดํฐ ๊ฒ์ฆ์ ์ํ ์๊ทธ๋์ฒ ์ ๋ณด}",
"status": "paid",
"paidAt": "2023-12-26T10:53:29.000+0900",
"failedAt": "0",
"cancelledAt": "0",
"payMethod": "card",
"amount": 1004,
"balanceAmt": 1004,
"goodsName": "์ ๊ธฐ๊ฒฐ์ ์ํ",
"mallReserved": null,
"useEscrow": false,
"currency": "KRW",
"channel": null,
"approveNo": "{์น์ธ ๋ฒํธ}",
"buyerName": null,
"buyerTel": null,
"buyerEmail": null,
"receiptUrl": "https://npg.nicepay.co.kr/issue/IssueLoader.do?type=0&innerWin=Y&TID={๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค ์น์ธ์ ๋ํ TransactionId}",
"mallUserId": null,
"issuedCashReceipt": false,
"coupon": {
"couponAmt": 0
},
"card": { # (3) ์นด๋ ์ ๋ณด
"cardCode": "06",
"cardName": "์ ํ",
"cardNum": "123456******1234",
"cardQuota": 0,
"isInterestFree": false,
"cardType": "credit",
"canPartCancel": true,
"acquCardCode": "06",
"acquCardName": "์ ํ"
},
"bid": "BIKY{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค}",
"messageSource": "nicepay"
}
- (1):
"tid": "{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค ์น์ธ์ ๋ํ TransactionId}"
- ๋นํค ์น์ธ ์ฑ๊ณต์ ๋ฐ๊ธ๋ TransactionId
- ๋นํค ์น์ธ ์์ฒญ์ ๋ํ ์๋ต์ผ๋ก ๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ TransactionId
- ํด๋น TransactionId๋ฅผ ํตํด ๊ฒฐ์ ์ทจ์ ์์ฒญ์ด ๊ฐ๋ฅํฉ๋๋ค.
- (2):
"orderId": "{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}"
- ๊ฐ๋งน์ ์์ ๋นํค ์น์ธ ์์ฒญ์ ์ํ ๊ณ ์ ์์ฒญ ์๋ณ์
- (3):
"card": {์นด๋ ์ ๋ณด}
- ์นด๋ ์ ๋ณด
- ์นด๋๋ฒํธ(cardNum)๋ ์ 6์๋ฆฌ์ ๋ค 4์๋ฆฌ๋ฅผ ์ ์ธํ ๋๋จธ์ง๋ฅผ *๋ก ๋ง์คํน ์ฒ๋ฆฌ๋ฉ๋๋ค.
๋นํค ์ญ์ ๋ ์ ๊ธฐ๊ฒฐ์ ๋ฅผ ์ํด ๋ฐ๊ธ ๋ฐ์๋ ๋นํค๋ฅผ ์ญ์ ํ๊ธฐ ์ํ API ์ ๋๋ค.
์ญ์ ์ฒ๋ฆฌ๊ฐ ์ด๋ฃจ์ด์ง BID๋ก๋ ๋นํค ์น์ธ์์ฒญ์ด ๋ถ๊ฐํฉ๋๋ค.
curl --request POST --url 'https://api.nicepay.co.kr/v1/subscribe/BIKY{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค}/expire' \ # (1) ๋นํค ์ญ์ ๋ฅผ ์ํ endpoint
--header 'Authorization: Basic ZWVjOGQzNTA4Y2IwNDI1ZGI5NTViMzBi...' \
--header 'Content-Type: application/json' \
--data '{
"orderId":"{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}", # (2) ๊ฐ๋งน์ ์์ ๋นํค์ญ์ ์์ฒญ์ ์ํ ๊ณ ์ ์์ฒญ ์๋ณ์ (signData ์์ฑ์ ์ํด ํ์ ๊ฐ)
"returnCharSet":"UTF-8"
}'
-
(1):
curl --request POST --url 'https://api.nicepay.co.kr/v1/subscribe/BIKY{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค}/expire'
- ๋นํค ์ญ์ ๋ฅผ ์ํ endpoint
- {bid}๋ ๋นํค ๋ฐ๊ธ API๋ฅผ ํตํด ๋ฐ๊ธ ๋ฐ์ BID ๊ฐ์ผ๋ก ๋์ฒด
-
(2):
"orderId":"{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}"
- ๊ฐ๋งน์ ์์ ๋นํค ์น์ธ ์์ฒญ์ ์ํ ๊ณ ์ ์์ฒญ ์๋ณ์
- ์์ฒญ ๋ฐ์ดํฐ์ ์ ํฉ์ฑ์ ๊ฒ์ฆ ํ๊ธฐ ์ํ SignData๋ฅผ ์์ฑํ๊ธฐ ์ํ ํ์ ์์
{
"resultCode": "0000",
"resultMsg": "์ ์ ์ฒ๋ฆฌ๋์์ต๋๋ค.",
"tid": "{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค์ญ์ ์ ๋ํ TransactionId}",
"orderId": "{๊ฐ๋งน์ ์ API ์์ฒญ ์๋ณ์}",
"bid": "BIKY{๋์ด์คํ์ด๋จผ์ธ ๊ฐ ๋ฐ๊ธํ ๋นํค}",
"authDate": "2023-12-26T11:12:00.750+0900"
}