선불 계정 잔액 관리

Apigee Edge 문서입니다.
Apigee X 문서로 이동 정보

선불 계정의 잔액을 관리하려면 다음 작업을 실행하면 됩니다.

• 현재 선불 계정 잔액을 확인합니다. API를 사용하여 선불 계정 잔액 보기를 참고하세요.
• 필요한 경우 Worldpay와 같은 서드 파티 결제 제공업체를 사용하여 계정 잔액을 충전 (금액 추가)합니다. 서드 파티 결제 제공자를 사용하여 선불 잔액 관리를 참고하세요.

  또는 선불 잔액 수동 관리에 설명된 대로 결제를 수동으로 추적하거나 통합 결제 시스템을 통해 추적한 후 수익 창출 API를 호출하여 계정을 재충전하여 충전을 관리할 수 있습니다.

• 수익 창출 API 및 Worldpay와 같은 서드 파티 결제 시스템 공급자를 사용하여 선불 계정 잔액이 특정 기준액 아래로 떨어질 때 자동 새로고침을 설정합니다. 이 옵션은 요금제의 반복 결제를 관리하는 데 유용합니다. 자세한 내용은 API를 사용하여 선불 계정 잔액 자동 재충전 설정을 참고하세요.

선불 계정의 잔액을 계산하려면 어떻게 해야 하나요?

다음 섹션에 설명된 대로 개발자 또는 회사의 선불 계정 잔액을 확인할 때는 응답에서 다음 값을 가져와야 합니다.

• amount: 현재 결제 기간에 사용할 수 있는 총 금액입니다. 이 값은 이 섹션에 설명된 방법을 사용하여 선불 계정을 새로고침할 때 업데이트됩니다.
• usage: 현재 결제 기간 동안 사용된 총 금액입니다. 이 값은 요건을 충족하는 수익 창출 거래가 있을 때마다 업데이트되거나 크레딧을 발급 (양수 또는 음수)하여 업데이트됩니다.

amount 값에서 usage 값을 빼면 현재 결제 기간의 남은 선불 계정 잔액을 계산할 수 있습니다. 예를 들어 amount 값이 335.50이고 usage 값이 34이면 잔액은 다음과 같이 계산됩니다.

amount(335.50) - usage(34) = 229.50

API를 사용하여 선불 계정 잔액 보기

다음 섹션에서는 API를 사용하여 개발자 또는 회사의 선불 계정 잔액을 확인하는 방법을 설명합니다.

개발자의 선불 계정 잔액 보기

개발자의 선불 계정 잔액을 보려면 다음 API 중 하나에 GET 요청을 실행합니다. 여기서 {developer_id}는 개발자의 이메일 주소입니다.

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: 개발자의 선불 계정 잔액 및 반복 설정 정보를 반환합니다.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: 현재 및 총 잔액, 사용량, 충전, 사용세를 비롯한 선불 계정 잔액 정보를 반환합니다.

다음 쿼리 매개변수를 전달하여 결과를 필터링할 수 있습니다.

예를 들면 다음과 같습니다.

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

다음은 응답의 예시입니다.

{
    "developerBalance": [
        {
            "amount": 2005,
            "chargePerUsage": false,
            "id": "your-provider-id",
            "isRecurring": false,
            "supportedCurrency": {
                "description": "United States Dollars",
                "displayName": "United States Dollars",
                "id": "usd",
                "name": "USD",
                "organization": {
                    "address": [
                        {
                            "address1": "10 Almaden Blvd.",
                            "city": "San Jose",
                            "country": "US",
                            "id": "32e808d8-3a3c-4d76-a0ae-17d70a982c61",
                            "isPrimary": true,
                            "state": "CA",
                            "zip": "95113"
                        }
                    ],
                    "approveTrusted": false,
                    "approveUntrusted": false,
                    "billingCycle": "CALENDAR_MONTH",
                    "country": "US",
                    "currency": "USD",
                    "description": "my-org",
                    "groupOrganization": false,
                    "hasBillingAdjustment": false,
                    "hasBroker": false,
                    "hasSelfBilling": false,
                    "hasSeparateInvoiceForProduct": false,
                    "id": "my-org",
                    "issueNettingStmt": false,
                    "name": "my-org",
                    "nettingStmtPerCurrency": false,
                    "selfBillingAsExchOrg": false,
                    "selfBillingForAllDev": false,
                    "separateInvoiceForFees": false,
                    "status": "ACTIVE",
                    "supportedBillingType": "BOTH",
                    "taxModel": "HYBRID",
                    "timezone": "UTC"
                },
                "status": "ACTIVE",
                "virtualCurrency": false
            },
            "usage": 2.1572
        }
    ],
    "totalRecords": 1
}

