# 포인트 전환

## 연동 순서

1\. 영업 담당자와 포인트 전환에 사용에 대한 설정 요청

2\. 포인트 전환에 사용될 단위/환율 협의

3\. 포인트 전환에 사용될 아이템 코드 발급

4\. 클라이언트 및 서버 연동

***

## 전환 관련 유저 서비스 플로우

<figure><img src="https://764858488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUcr5cFWxwR8mzZgUD30Y%2Fuploads%2F8TLsrEUdkZvXeyWefVZw%2Fb410810-image.png?alt=media&#x26;token=55a95b1d-0d47-478d-90b5-3469ed6d3411" alt=""><figcaption></figcaption></figure>

***

## 전환 프로세스

{% hint style="info" %}
**요청ID == transactionID**
{% endhint %}

<figure><img src="https://764858488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUcr5cFWxwR8mzZgUD30Y%2Fuploads%2FsPRiQBlYgqUsV8gJjk6s%2F87e0ac6-image.png?alt=media&#x26;token=1ed67993-4a0a-471c-a322-57a0246c6dca" alt=""><figcaption></figcaption></figure>

***

## Client

[#undefined-6](https://avatye.gitbook.io/buzzvil/initialize#undefined-6 "mention")

{% hint style="info" %}
&#x20;전환 기능을 사용하기 위한 초기화 과정 (Application)

***

1. 캐시버튼 초기화 옵션 "setCashExchangeListener" 설정
2. setCashExchangeListener::onRequestExchange(transactionID) → **transactionID**를 전달 받는다.
3. **transactionID** 를 요청 파라미터에 담아 **HostApp-Server**로 전환요청을 한다.
4. 전환 성공/실패 여부를 \*\* CashButtonExchangeConfig.onCompleted()\*\* 함수를 사용하여 전달해준다.
   {% endhint %}

```kotlin
/** 
* 포인트전환
* 1. setCashExchangeListener API 를 이용하여 transactionID(요청ID)를 전달받는다.
* 2. transactionID 를 요청 파라미터에 담아 HostApp-Server로 전환요청을 한다.
* 3. 전환 성공/실패 여부를 CashButtonExchangeConfig.onCompleted() 함수를 사용하여 전달
*/

class App : Application() { 
  override fun onCreate() {
    super.onCreate()
    val initSDK = CashButtonSDK() or CashScreenSDK() or PublisherSDK()
    initSDK.setCashExchangeListener(object : ICashExchangeListener{
      override fun onRequestExchange(transactionID: String) {
        // 1.HostApp-Server로 전환요청
        // 2. 성공 시  CashButtonExchangeConfig.onCompleted(true)
        // 2. 실패 시	CashButtonExchangeConfig.onCompleted(false, failureEntity.responseDescription);
      }
    })
    
    initSDK.build(listener = object : CashButtonSDK.IResultListener {
      override fun onSuccess() {
        // Build Completed
      }
      
      override fun onFailure(reason: String) {
        // Build Failed
      }
    })
  }  
}
```

***

## Server

### 검증(Verify Transaction)

{% hint style="warning" %}
**성공여부를 반드시 호출되어야 다음화면으로 진행됩니다.**
{% endhint %}

## 캐시전환시 발급한 요청ID를 검증합니다.

<mark style="color:orange;">`PUT`</mark> `https://api.reward.avatye.com/shop/exchange/rollbackV2`&#x20;

**검증 성공 시, 결과로 상품ID(exchangeItemID)를 반환합니다.**

해당 상품 ID에 해당하는 금액을 해당 서비스의 재화로 적립 후, 캐시버튼 SDK에 성공여부를 응답합니다.

상품ID는 캐시버튼 담당자로부터 전달받을 수 있습니다

#### Headers

| Name                                            | Type   | Description          |
| ----------------------------------------------- | ------ | -------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json     |
| Authorization<mark style="color:red;">\*</mark> | String | Basic Token (사전 전달 ) |

#### Request Body

| Name                                            | Type   | Description          |
| ----------------------------------------------- | ------ | -------------------- |
| transactionID<mark style="color:red;">\*</mark> | String | 캐시버튼 SDK에서 전달받은 요청ID |

{% tabs %}
{% tab title="200: OK 통신 성공(resultCode값으로 결과 분기)" %}
기본적인 성공 및 실패 응답은 모두 200으로 반환되며, 반환 값 "**resultCode**"를 통해 결과 분기합니다.&#x20;

**검증이 성공("0000")**&#xD55C; 경우에만 서비스의 재화를 지급해야 합니다. 이 후, 성공 및 실패 여부를 캐시버튼 SDK에 전달합니다.

```json
//resultCode가 "0000"일 경우, exchangeItemID 값이 제공됩니다.
{  
    resultCode: “0000”,  
    exchangeItemID: “dae1027a7bbc4eeeb56163427d1447a3“,  
    extraData: {}  
}
```

{% endtab %}

{% tab title="500: Internal Server Error 전환 실패" %}
캐시버튼 서버에서 분류되지않은 에러 발생 시, status code 500을 반환합니다.&#x20;

해당 에러 발생 시, 담당자에게 문의 부탁드립니다.
{% endtab %}
{% endtabs %}

<details>

<summary>Response(응답값:ResultCode)</summary>

***

* 0000 :  성공
* 9000 : 잘못된 요청ID(담당자 문의 필요)
* 9001 : 이미 실패 처리된 요청
* 9002 : 이미 검증된 요청(해당 요청ID로 이미 검증요청 및 확인완료)
* 9003 : 상품이 이용할 수 없는 상태(ex:판매중지)인 경우
* 9004 : 잔액부족등의 이유로 사용자의 캐시를 차감이 불가한 경우

</details>

***

### 취소(Rollback)

## 캐시전환을 취소합니다.

<mark style="color:orange;">`PUT`</mark> `https://api.reward.avatye.com/shop/exchange/rollbackV2`&#x20;

검증이 성공했지만, 서비스내의 재화에 적립을 할 수 없는 경우, 캐시전환 취소를 호출합니다.\
사용자는 검증과정에서 캐시버튼의 캐시를 이미 사용 했기때문에, 캐시전환이 실패할 경우 해당 API를 호출함으로써, 사용자가 사용한 캐시를 복원합니다.

#### Headers

| Name                                            | Type   | Description          |
| ----------------------------------------------- | ------ | -------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json     |
| Authorization<mark style="color:red;">\*</mark> | String | Basic Token (사전 전달 ) |

#### Request Body

| Name                                            | Type   | Description          |
| ----------------------------------------------- | ------ | -------------------- |
| transactionID<mark style="color:red;">\*</mark> | String | 캐시버튼 SDK에서 전달받은 요청ID |

{% tabs %}
{% tab title="200: OK 통신 성공(resultCode값으로 결과 분기)" %}
응답 값의 resultCode 필드로 성공여부를 확인할 수 있습니다.

응답 값은 고객지원 시 참고용으로 사용되며 이 후, 추가 프로세스는 없습니다.
{% endtab %}

{% tab title="500: Internal Server Error 실패" %}
캐시버튼 서버에서 분류되지않은 에러 발생 시, status code 500을 반환합니다.

해당 에러 발생 시, 담당자에게 문의 부탁드립니다.
{% endtab %}
{% endtabs %}
