결제

💳

결제

결제

현재 API 버전: v1.3

Payment 객체

결제 정보를 담고 있는 객체입니다. 결제 한 건의 결제 상태, 결제 취소 기록, 결제 금액 등을 자세히 알 수 있습니다. 결제가 승인 됐을 때 응답은 Payment 객체로 항상 동일합니다.

객체 상세

tid string

잽페이의 결제 고유 아이디입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 준비 요청 시, 잽페이 서버에서 생성하여 응답에 포함됩니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인, 결제 취소 API에 사용합니다.

store_id string

상점 아이디입니다. 잽페이에서 발급합니다. 상점을 구별하는 고유 아이디입니다.

order_id string

주문번호입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 상점에서 만들어서 사용한 값입니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.

user_id string

결제를 요청한 이용자의 아이디 입니다. 이 아이디는 0x로 시작하고, 그 뒤로 40자리의 16진수 문자열(숫자 0-9와 문자 a-f)로 이루어진 총 42자의 문자열입니다.

total_amount number

총 결제 금액입니다. 결제가 취소되는 등 결제 상태가 변해도 최초에 결제된 결제 금액으로 유지됩니다.

tax_free_amount number

상품 비과세 금액입니다. 비과세가 없을 경우 0 을 넣어주세요.

vat_amount nullable · number

상품 부가세 금액입니다. 값을 보내지 않을 경우 다음과 같이 VAT 자동 계산합니다.

(상품총액 - 상품 비과세 금액)/11 : 소수점 이하 반올림

supply_amount nullable · number

상품 공급가액입니다. 총 결제 금액 / 1.1 이 공급가액입니다.

green_deposit nullable · number

컵 등 보증금 금액입니다.

approved_at string

결제 승인이 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)

approved_number string

결제 완료 후 발급된 결제 승인 번호입니다.

currency string

통화 단위를 나타내는 변수입니다. 이 변수는 결제 유형인 일반 결제와 법인 결제를 구분하는 데 사용됩니다. 일반 결제는 개인 결제를 의미하며, 이 경우 통화 단위로 KRW를 사용합니다. 법인 결제는 법인 비용 처리를 의미하며, 법인 결제의 통화 단위는 잽페이에서 발급됩니다. 또한, 잽페이에 회원가입 시 사용자의 소속 부서 정보도 등록되므로, 법인 결제 시 어느 부서에서 결제가 이루어졌는지 확인할 수 있습니다. API 요청 시, 해당 결제 유형에 맞는 통화 단위를 설정하여 요청해야 합니다.

department_name string

결제 요청자의 부서에 대한 변수입니다. 법인 결제 시 어떤 부서로 비용처리를 할 것인지 확인합니다.

order_details string

결제 내역은 단일 품목 주문 시 “라떼 1잔”처럼 표시하고, 여러 품목 주문 시 “라떼 1잔 외 4개”처럼 요약하여 제공하시면 됩니다.

status string

결제 승인에 대한 HTTP 상태 코드입니다. 결제가 정상적으로 완료되면 200 상태 코드를 반환하며, 오류가 발생한 경우에는 다른 상태 코드가 반환됩니다. 자세한 내용은 아래 결제 승인에 대한 실패 응답을 참고해 주세요.

version string

요청을 한 잽페이 API 버전입니다.

결제 준비

POST

/api/v1/payment/ready

상점에서 잽페이 서버로 결제 준비를 요청합니다. 잽페이 서버는 응답으로 tid와 잽페이 클라이언트로 이동할 수 있는 URL 등을 제공합니다.

Request Body 파라미터

store_id 필수 · string

상점 아이디 입니다. 잽페이에서 발급합니다. 상점을 구별하는 고유 아이디입니다.

order_id 필수 · string

주문번호입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 상점에서 만들어서 사용한 값입니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 테스트 시 order_id가 이전과 겹치지 않게 유의해주세요.

total_amount 필수 · number

총 결제 금액입니다. 결제가 취소되는 등 결제 상태가 변해도 최초에 결제된 결제 금액으로 유지됩니다.

tax_free_amount 필수 · number

상품 비과세 금액입니다. 비과세가 없을 경우 0 을 넣어주세요.

vat_amount number

상품 부가세 금액입니다. 값을 보내지 않을 경우 다음과 같이 VAT 자동 계산합니다.

(상품총액 - 상품 비과세 금액)/11 : 소수점 이하 반올림

supply_amount number

