==== Description
Api call used to record purchases from Mobile App on DVIP and Payment systems.
Purchase already happens on Mobile App part (on Apple store or Google store).
This call sets up state on Payment App and DVIP, so that the user benefits are active.
Since purchase already happened when this call is made, DVIP tries to make this call succeed, even in case of some errors.
==== Errors
If there are errors they are always included in response's 'encountered_errors' field.
If API call fails they are also added to response status using `Errors::add()`.
`no_pay_event_*`
This can happen when there is no payment happening - due to user already being Premium / PremiumPlus access, or when API request is incomplete and does not contain purchased items.
User will be promoted if possible and if promotion succeeds DVIP will return OK response status to Mobile App.
In user cannot be promoted DVIP will return ERROR response status to Mobile App.
`api_call_to_payment_failed_*`
This error happens when API call from DVIP to Payment App fails. Usually, due to bad payment data from the App Store (receipt etc.).
In this case DVIP will try to give user PremiumPlus access and open a support ticket for further investigation and API response status is OK.
However, Mobile App can influence this with `strict` param (default `false`) - if this param is set error from Payment App is reported back to Mobile App and DVIP does not try to give user PremiumPlus.
`receipt_validation_failed_and_strict_mode_*`
This is error reported `strict` param is set and API call to Payment App fails.
In this case API response status to Mobile App is ERROR.
`no_purchased_pay_item_ids`
This error happens when API request does not contain purchased item id.
In this case DVIP cannot give user PremiumPlus and API response status to Mobile App is ERROR.
`failed_to_create_promotion_for_user`
Happens when promotion process fails (due to missing setup or incomplete/inconsistent user data).
In this case API response status to Mobile App is ERROR.
`payment_locked`
`pay_stage_not_ready`
Error in sessions on DVIP, should not happen.
-----
Above errors have usually been happening during testing with test users or during initial usage on new system or app.
==== API call response
If API call is processed successfully OR if there are errors, and DVIP 'fixes' them - response status is set to OK.
If API call fails AND DVIP cannot 'fix' encountered errors - response status is set to ERROR.
In any way (OK or ERROR), all encountered errors are set in field `encountered_errors` in API call response.
If status is ERROR - all encountered errors are added into API response using `Errors::add()` calls.
Support ticket is created on DVIP for all encountered errors (OK or ERROR status), except when Payment App returns errors 871 (PCODE_INT_API_INVALID_OPTION) or 694 (PCODE_IO_API_SUBSCRIPTION_EXPIRED) - these have happened during testing.
=== API call parameters
==== Ios
|Parameter|Description
| -- | --
|agent| Ios
|purchase_id| m1_3293_197_premium
|receipt-data| Receipt from Apple store (store param)
|currency| USD
|amount| 30.99
|strict| bool
==== GooglePlay
|Parameter|Description
| -- | --
|agent| GooglePlay
|purchase_id| m1_136_197_premium
|package_name| Package name (store param)
|purchase_type| Test transaction flag
|merchant_order_number| m1_136_197_premium
|purchase_token| Purchase token (store param)
|currency| USD
|amount| 30.99
|strict| bool