회사의 선불 계정 잔액 보기

회사의 선불 계정 잔액을 보려면 /mint/organizations/{org_name}/companies/{company_id}/developer-balances에 GET 요청을 실행합니다. 여기서 {company_id}은 회사의 ID입니다. 회사가 선불인 경우 요청은 현재 선불 계정 잔액을 가져옵니다. 회사가 후불인 경우 요청은 현재 신용 한도를 검색합니다.

다음 쿼리 매개변수를 전달하여 결과를 필터링할 수 있습니다.

예를 들면 다음과 같습니다.

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

응답은 개발자의 선불 계정 잔액을 확인할 때 위에 표시된 응답과 유사합니다.

결제 시스템 공급자를 통해 선불 계정 잔액 관리

Worldpay와 같은 서드 파티 결제 제공업체에서 판매자 계정을 설정하여 선불 계정 잔액을 관리합니다. 다음 그림은 Worldpay 결제 제공업체를 사용하여 선불 계정 잔액을 관리하는 방법을 보여줍니다.

다음 표에서는 위의 선불 계정 잔액 관리 흐름의 각 단계를 설명합니다.

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

다음 섹션에서는 서드 파티 결제 제공업체를 사용하여 선불 잔액을 관리하는 데 필요한 단계를 설명합니다.

• Worldpay 결제 제공업체로 판매자 계정 설정
• Edge에서 결제 제공업체 구성하기
• 조직에 구성된 결제 제공업체 보기
• 개발자 포털에서 필수 모듈 사용 설정 및 구성
• 결제 제공업체를 사용하여 선불 계좌에 대한 결제 시작
• API를 사용하여 선불 계정 잔액 재충전
• 서드 파티 결제 제공업체 삭제하기

Worldpay 결제 제공업체에서 판매자 계정 설정하기

시작하기 전에 서드 파티 결제 제공업체(Worldpay)에 문의하여 판매자 계정을 설정해야 합니다. 테스트용 계정과 프로덕션용 계정 등 두 개의 계정을 설정하는 것이 좋습니다. Worldpay 판매자 계정에 대한 자세한 내용은 www.worldpay.com 및 wp-support.crm.worldpay.com (Worldpay 지원 센터)을 참고하세요.

판매자 계정을 설정하고 계정 사용자 인증 정보를 받은 후 Worldpay로 판매자 계정을 구성하려면 다음 단계를 따르세요.

1. https://secure.worldpay.com/sso/public/auth/login.html로 이동합니다.
2. Worldpay에서 제공한 사용자 인증 정보를 사용하여 Worldpay 계정에 로그인합니다.
3. XML 비밀번호 및 메시지 인증 코드 (MAC) 보안 비밀 키를 설정합니다.
   1. 프로필을 클릭합니다.
   2. Edge에서 Worldpay 결제 제공업체를 구성할 때 사용할 비밀번호를 XML 비밀번호 필드에 설정합니다.
   3. MAC 보안 비밀 리디렉션 필드에 20~30자 길이의 MAC 보안 비밀 키를 입력합니다.
   4. 프로필 저장을 클릭합니다.
4. Apigee Edge 관리 서버를 판매자 IP 목록 (허용 목록)에 추가합니다.
   1. 프로필 > 판매자 환경을 클릭합니다.
   2. 새 테스트 IP를 클릭합니다.
   3. Apigee Edge 관리 서버의 IP를 입력하세요.
   4. 저장을 클릭합니다.
