# Payment Processing

Payment Processing can be handled directly via nexxOMNIA or via a Third-Party Platform. In the first Case, the Frontend must handle the Internal API Methods. If everything is handled via another Operator, the Frontend can just use the "**addexternalsubscription**" Operation (possible even via Backend).

In both Cases, Subscriptions can be managed afterwards.

## Internal Payment Management

## /itemstate

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/itemstate`

#### Query Parameters

| Name                         | Type    | Description                                                                                                     |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| item                         | integer | the Media ID                                                                                                    |
| streamtype                   | string  | the Media Streamtype                                                                                            |
| performTransactionIfPossible | boolean | if set to 1, and the User can watch the Item (for example via Subscription), automatically register this "buy". |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## /redeemvoucher

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/redeemvoucher`

The Methods needs "vouchercode" OR "referencecode" to be valid and set - not both.

#### Query Parameters

| Name          | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| vouchercode   | string | the given Voucher Code             |
| referencecode | string | the ID of an external Voucher Code |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## /preparetransaction

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/preparetransaction`

#### Query Parameters

| Name                           | Type    | Description                                                                                             |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------- |
| operation                      | string  | the Type of Transaction  \[subscription, ppv, ownage, deposit,...]                                      |
| item                           | number  | the Media ID (not applicable on all Contexts)                                                           |
| streamtype                     | string  | the Media Streamtype (not applicable on all Contexts)                                                   |
| reference                      | string  | in Case the Provider already returned a Transaction Reference                                           |
| amount                         | number  | the Amount of Money for this Operation (in the Subunit of the Currency (for example - Cents for Euro))  |
| currency                       | string  | the used Currency                                                                                       |
| provider                       | string  | 3Q nexx Code for the Provider Type                                                                      |
| paymentType                    | string  | 3Q nexx Code for the Payment Type (for exmaple "creditcard") (can also be defined later)                |
| affiliateParam                 | string  | If the Operation is driven by an Affiliate Partner, add the Parameter to store it for later Processing. |
| subscriptionDuration           | number  | Subscription Duration (in Months)                                                                       |
| subscriptionIsPremium          | boolean | Default or Premium Subscription                                                                         |
| subscriptionWillRenew          | boolean | will the Subscription renew automatically                                                               |
| subscriptionCanRenew           | boolean | can the Subscription be renewed after Expiry                                                            |
| subscriptionWillBePayedMonthly | boolean | will the Subscription be payed every Month or in full upfront.                                          |
| capturePaymentOn               | number  | if the Payment is for a Trial Phase, capture the Money on the given Timestamp                           |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## /finishtransaction

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/finishtransaction`

#### Query Parameters

| Name                         | Type    | Description                                                                                                                        |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| transactionID                | number  | the Transaction ID from the **preparetransaction** Method                                                                          |
| token                        | string  | the used Payment Security Token                                                                                                    |
| reference                    | string  | the Payment Provider Transaction ID                                                                                                |
| paymentType                  | string  | the Type of Payment (if not set before)                                                                                            |
| finalPayment                 | number  | the finally payed Price (could be different from the Start due to Payment Specials)                                                |
| isLatePremium                | boolean | the Subscription is a Premium Subscription (this could have been upgraded during the Payment Process)                              |
| externalUserID               | string  | the User Reference of the Payment Provider                                                                                         |
| externalTransactionReference | string  | the Reference of the nexxOMNIA Transaction for the Payment Provider, if its Design needs a different Type of Transaction Reference |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## /verifyinapptransaction

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/verifyinapptransaction`

inApp Payment cannot be handled by the usual prepare/finish Approach and needs therefore be treated differently.

#### Query Parameters

| Name             | Type    | Description                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| operation        | string  | the Type of Transaction  \[subscription, ppv, ownage, deposit,...]                                     |
| item             | number  | the Media ID (not applicable on all Contexts)                                                          |
| streamtype       | string  | the Media Streamtype (not applicable on all Contexts)                                                  |
| provider         | string  | 3Q nexx Code for the Provider  \[io, go, am]                                                           |
| amount           | number  | the Amount of Money for this Operation (in the Subunit of the Currency (for example - Cents for Euro)) |
| currency         | string  | the used Currency                                                                                      |
| amount\_original | number  | the Amount, as given by the App Store                                                                  |
| isPremium        | boolean | the Subscription will be Default or Premium                                                            |
| receipt          | string  | the App Store Receipt (as encoded JSON) for Serverside Verification                                    |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## External Payment Management

## /addexternalsubscription

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/addexternalsubscription`

will add a Subscription to a given User. The target User must have been registered also externally. This Call is only needed if User- and Payment Management are handled outside of nexxOMNIA.

#### Query Parameters

| Name       | Type    | Description                                                                    |
| ---------- | ------- | ------------------------------------------------------------------------------ |
| validUntil | number  | Timestamp for the Period, nexxOMNIA should consider the Subscription as active |
| isPremium  | boolean | Default/Premium Subscriptio                                                    |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Subscription Lifecycle Management

## /upgradesubscription

<mark style="color:green;">`POST`</mark> `https://api.nexx.cloud/v3.1/payment/upgradesubscription`

will replace the current Default Subscription into a Premium Subscripion (without changing the Timings of this Subscription)

#### Query Parameters

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| transactionID | string | the Transaction ID for the additional Payment of the Payment Provider |
| amount        | number | the Costs for this Upgrade                                            |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## /cancelsubscription

<mark style="color:red;">`DELETE`</mark> `https://api.nexx.cloud/v3.1/payment/cancelsubscription`

#### Query Parameters

| Name              | Type    | Description                                                                                                                                                                                                                      |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| transactionID     | number  | the ID of the original Transaction                                                                                                                                                                                               |
| cancelTransaction | boolean | if set to 1, the complete Transaction will be deleted - this should only happen, if the original Transaction itself failed during Processing. In all other Cases, this Value should be 0 (=the Subscription wont extend anymore) |
| skipEmail         | boolean | if set to 1, nexxOMNIA wont send a Confirmation Email                                                                                                                                                                            |
| reasonText        | string  | an optional Reason for this Cancelation (entered by the User)                                                                                                                                                                    |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.docs.nexx.cloud/frontend-api/endpoints/payment-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.