<a id="ios_iap"></a>

# iOS in-app purchase

## Overview

In-App Purchase mechanism in iOS apps can be divided into two steps:

1. Purchase of the item at App Store
2. Verify purchase confirmation from Apple by provider and deliver the purchased item

For the first step, the in-app purchase items must be filled in at iTunes Connect portal, including their description,
prices etc. Each such in-app purchase item will have a unique identifier. Comma-separated list of these unique
identifiers must be filled in at Cloud Softphone portal, the app will then fetch the rest of data from iTunes Connect.

When the user makes a successful purchase, the Cloud Softphone app receives a confirmation receipt from Apple. Cloud
Softphone then calls a web service on provider side and passes the receipt to it.

This starts the second step. Provider should validate the receipt by Apple to make sure it's backed by a real purchase.
The API to validate receipts is documented by [Apple](https://developer.apple.com/library/ios/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html).

!!! note
    There are also code snippets and libraries for various languages available on internet which may be more explanatory,
    like:

    - [for PHP](https://github.com/chrismaddern/iOS-Receipt-Validator-PHP)
    - [for Python](https://pypi.python.org/pypi/itunes-iap)

After the receipt is found valid, the script should deliver the purchased item (enable a service, add calling credit
etc).

The web service has to be configured at Cloud Softphone web portal.

## Parameters

Parameter templates for iOS in-app purchase web service can use any variables from [global](../reporting/intro.md#global-params) and
[account](../reporting/intro.md#account-params) scopes. There are also some web-service specific parameters:

### `receipt` { .reference-entry }

This parameter will be replaced by base64 encoded receipt received from Apple. This is the receipt which needs to be
validated.

### `price` { .reference-entry }

The price the user has paid for the in-app purchase item.

### `currency` { .reference-entry }

The currency in which the purchase was made.

### `productCode` { .reference-entry }

The unique identifier of the in-app purchase item which has been purchased.

## Configuration

The web service is configured in Cloud Softphone web portal. The following fields may be filled in:

### `iapWsUrl` { .reference-entry }

Contains the URL, including URL scheme, of the web service, possibly also with query string.

Example (with query-string):

```
https://example.com/iap_validate/?username=%account[username]%&receipt=%receipt%&product=%productCode%
```

### `iapWsPostData` { .reference-entry }

If filled in, the app will use POST request to validate the receipt.

Example (for application/x-www-form-urlencoded):

```
username=%account[username]%&receipt=%receipt%&product=%productCode%
```

Example (for application/json):

```json
{ "username" : "%account[username]%" , "receipt" : "%receipt%" , "product" : "%productCode%" }
```

### `iapWsContentType` { .reference-entry }

Specifies the value of Content-Type header to be sent in POST request. If not specified, the app will default to
`application/x-www-form-urlencoded`

## Response

The response will be considered successful if the HTTP response code is 2xx. For any responses which have other
response code, or whose body can't be parsed, an error message is shown to the user.

`Content-type` header of the response specifies the format of the body. The following Content-Types are supported:

- application/xml (**default**)
- application/json
- application/x-www-form-urlencoded

The following fields in the response are recognized:

<a id="iap-final"></a>

### `final` { .reference-entry }

This parameter **MUST** be included in the response body for both success (2xx) and failure (non-2xx) cases, with a
value of `1`. Examples:

- JSON / form-encoded: `"final": "1"`
- XML: `<final>1</final>`

The presence of `final=1` indicates that the provider has completed handling of the request and the app can finish
the purchase flow.

<a id="iap-message"></a>

### `message` { .reference-entry }

This parameter should be included in case the web service returns non-2xx response code. The contents of this
parameter will be shown to the user.

## Examples

### GET method, XML

request:

```http
GET /iap_validate/?username=johndow&product=credit5&receipt=TG9yZW0gSXBzdW0gRG9sb3IgU2l0IEFtZXQ= HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
```

response:

```http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 21
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/xml

<root>
    <final>1</final>
</root>
```

### POST method, JSON

request:

```http
POST /iap_validate/ HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
Content-Length: 183
Content-Type: application/json
User-Agent: CloudSoftphone/1.5.6

{
  "username" : "johndow",
  "product"  : "credit5",
  "receipt"  : "TG9yZW0gSXBzdW0gRG9sb3IgU2l0IEFtZXQ="
}
```

response:

```http
HTTP/1.1 403 Forbidden
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Content-Length: 183
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/json

{
    "final" : "1",
    "message" : "Failed to validate your purchase with App Store"
}
```