5. 메서드 인증 코드 (MAC)를 비롯한 Worldpay 매개변수를 추가하도록 판매자 URL을 구성합니다.
   1. 설치 > 호스팅된 결제 페이지 > 결제 페이지 디자이너를 클릭합니다.
   2. 결제 페이지 수정에서 채널 선택 드롭다운 목록에서 설치 ID를 선택합니다.
   3. '속성' 탭에서 판매자 구성 수정을 선택합니다.
   4. Send URL 매개변수 값을 True로 설정합니다.
   5. 게시 탭을 클릭합니다.
   6. 다음과 같이 변경사항을 승격합니다.
      • 테스트 환경의 경우 Design에서 Promote를 클릭하여 Design에서 Sandbox로 승격합니다.
      • 프로덕션 환경의 경우 Sandbox 아래에서 Promote를 클릭하여 샌드박스에서 프로덕션으로 승격합니다.

Edge에서 결제 시스템 공급자 구성

다음 단계는 Edge에서 결제 제공업체를 구성하는 것입니다.

다음 API를 사용하여 특정 조직의 결제 제공업체를 구성할 수 있습니다.

/organizations/{org-name}/providers

시스템 관리자 권한이 있는 Apigee Edge Private Cloud 고객만 다음 API를 사용하여 글로벌 결제 제공업체를 구성할 수 있습니다(선택사항).

/config/providers

각 API를 호출할 때 요청 본문에 다음 정보를 지정해야 합니다.

예를 들어 다음은 Worldpay-myorg라는 이름의 Worldpay 판매자 계정을 설정합니다.

$ curl  -H "Content-Type:application/json" -X POST -d \
'{
    "name": "Worldpay-myorg",
    "description": "Worldpay payment provider",
    "endpoint": "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "authType": "123456",
    "credential": "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "merchantCode": "myMerchantCode"
  }' \
"https://api.enterprise.apigee.com/v1/organizations/myOrg/providers" \
-u email:password 

서드 파티 결제 제공업체 보기

다음 리소스에 GET 요청을 실행하여 Edge 조직에 구성된 서드 파티 결제 제공업체를 확인합니다.

/mint/organizations/{org-name}/providers

예를 들어 다음은 현재 myorg에 구성된 서드 파티 결제 시스템 공급자를 보여줍니다.

$ curl  -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers" \
-u email:password

다음은 테스트용 및 프로덕션용, 이렇게 두 개의 판매자 계정을 보여주는 응답의 예시입니다.

{
  "provider" : [ {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-myorg",
    "merchantCode" : "MERCH_CODE",
    "name" : "Worldpay-myorg"
  }, {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-test",
    "merchantCode" : "MERCH_CODE_FROM_PROVIDER",
    "name" : "Worldpay-test"
  } ]
}

개발자 포털에서 수익 창출 및 Worldpay 모듈 사용 설정 및 구성

개발자 포털에서 필요한 수익 창출 및 Worldpay 모듈을 사용 설정합니다. 자세한 내용은 개발자 포털에서 수익 창출 구성을 참고하세요.

결제 제공업체를 사용하여 선불 계정으로 결제 시작

선불 계정 관리 흐름의 2단계에 표시된 대로 API 소비자가 다음과 같은 경우 개발자 포털에서 결제 제공업체를 사용하여 선불 계정에 대한 결제를 시작합니다.

• 요금제를 수락하지만 선불 계정의 잔액이 부족한 경우
• 선불 계정에 금액을 추가해 달라고 요청합니다.

API를 사용하여 서드 파티 결제 제공업체에서 결제를 시작하려면 다음 리소스에 대한 POST 요청을 실행합니다. 여기서 {developer_id}는 개발자의 이메일 주소입니다.

/mint/organizations/{org_name}/developers/{developer_id}/payment?amount={amount}&provider={providerId}&supportedCurrencyId={currency}

요청을 실행할 때 다음 값을 쿼리 매개변수로 지정해야 합니다.

• 선불 계정 잔액에 추가할 금액 (amount={amount})
• 결제 서비스 제공업체 ID (provider={providerId})
• 지원되는 통화 (supportedCurrencyId={currency})