상품 공급가액입니다. 총 결제 금액 / 1.1 이 공급가액입니다.

green_deposit number

컵 등 보증금 금액입니다.

order_details 필수 · string

결제 내역은 단일 품목 주문 시 “라떼 1잔”처럼 표시하고, 여러 품목 주문 시 “라떼 1잔 외 4개”처럼 요약하여 제공하시면 됩니다.

응답(Response)

성공

tid string

잽페이의 결제 고유 아이디입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

redirect_url string

tid에 대응하는 잽페이 클라이언트로 이동할 수 있는 리디렉트 URL입니다. 또한 결제 준비 api를 테스트하시고 나온 response인 redirect url을 테스트 하실 시에 저희 DB에 사용자 등록이 되어야 정상 동작이 가능합니다. 따라서 회원가입 진행하시게 되면 사용자명을 저희측으로 전달부탁드립니다.

created_at string

해당 결제내용이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

version string

요청을 한 잽페이 API 버전입니다.

결제 준비 응답 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 준비에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 준비 API에서 발생할 수 있는 에러를 살펴보세요.

curl --request POST \
  --url https://app.zab.cash/api/v1/payment/ready \
  --header 'Authorization: Basic dGVzdF9za18xMWQxZGJkMzliNTVjZTY2NDMyY2E3YzA3N2IzZTBjMTo=' \
  --header 'Content-Type: application/json' \
  --data '{"store_id":"S1234","order_id":"T2003","total_amount":1000,"tax_free_amount":0,"supply_amount": 1000,"order_details":"라떼 2잔"}'
Bash
복사
요청(Request)

{
    "tid": "80fb955d-ef86-4115-804f-6301d4f17f86",
    "redirect_url": "https://app.zab.cash/payment/redirect?tid=80fb955d-ef86-4115-804f-6301d4f17f86",
    "created_at": "2024-10-16T09:53:57.901Z",
    "version": "v1.3"
}
JSON
복사
응답(Response)

결제 승인

POST

/api/v1/payment/approve

tid에 해당하는 결제를 검증하고 승인합니다. 결제 승인 요청은 상점이 아닌 잽페이 클라이언트에서 이루어지며, 요청에 대한 응답은 잽페이 클라이언트 뿐만 아니라 웹훅을 통해 상점 앱에도 전달됩니다.

Request Body 파라미터

tid 필수 · string

잽페이의 결제 고유 아이디입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

store_id 필수 · string

상점 아이디입니다. 잽페이에서 발급합니다. 상점을 구별하는 고유 아이디입니다.

order_id 필수 · string

user_id 필수 · string

결제를 요청한 이용자의 아이디입니다. 이 아이디는 0x로 시작하고, 그 뒤로 40자리의 16진수 문자열(숫자 0-9와 문자 a-f)로 이루어진 총 42자의 문자열입니다.

password 필수 · string

잽페이의 결제 비밀번호로, 6자리 숫자로 구성되어 있습니다.

currency 필수 · string

응답(Response)

성공

결제 승인에 성공하면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 승인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 승인 API에서 발생할 수 있는 에러를 살펴보세요.

curl --request POST \
  --url https://app.zab.cash/api/v1/payment/approve \
  --header 'Authorization: Bearer 0xad7b61f65028d45b03a820c1c39b8c78108569c7:0x219df5c2b4d8fb8c88567a29ef7aaa9e211ea486e9ab5d8a1a1a61a12191a2dc152a6651b17b93f3377bcf24692452f6bc36cd8a4fe5a20362f2fd68a722c3a91b' \
  --header 'x-time: 2024-10-04T06:45:38.967Z' \
  --header 'Content-Type: application/json' \
  --data '{"tid":"80fb955d-ef86-4115-804f-6301d4f17f86","store_id":"S1234","order_id":"T2003","user_id":"0xAD7B61f65028d45B03a820C1c39b8C78108569c7","password":"123456","currency":"ITCEN"}'
Bash
복사
요청(Request)

{
  "tid": "80fb955d-ef86-4115-804f-6301d4f17f86",
  "store_id": "S1234",
  "order_id": "T2003",
  "user_id": "0x9ED3d6C7e67Bb2bB56b709Cc603F329Df99e22Ed",
  "total_amount": 1000,  
  "tax_free_amount": 0,
  "vat_amount": null,
  "supply_amount": 1000,
  "green_deposit": null,
  "approved_at": "2024-10-16T10:20:03.260Z",
  "approve_number": 1,
  "currency": "ITCEN",
  "department_name": "payments",
  "order_details": "라떼 외 1개",
  "status": 200,
  "version": "v1.3"
}
JSON
복사
응답(Response)

