POSTing multicurrency information

Whenever you POST a reserve or check, you must specify currency information. For a single-currency instance of ClaimCenter, all specified currencies must be the same. When multicurrency is enabled, the specified currencies can be different.

When a request payload contains multiple currency values, the specified currencies must meet any relevant validation criteria. For example, when creating a reserve, the claim currency does not need to match the reserve currency. But, the currency for each reserve line item must match the reserve currency. If these types of validation criteria are not met, Cloud API returns an error.

POSTing a reserve with multiple currencies

The following is an example of a request payload for a new reserve for claim cc:202. Although it is not evident from the payload, the claim currency for cc:202 is US Dollars (usd).

  • The reserving currency is Euros (eur).
  • The reserve transaction currency is Japanese yen (jpy).
POST http://localhost:8080/cc/rest/claim/v1/claims/cc:202/reserve-sets

{
  "data": {
    "attributes": {
      "reservesToWrite": [
        {
          "reserveLine": {
            "costCategory": {
              "code": "body"
            },
            "costType": {
              "code": "claimcost"
            },
            "exposure": {
              "id": "cc:SfXS3Pey0Al29PI13KC5C"
            },
            "reservingCurrency": {
              "code": "eur"
            }
          },
          "lineItems": [
            {
              "transactionAmount": {
                "amount": "100.00",
                "currency": "jpy"
              }
            }
          ],
          "currency": {
            "code": "jpy"
          }
        }
      ]
    }
  }
}
Java

POSTing a reserve with a custom exchange rate

To specify a custom exchange rate, use the transToReservingExchangeRate object. This specifies the rate to use when converting the transaction currency into the reserving currency. The object takes three fields:

  • An optional description string value.
  • A Boolean market value. (This identifies whether ClaimCenter uses the market rate populated by the ExchangeRateSetPlugin for this transaction or uses a new custom rate. If a custom exchange rate is being specified, set market to false.)
  • A decimal rate value.

The following is an example of a request payload for a new reserve for claim cc:202. Although it is not evident from the payload, the claim currency for cc:202 is US dollars (usd).

  • The reserving currency is US dollars (usd).
  • The reserve transaction currency is Canadian dollars (cad).
  • The custom exchange rate is 4.0 (The transaction amount is 300. Thus, this will be recorded as $300 CAD, which is equal to $1200 USD.)
POST http://localhost:8080/cc/rest/claim/v1/claims/cc:202/reserve-sets

{
  "data": {
    "attributes": {
      "reservesToWrite": [
        {
          "transToReservingExchangeRate": {
            "description": "Custom exchange rate",
            "market": false,
            "rate": "4.0"
          },
          "reserveLine": {
            "costCategory": {
              "code": "body"
            },
            "costType": {
              "code": "claimcost"
            },
            "exposure": {
              "id": "cc:SfXS3Pey0Al29PI13KC5C"
            },
            "reservingCurrency": {
              "code": "usd"
            }
          },
          "lineItems": [
            {
              "transactionAmount": {
                "amount": "300.00",
                "currency": "cad"
              }
            }
          ],
          "currency": {
            "code": "cad"
          }
        }
      ]
    }
  }
}
Java

POSTing a check set with multiple currencies

The following is an example of a check set payload for a new check set for claim cc:202. Although it is not evident from the payload, the claim currency for cc:202 is usd.

  • The reserving currency is British pounds (gbp).
  • The currency for the check (and any associated payment transaction) is Canadian dollars (cad).
POST http://localhost:8080/cc/rest/claim/v1/claims/cc:202/check-sets

{
  "data": {
    "attributes": {
      "primaryCheckToWrite": {
        "paymentsToWrite": [
          {
            "lineItems": [
              {
                "transactionAmount": {
                  "amount": "75.00",
                  "currency": "cad"
                }
              }
            ],
            "paymentType": {
              "code": "final"
            },
            "reserveLine": {
              "costCategory": {
                "code": "body"
              },
              "costType": {
                "code": "claimcost"
              },
              "exposure": {
                  "id": "cc:SfXS3Pey0Al29PI13KC5C"
              },
              "reservingCurrency": {
                "code": "gbp"
              }
            },
            "currency": {
              "code": "cad"
            }
          }
        ],
        "payees": [
          {
            "contact": {
              "id": "cc:Sr-RcOtnyAd2_TsoU4Szy"
            },
            "payeeType": {
              "code": "insured"
            }
          }
        ],
        "paymentMethod": {
          "code": "eft"
        }
      }
    }
  }
}
Java

POSTing a check set with a custom exchange rate

To specify a custom exchange rate, use the transToReservingExchangeRate object. This specifies the rate to use when converting the transaction currency into the reserving currency. The object takes three fields:

  • An optional description string value.
  • A Boolean market value. (This identifies whether ClaimCenter uses the market rate populated by the ExchangeRateSetPlugin for this transaction or uses a new custom rate. If a custom exchange rate is being specified, set market to false.)
  • A decimal rate value.

The following is an example of a request payload for a new reserve for claim cc:202. Although it is not evident from the payload, the claim currency for cc:202 is US Dollars (usd).

  • The reserving currency is British pounds (gbp).
  • The currency for the check (and any associated payment transaction) is Canadian dollars (cad).
  • The custom exchange rate is 0.5 (The transaction amount is 50. Thus, this will be recorded as $50 CAD, which is equal to $25 GPB.)
POST http://localhost:8080/cc/rest/claim/v1/claims/cc:202/reserve-sets