또한 회사 청구서 주소와 같은 기본 계정 세부정보를 전달해야 합니다.

예를 들어 다음은 Worldpay 결제 제공업체를 사용하여 선불 계정 잔액을 다시 로드합니다. 선불 계정으로 최초 이체는 미화 10달러입니다(amount 쿼리 매개변수가 10(으)로 설정됨).

$ curl  -H "Content-Type:application/xml" -X POST -d \
'{
    "address1": "5115 Hopyard Ave.",
    "city": "Pleasanton",
    "country": "US",
    "state": "CA",
    "zip": "58158"
}'
' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/payment?amount=10&provider=worldpay-myorg&supportedCurrencyId=usd" \
-u email:password

다음은 응답의 예시입니다.

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

Worldpay Secure Payment 페이지의 URL은 고유한 주문 키가 쿼리 매개변수로 추가된 상태로 referenceUrl에서 반환됩니다.

API를 사용하여 선불 계정 잔액 재충전

선불 계정 관리 흐름의 15단계에 표시된 대로 개발자 포털은 결제 제공업체에서 처리를 완료했음을 확인한 후 Edge에 선불 계정을 새로고침하라는 요청을 보냅니다.

다음 섹션에 설명된 대로 개발자 또는 회사의 API를 사용하여 선불 계정 잔액을 다시 로드할 수 있습니다.

개발자의 선불 계정 잔액 재로드

API를 사용하여 개발자의 선불 계정 잔액을 다시 로드하려면 /mint/organizations/{org_name}/developers/{developer_id}/developer-balances에 POST 요청을 실행합니다. 여기서 {developer_id}은 개발자의 이메일 주소입니다. 요청을 실행할 때는 요청 본문에서 잔액에 추가할 금액과 사용된 통화를 지정해야 합니다.

예를 들어 다음 요청은 개발자의 선불 계정 잔액에 1, 000달러를 추가합니다.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

요청 속성에 대한 설명은 선불 충전 계정 재충전 요청 속성 요약을 참고하세요.

회사의 선불 계정 잔액 재충전

API를 사용하여 회사의 선불 계정 잔액을 다시 로드하려면 /mint/organizations/{org_name}/companies/{company_id}/developer-balances에 POST 요청을 실행합니다. 여기서 {company_id}은 회사의 ID입니다. 요청을 실행할 때는 요청 본문에서 잔액에 추가할 금액과 사용된 통화를 지정해야 합니다.

예를 들어 다음 요청은 회사의 선불 계정 잔액에 1, 000달러를 추가합니다.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

요청 속성에 대한 설명은 선불 충전 계정 재충전 요청 속성 요약을 참고하세요.

선불 계정 재충전을 위한 요청 속성 요약

API를 사용하여 선불 계정 잔액을 새로고침할 때 다음 속성을 지정해야 합니다.

서드 파티 결제 제공업체 삭제

다음 리소스에 대해 DELETE 요청을 실행하여 Edge 조직에 구성된 서드 파티 결제 제공업체를 삭제할 수 있습니다.

특정 조직의 결제 제공업체를 삭제하려면 다음 API를 사용하세요.

/mint/organizations/{org-name}/providers/id

시스템 관리자 권한이 있는 Apigee Edge 프라이빗 클라우드 고객만 해당은 원하는 경우 다음 API를 사용하여 글로벌 결제 시스템 공급자를 삭제할 수 있습니다.

/config/providers/id

예를 들어 다음은 현재 myorg에 구성된 서드 파티 결제 제공업체를 삭제합니다.

$ curl  -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers/worldpay-myorg" \
-u email:password

선불 계정 잔액 수동 관리

또는 API를 사용하여 선불 계정 잔액 다시 로드에 설명된 대로 수동으로 또는 통합 결제 시스템을 통해 결제를 추적하고 수익 창출 API를 호출하여 계정을 다시 로드하는 방식으로 선불 잔액의 재충전을 관리할 수 있습니다.

API를 사용하여 선불 계정 잔액 자동 충전 설정

