==== 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.
User needs to be logged in on DVIP before this API call is executed.
==== 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:*`
(* - details about no_pay_event)
Error happens 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.
Support ticket will be created for further investigation.
In user cannot be promoted DVIP will return ERROR response status to Mobile App.
`api_call_to_payment_failed:*`
(* - payment api response code)
Error happens when API call from DVIP to Payment App fails. Usually, due to bad payment data from the App Store (invalid receipt etc.).
User will be promoted if possible and if promotion succeeds DVIP will return OK response status to Mobile App.
Support ticket will be created for further investigation.
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 nor is support ticket created.
`api_call_to_payment_failed_and_strict_mode:*`
(* - payment api response code)
Error happens when API call to Payment App fails and `strict` param is set.
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 (value of response field `meta->status` OK or ERROR), all encountered errors are set in field `result->data->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