{
  "data": {
    "attributes": {
      "primaryCheckToWrite": {
        "paymentsToWrite": [
          {
            "lineItems": [
              {
                "transactionAmount": {
                  "amount": "50.00",
                  "currency": "cad"
                }
              }
            ],
            "paymentType": {
              "code": "partial"
            },
            "reserveLine": {
              "costCategory": {
                "code": "body"
              },
              "costType": {
                "code": "claimcost"
              },
              "exposure": {
                  "id": "cc:SfXS3Pey0Al29PI13KC5C"
              },
              "reservingCurrency": {
                "code": "gbp"
              }             
            },
            "currency": {
              "code": "cad"
            },
            "transToReservingExchangeRate": {
              "description": "Custom exchange rate",
              "market": false,
              "rate": "0.5"
            }             
          }
        ],
        "payees": [
          {
            "contact": {
              "id": "cc:Sr-RcOtnyAd2_TsoU4Szy"
            },
            "payeeType": {
              "code": "insured"
            }
          }
        ],
        "paymentMethod": {
          "code": "eft"
        }
      }
    }
  }
}
Java

Specifying multicurrency line items

Specifying the transactionAmount automatically calculates the reservingAmount, claimAmount and reportingAmount line items based on market or custom exchange rates. This automatic conversion covers most use cases for multicurrency. However, in certain instances, overriding the automatic calculation with a user-specified amount field is warranted. An example of this instance is satisfying a coverage’s deductible in the policy currency.

For example, a policy that uses USD has a 500 USD deductible.

A payment is made in GBP to satisfy the 500 USD deductible, which means the GBP payment deducts transaction amounts in GBP that is calculated to USD using exchange rates.

However, depending on the exchange rate, the exact conversion may be impossible, such as follows:

378.16GPV=499.96 USD, and 378.17 GVP = 500.01 USD. Either calculation does not satisfy the deductible and prevents the exposure from being closed.

To work around edge cases such as this, you can specify transactionAmount, reservingAmount, claimAmount and reportingAmount.

Multicurrency property amount dependency criteria

When posting multicurrency information that includes one or more of the four amount properties, the cloud API rules ensure that all properties are initialized with a value, are overridden with a user-specified value, and that fields that share the same currency use the same value. Multicurrency fields that use different values in the same currency will always throw an error.

Note the following:

  • The transactionAmount field is always required, and automatically calculates any line items you do not specify. (This is the default behavior).
    • reservingAmount is set to the transactionAmount if the reserving currency is the same as the transaction currency. Otherwise, the reservingAmount is set to the converted value.
    • claimAmount is set to the transactionAmount if the claim currency is the same as the transaction currency. Otherwise, the claimAmount is set to the converted value.
    • reportingAmount is set to the transactionAmount if the reporting currency is the same as the transaction currency. Otherwise, is transactionAmount is set to the converted value.
  • The reservingAmount field, if specified, cannot have the same currency as the transaction currency.
    • claimAmount is set to the reservingAmount if the claim currency is the same as the reserving currency.
    • reportingAmount is set to reservingAmount if the reporting currency is the same as the reserving currency.
  • The claimAmount field, if specified, cannot have the same currency as the transaction currency or claim currency.
    • reportingAmount is set to claimAmount if the reporting currency is the same as the claim currency.
  • The reportingAmount, if specified, cannot have the same currency as the transaction currency, reserving currency, or claim currency.
Warning: When PATCHing a multicurrency transaction, and specifying the transactionAmount, the other three amount properties will be recalculated and overwritten with the transactionAmount exchange rate calculations. This occurs even when the amount properties were previously specified.

As an example, consider that you encounter an edge case where the standard multicurrency calculations does not satisfy the deductible amount. The exchange rate at the time of the check-set creation calculates 250.02 GBP to 499.99 USD. Thus, the exposure for this claim cannot be closed.

Note: When encountering the edge case where exchange rates calculate a value that does not satisfy the deductible, and if the claim is a different currency than the transactionAmount, you must specify the claimAmount on the deductible.

Consider the following:

  • The exchange rate at the time of the check-set creation calculates 250.02 GBP to 499.99 USD. Thus, the exposure for this claim cannot be closed.
  • The user specifies the claimAmount as -500.00 USD, which overrides the calculated value of 499.99 USD.
"primaryCheckToWrite": {
    "paymentsToWrite": [
      {
      "transToReservingExchangeRate": {
      "description": "Custom exchange rate",
      "market": false,
      "rate": "1.9998"
      },
          "lineItems": [
            {
              "transactionAmount": {
              "amount": "600",
              "currency": "gbp"
              },
      "transactionAmount": {
      "amount":"-250.02",
      "currency": "gbp"
       },
      "claimAmount": {
      "amount": "-500.00"
      "currency": "USD"
      },
      "lineCategory": {
      "code": "deductible"
      }
            }
          ], 
...
Java

POSTing multicurrency line items

When POSTing multicurrency line items in other instances, you need only add the line items to the request payload, such as the following:

POST http://localhost:8080/cc/rest/claim/v1/claims/cc:202/reserve-sets

{
  "data": {
    "attributes": {
      "reservesToWrite": [
        {
          "reserveLine": {
            "costCategory": {
              "code": "body"
            },
            "costType": {
              "code": "claimcost"
            },
            "exposure": {
              "id": "cc:SfXS3Pey0Al29PI13KC5C"
            },
            "reservingCurrency": {
              "code": "eur"
            }
          },
          "lineItems": [
            {
              "transactionAmount": {
                "amount": "100.00",
                "currency": "jpy"
              },
		"reservingAmount": {
		"amount":"1.01",
		"currency": "eur"
		}
            }
          ],
          "currency": {
            "code": "jpy"
          }
        }
      ]
    }
  }
}
Java

Additional exchange rate schema fields

Response payloads can also include the following exchange rate fields:

  • claimToReportingExchangeRate
  • transToClaimExchangeRate

Note that these fields are read-only. When POSTing reserves and check sets, custom exchange rates are always specified using the transToReservingExchangeRate field.