다음 섹션에서는 서드 파티 결제 시스템 공급자를 사용하는 개발자 또는 회사의 선불 계정 잔액 자동 충전을 설정하는 방법을 설명합니다. 이 옵션은 요금제의 정기 결제를 관리하는 데 유용합니다.

개발자의 선불 계정 잔액 자동 재충전 설정

잔액이 특정 기준점 아래로 떨어지면 개발자의 선불 계정 잔액을 자동으로 재충전하도록 설정하려면 /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup에 POST 요청을 실행합니다. 여기서 {developer_id}은 개발자의 이메일 주소입니다.

요청을 실행할 때 다음을 지정해야 합니다.

• 계정을 새로고침하는 데 사용할 결제 시스템 공급자의 ID (providerID)입니다.
• 자동 새로고침을 사용 설정하는 플래그 (isRecurring)
• 자동 재충전을 트리거하기 위해 선불 계정 잔액이 아래로 떨어져야 하는 기준액 (replenishAmount)
• 계정에 자동으로 추가할 금액 (recurringAmount)
• supportedCurrencyID 쿼리 매개변수로 통화를 지정합니다.

다음 예에서 개발자의 선불 계정 잔액이 5달러(USD) 미만으로 떨어지면 미화 10달러가 계정에 자동으로 추가됩니다.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

요청 속성에 관한 설명은 선불 계정의 자동 재충전 설정을 위한 요청 속성 요약을 참고하세요.

회사의 선불 계정 잔액 자동 충전 설정

잔액이 특정 금액 미만이 되었을 때 회사의 선불 계정 잔액이 자동으로 충전되도록 설정하려면 /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup에 POST 요청을 실행하세요. 여기서 {company_id}는 회사 ID입니다.

요청을 실행할 때 다음을 지정해야 합니다.

• 계정을 충전하는 데 사용할 결제 제공업체의 ID (providerID)
• 자동 새로고침을 사용 설정하는 플래그 (isRecurring)
• 자동 새로고침을 트리거하려면 선불 계정 잔액이 아래로 감소해야 하는 기준 (replenishAmount)
• 계정에 자동으로 추가할 금액 (recurringAmount)
• supportedCurrencyID 쿼리 매개변수로 통화를 지정합니다.

다음 예에서는 회사의 선불 계정 잔액이 미화 5달러 미만으로 떨어지면 계정에 미화 10달러가 자동으로 추가됩니다.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

요청 속성에 관한 설명은 선불 계정의 자동 새로고침 설정을 위한 요청 속성 요약을 참고하세요.

선불 계정의 자동 재충전 설정을 위한 요청 속성 요약

API를 사용하여 선불 계정 잔액을 자동으로 재충전할 때 다음 속성을 지정할 수 있습니다.

WorldPay의 호스팅 결제 페이지로 이전

호스팅 결제 페이지라고 하는 새로운 페이지 세트를 사용하도록 WorldPay의 보안 결제 처리 흐름이 업데이트되었습니다.

지원 중단된 보안 결제 처리 흐름(2017년 8월 이전)을 사용하여 WorldPay 결제 제공업체를 구성한 경우 2018년 1월 이전에 WorldPay의 새 호스팅 결제 페이지로 이전해야 합니다.

WorldPay의 호스팅 결제 페이지로 이전하려면 다음 단계를 따르세요.

1. WorldPay에 문의하여 새 호스팅 결제 페이지를 사용하도록 현재 계정을 이전하고 계정의 새 설치 ID를 받습니다.
2. Edge에서 결제 제공업체 구성에 설명된 대로 새 WorldPay 결제 제공업체를 구성하고 authType 필드에 설치 ID를 전달합니다.
3. 개발자 포털에서 수익 창출 구성에 설명된 대로 개발자 포털에서 새 결제 제공업체를 구성합니다.
4. 결제 제공업체를 통해 선불 계정의 자동 새로고침을 설정하면 API를 사용하여 선불 계정 잔액의 자동 새로고침 설정에 설명된 대로 새 제공업체 ID를 사용하도록 자동 새로고침을 다시 구성해야 합니다.

다음 단계

개별 후불 개발자에 대한 신용 한도를 설정할 수 있습니다. 후불 잔액 관리에서 방법을 알아보세요.