Merge pull request #412 from vippsas/hf-external-id

Add info about externalId

CHANGELOG.md

@@ -19,6 +19,11 @@ See:
 * Landing page update. Due to complexity of which price applies to an agreement, whether it's the agreement price, initial charge price, promotional price etc, the [landing page](https://developer.vippsmobilepay.com/docs/knowledge-base/landing-page/) will show agreement names instead of prices.
 
 
+## November 2023
+* Charge ``externalId``
+  * If specified, the ``externalId`` will be used as order id, meaning it will show up on settlement reports in place of the orderId-field.
+  * If both ``orderId`` and ``externalId`` are specified, the ``externalId`` will be used as order id, while orderId will just be used to identify the charge in the recurring api.
+
 ## October 2023
 
 * Fixes in the Recurring YAML file: 

docs/openapi.yaml

@@ -2881,7 +2881,8 @@ components:
             We recommend at least two days retry.
         orderId:
           type: string
-          maximum: 50
+          maxLength: 50
+          minLength: 1
           pattern: "^[a-zA-Z\\d-]+"
           example: acme-shop-123-order123abc
           description: |-
@@ -2893,9 +2894,10 @@ components:
         externalId:
           type: string
           description: |-
-            An optional external id for the charge
-            The `externalId` can be used by the merchant to map the `chargeId`
-            to an id in a subscription system or similar.
+            An optional external id for the charge, that takes the place of the `orderId` in settlement reports without overriding the default `chargeId`
+            The `externalId` can be used by the merchant to map the `chargeId` to an id in a subscription system or similar.
+            Note that while `orderId` must be unique per merchant, `externalId` does not have this limitation, 
+            so you need to avoid assigning the same `externalId` to multiple charges if you want to keep them separate in settlement reports.
           maxLength: 64
           minLength: 1
           pattern: '^.{1,64}$'

recurring-api-guide.md

@@ -226,7 +226,7 @@ The `orderId` replaces the `chargeId`.
 * The value of the `orderId` is used for all instances of `chargeId`
 * The `orderId` (and `chargeId`) is used for all subsequent identification
   of the charge.
-* The `orderId` is used in the settlement files.
+* The `orderId` is used in the settlement files if no `externalId` is specified.
 
 This `orderId` must be unique across all Recurring and eCom
 transactions for the given `merchantSerialNumber`.
@@ -787,9 +787,22 @@ Each specific charge on an agreement must be scheduled by the merchant.
 
 To create a charge use the [`POST:/recurring/v3/agreements/{agreementId}/charges`][create-charge-endpoint] endpoint.
 
-Also see check [Recommendations for `reference` and `orderId`](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid) before creating charges.
-
-For agreements of type `variable`, also see [Recurring agreements with variable amount](#create-charge).
+For agreements with `VARIABLE_AMOUNT` pricing, see [Recurring agreements with variable amount](#create-charge).
+
+>### `orderId` and `externalId`
+> The optional `orderId`-field will override the automatically generated `chargeId` for the charge if specified,
+> and will be used for all subsequent identification of the charge, and in settlement reports unless an `externalId` is specified.
+> 
+> The `externalId`-field is a more flexible alternative to `orderId` which does not override the `chargeId`, but will be used in settlement reports.
+> 
+> This means that if both `orderId` and `externalId` are specified, 
+> the `orderId` will override `chargeId` and be used for all subsequent identification of the charge, 
+> while the `externalId` will be used in settlement reports.
+> 
+> As `externalId` does not have the same requirements for uniqueness as `orderId`, 
+> it is important that you understand how this will impact your settlements before using it.
+> 
+> Also see [Recommendations for `reference` and `orderId`](https://developer.vippsmobilepay.com/docs/knowledge-base/orderid)
 
 #### Due date