# 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
`POST` `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
`POST` `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
`POST` `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
`POST` `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
`POST` `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
`POST` `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
`POST` `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
`DELETE` `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 %}