diff --git a/CHANGELOG.md b/CHANGELOG.md index e3b501e..7e53ffe 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/docs/openapi.yaml b/docs/openapi.yaml index b7e64b7..60aa0ca 100644 --- a/docs/openapi.yaml +++ b/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}$' diff --git a/recurring-api-guide.md b/recurring-api-guide.md index b21ee60..2d6e5de 100644 --- a/recurring-api-guide.md +++ b/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