결제 승인 요청은 잽페이 클라이언트에서 이루어지며, 그에 대한 응답은 상점 앱에서 웹훅을 통해 수신할 수 있습니다. 상점에서 웹훅 URL을 제공해 주시면, 잽페이가 고유 상점 ID(store_id)와 함께 등록해 드립니다. 이를 통해 상점 앱은 결제 승인 응답을 받을 수 있습니다. 결제 승인 요청에 대한 Authorization은 내부 API 보안 방식인 Bearer을 사용합니다.

결제 취소

POST

/api/v1/payment/cancel

tid에 해당하는 결제를 취소합니다. 결제 취소 요청은 카페앱에서 이루어지며, 잽페이 서버에서 처리 후 응답을 카페앱 서버로 전송합니다.

현재 결제 취소 API 처리 과정에서 별도의 인증 절차가 포함되어 있지 않습니다. 따라서 이 기능은 반드시 결제 취소 권한이 있는 관리자만 사용할 수 있도록 제한해 주시기 바랍니다.

Request Body 파라미터

tid 필수 · string

잽페이의 결제 고유 아이디입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

store_id 필수 · string

상점 아이디입니다. 잽페이에서 발급합니다. 상점을 구별하는 고유 아이디입니다.

응답(Response)

성공

tid string

잽페이의 결제 고유 아이디입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

store_id string

상점 아이디입니다. 잽페이에서 발급합니다. 상점을 구별하는 고유 아이디 입니다.

order_id nullable · string

user_id string

결제를 요청한 이용자의 아이디입니다. 이 아이디는 0x로 시작하고, 그 뒤로 40자리의 16진수 문자열(숫자 0-9와 문자 a-f)로 이루어진 총 42자의 문자열입니다.

total_amount number

총 결제 금액입니다. 결제 상태가 변동 되더라도 최초 결제된 금액으로 유지됩니다. 결제가 취소된 경우에는 총 취소 금액을 의미합니다.

tax_free_amount number

상품 비과세 금액입니다. 비과세가 없을 경우 0 을 넣어주세요.

vat_amount nullable · number

상품 부가세 금액입니다. 값을 보내지 않을 경우 다음과 같이 VAT 자동 계산합니다.

(상품총액 - 상품 비과세 금액)/11 : 소수점 이하 반올림

supply_amount number

상품 공급가액입니다. 총 결제 금액 / 1.1 이 공급가액입니다.

green_deposit nullable · number

컵 등 보증금 금액입니다.

canceled_at string

결제 취소가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

canceled_number string

결제 취소 후 발급된 결제 취소 번호입니다.

currency string

order_details string

결제 내역은 단일 품목 주문 시 “라떼 1잔”처럼 표시하고, 여러 품목 주문 시 “라떼 1잔 외 4개”처럼 요약하여 제공하시면 됩니다.

department_name string

결제 요청자의 부서입니다. 법인 결제 시 어떤 부서로 비용처리를 할 것인지 확인합니다.

version string

요청을 한 잽페이 API 버전입니다.

결제 실패 응답 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 취소에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 취소 API에서 발생할 수 있는 에러를 살펴보세요.

curl --request POST \
  --url https://app.zab.cash/api/v1/payment/cancel \
  --header 'Authorization: Basic dGVzdF9za18xMWQxZGJkMzliNTVjZTY2NDMyY2E3YzA3N2IzZTBjMTo=' \
  --header 'Content-Type: application/json' \
  --data '{"tid":"80fb955d-ef86-4115-804f-6301d4f17f86","store_id":"S1234"}'
Bash
복사
요청(Request)

{
    "tid": "80fb955d-ef86-4115-804f-6301d4f17f86",
    "store_id": "S1234",
    "order_id": "T2003",
    "user_id": "0x9ED3d6C7e67Bb2bB56b709Cc603F329Df99e22Ed",
    "total_amount": 1100,
    "tax_free_amount": 0,
    "vat_amount": null,
    "supply_amount": 1000,
    "green_deposit": null,
    "canceled_at": "2024-10-16T11:18:45.266Z",
    "canceled_number": 1,
    "currency": "ITCEN",
    "order_details": "라떼 외 1개",
    "department_name": "payments",
    "version": "v1.3"
}
JSON
복사
응답(Response)