Localization API

Last changes: 02-21-2022

Introduction

Localization, what is it about?

Custom localization might be a crucial topic to amend SmartPay towards your business and journey specific needs.

To give you full control about any localization, we introduced our /payment/localization endpoint. It allows you to:

  1. Get currently valid localization data (if use first time, it will return SmartPay default language configuration).
  2. Upload custom localization data for some or all supported languages.
  3. Upload languages which are not supported by SmartPay default langauge set.
  4. Delete all custom localization data to transition back to SmartPay standard localization.

Usage of this endpoint is optional. If you do not opt for this, you'll automatically use the SmartPay default localization for all currently supported languages with a fallback to English in case the consumer's language is currently not supported.

Localization concept

To organize localization, we work with a json formatted data object consisting of:

  1. Basic merchant information & version timestamps
  2. culturesEnabled array holding the actual localization data per stringID

The cultureEnabled object is prefilled with all SmartPay default localizations, whereby one culture is the smallest entity.

Meaning, if you would like to change only one StringID in en-EN language, you would first get the current default localization (perhaps containing en-EN, de-DE and es-ES). Then you would update the StringID in en-EN and post the entire en-EN localization (consiting of the custom value and remaining default values) back to SmartPay. In this case, SmartPay will use your customer en-EN localization but still the default de-DE and es-ES.

Eventual updates to the default localizations are in this case automatically reflected to de-DE and es-ES - en-EN remains in the state which you have posted, as you have claimed control.

Only exception to this rule is, if we would add new StringIDs (e.g., due to journey changes). If this happens, the default StringIDs will also be promoted to your custom file, to protect your journey without immediate interaction from your side.

In addition, you may always revert to default localization by using DELETE /payment/localization.

Please note:

Any update of default localization and added StringIDs will be added to the changelog and highlighted within the deployment notification. Make sure to subscribe to contoworks.statuspage.io to receive those updates.

If you create currently not supported languages, please specify the language using RFC-4646 declaration (e.g. de-DE). Remark, currently SmartPay only evaluates the langauge code "de" but not the county code. Support of the full combination will be added in a later release.

Default Language vs Fallback Language

Default language are all localizations, which SmartPay provides by default. Currently, these languages are de-DE, en-EN, es-ES, fi-FI, fr-FR, it-IT, pl-PL, ro-RO and sv-SV.

Fallback language is en-EN and will be used if a not existing localization or stringID is requested.

Get Localization Data API

API Parameters

Request Parameters

Field Description Type Length Mandatory
merchantKey Merchant identifier. String 36 Yes

Response Parameters

Field Description Type Length
merchantKey Merchant identifier. GUID 36
merchantName The merchant's name. String 255
lastUpdateDateTime The time when the merchant's strings were updated last time. String 24
requestDateTime The time when the user has downloaded the file. String 24
culturesEnabled An object which consists of all culture codes enabled by the merchant. Object  
culturesEnabled.{cultureEntry} See String ID reference Name:Value pairs  

Example

Request

Path:

GET {Base URL}/payment/localization/{merchantKey}

Header:

Content-Type: application/json
Accept-Language: en-US

{}

Response

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "culturesEnabled": {
    "de-DE": {
      "sepa_mandate:name": "Name",
      "payment-method:PAYPAL": "PayPal",
      "main-panel-registration:instruction": "Neue Zahlungsart speichern",
      "sepa_mandate:country": "Land",
      "stored-method:add": "Neue Zahlart hinzufügen",
      "stored-method:expiry_date": "Gültig bis:",
      "button:stored-payment": "Speichern",
      "main-panel-registration:instruction_detail": "Bitte wählen Sie eine Zahlungsart aus. Die Zahlungsinformationen geben Sie im letzten Schritt ein.",
      "payment-method:CC": "Kreditkarte",
      "sepa_mandate:iban": "IBAN",
      "sepa_mandate:creditor_identifier": "Gläubiger Id",
      "sepa_mandate:state": "Bundesland",
      "sepa_mandate:mandate_reference": "Mandatsreferenz",
      "button:cancel": "Abbrechen",
      "sepa_mandate:mandate_info_first": "Ich ermächtige/ Wir ermächtigen (A) Volkswagen Payments S.A., Zahlungen von meinem/ unserem Konto mittels Lastschrift einzuziehen. Zugleich (B) weise ich mein/ weisen wir unser Kreditinstitut an, die von Volkswagen Payments S.A. auf mein/ unser Konto gezogenen Lastschriften einzulösen.",
      "button:submit": "Bestätigen",
      "payment-method:PAYINVC": "Kauf auf Rechnung",
      "sepa_mandate:agree": "Zustimmen",
      "button:as-guest": "Als Gast zahlen",
      "payment-method:KLARNA_PAY_LATER": "Klarna Rechnungskauf",
      "main-panel-guest:instruction_detail": "Bitte wählen Sie eine Zahlungsart aus. Die Zahlungsinformationen geben Sie im letzten Schritt ein.",
      "payment-method:AMEX": "AMEX",
      "payment-method:JCB": "JCB",
      "payment-method:MSTRCRD": "Mastercard",
      "payment-method:IDEAL": "Ideal",
      "stored-method:empty": "Keine gespeicherten Zahlarten vorhanden. Bitte fügen Sie eine neue Zahlart hinzu.",
      "payment-method:VISA": "VISA",
      "sepa_mandate:address": "Adresse",
      "main-panel-guest:instruction": "Zahlungsart",
      "payment-method:BNKACCT": "SEPA Direct Debit",
      "sepa_mandate:date": "Datum",
      "stored-method:remove": "Entfernen",
      "sepa_mandate:city": "Stadt",
      "payment-method:PAYU": "PayU",
      "sepa_mandate:post_code": "PLZ",
      "payment-method:PREPMNT": "Vorauskasse",
      "stored-method:default": "Bevorzugt",
      "button:payment": "Bezahlen",
      "main-panel-registered:instruction": "Gespeicherte Zahlungsarten",
      "main-panel-registered:instruction_detail": "Bitte wählen Sie eine Ihrer gespeicherten Zahlungsarten aus oder speichern Sie eine neue Zahlart.",
      "payment-method:KLARNA_PAY_OVER_TIME": "Klarna Ratenkauf",
      "payment-method:CRTBANCAIR": "Carte Bancaire",
      "stored-method:back": "Zurück zu den vorhanden Zahlarten",
      "sepa_mandate:creditor": "Gläubiger",
      "sepa_mandate:account_holder": "Kontoinhaber",
      "stored-method:set_default": "Als Bevorzugt setzen",
      "sepa_mandate:mandate_info_second": "Hinweis: Ich kann/ Wir können innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrages verlangen. Es gelten dabei die mit meinem/ unserem Kreditinstitut vereinbarten Bedingungen."
    },
    "en-EN": {
      "sepa_mandate:name": "Name",
      "payment-method:PAYPAL": "PayPal",
      "main-panel-registration:instruction": "Please select your new payment method",
      "sepa_mandate:country": "Country",
      "stored-method:add": "Add new payment",
      "stored-method:expiry_date": "Expires",
      "button:stored-payment": "Confirm",
      "main-panel-registration:instruction_detail": "We will ask you to enter your details in the next step to register your payment option.",
      "payment-method:CC": "Credit Card / Debit Card",
      "sepa_mandate:iban": "IBAN",
      "sepa_mandate:creditor_identifier": "Creditor identifier",
      "sepa_mandate:state": "State",
      "sepa_mandate:mandate_reference": "Mandate reference",
      "button:cancel": "Cancel",
      "sepa_mandate:mandate_info_first": "By signing this mandate form, you authorise (A) Volkswagen Payments S.A. to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from Volkswagen Payments S.A.",
      "button:submit": "Continue",
      "payment-method:PAYINVC": "Pay upon Invoice",
      "sepa_mandate:agree": "Agree",
      "button:as-guest": "Pay as a guest",
      "payment-method:KLARNA_PAY_LATER": "Klarna pay later",
      "main-panel-guest:instruction_detail": "We will ask you to enter your details in the next step.",
      "payment-method:AMEX": "AMEX",
      "payment-method:JCB": "JCB",
      "payment-method:MSTRCRD": "Mastercard",
      "payment-method:IDEAL": "Ideal",
      "stored-method:empty": "No stored payments available. Please add a new payment method.",
      "payment-method:VISA": "VISA",
      "sepa_mandate:address": "Address",
      "main-panel-guest:instruction": "Please select your payment method",
      "payment-method:BNKACCT": "SEPA Direct Debit",
      "sepa_mandate:date": "Date",
      "stored-method:remove": "delete",
      "sepa_mandate:city": "City",
      "payment-method:PAYU": "PayU",
      "sepa_mandate:post_code": "PostCode",
      "payment-method:PREPMNT": "Prepayment",
      "stored-method:default": "default",
      "button:payment": "Pay Now",
      "main-panel-registered:instruction": "Choose a payment method",
      "main-panel-registered:instruction_detail": "Continue with one of your saved payment methods or add a new one.",
      "payment-method:KLARNA_PAY_OVER_TIME": "Klarna pay over time",
      "payment-method:CRTBANCAIR": "Carte Bancaire",
      "stored-method:back": "Back to stored payments",
      "sepa_mandate:creditor": "Creditor",
      "sepa_mandate:account_holder": "Account Owner",
      "stored-method:set_default": "set as default",
      "sepa_mandate:mandate_info_second": "As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited."
    }
  },
  "merchantName": "CW Generic Merchant",
  "lastUpdateDateTime": "2021-07-06T11:28:33.491Z",
  "requestTime": "2021-07-09T10:05:20.261Z",
  "merchantKey": "23016498-3dd9-4be3-a76f-6454894564"
}

Post Localization Data API

API Parameters

Request Parameters

Field Description Type Length
merchantKey Merchant identifier. GUID 36
merchantName The merchant's name. String 255
lastUpdateDateTime The time when the merchant's strings were updated last time. String 24
requestDateTime The time when the user has downloaded the file. String 24
culturesEnabled An object which consists of all culture codes enabled by the merchant. Object  
culturesEnabled.{cultureEntry} See String ID reference Name:Value pairs  

Response Parameters

Field Description Type Length
merchantKey Merchant identifier. GUID 36
message Information regarding processing status String 255

Example

Request

Path:

POST {Base URL}/payment/localization/{merchantKey}

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "culturesEnabled": {
    "en-EN": {
      "sepa_mandate:name": "This vaule is changed",
      "payment-method:PAYPAL": "PayPal",
      "main-panel-registration:instruction": "Please select your new payment method",
      "sepa_mandate:country": "Country",
      "stored-method:add": "Add new payment",
      "stored-method:expiry_date": "Expires",
      "button:stored-payment": "Confirm",
      "main-panel-registration:instruction_detail": "We will ask you to enter your details in the next step to register your payment option.",
      "payment-method:CC": "Credit Card / Debit Card",
      "sepa_mandate:iban": "IBAN",
      "sepa_mandate:creditor_identifier": "Creditor identifier",
      "sepa_mandate:state": "State",
      "sepa_mandate:mandate_reference": "Mandate reference",
      "button:cancel": "Cancel",
      "sepa_mandate:mandate_info_first": "By signing this mandate form, you authorise (A) Volkswagen Payments S.A. to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from Volkswagen Payments S.A.",
      "button:submit": "Continue",
      "payment-method:PAYINVC": "Pay upon Invoice",
      "sepa_mandate:agree": "Agree",
      "button:as-guest": "Pay as a guest",
      "payment-method:KLARNA_PAY_LATER": "Klarna pay later",
      "main-panel-guest:instruction_detail": "We will ask you to enter your details in the next step.",
      "payment-method:AMEX": "AMEX",
      "payment-method:JCB": "JCB",
      "payment-method:MSTRCRD": "Mastercard",
      "payment-method:IDEAL": "Ideal",
      "stored-method:empty": "No stored payments available. Please add a new payment method.",
      "payment-method:VISA": "VISA",
      "sepa_mandate:address": "Address",
      "main-panel-guest:instruction": "Please select your payment method",
      "payment-method:BNKACCT": "SEPA Direct Debit",
      "sepa_mandate:date": "Date",
      "stored-method:remove": "delete",
      "sepa_mandate:city": "City",
      "payment-method:PAYU": "PayU",
      "sepa_mandate:post_code": "PostCode",
      "payment-method:PREPMNT": "Prepayment",
      "stored-method:default": "default",
      "button:payment": "Pay Now",
      "main-panel-registered:instruction": "Choose a payment method",
      "main-panel-registered:instruction_detail": "Continue with one of your saved payment methods or add a new one.",
      "payment-method:KLARNA_PAY_OVER_TIME": "Klarna pay over time",
      "payment-method:CRTBANCAIR": "Carte Bancaire",
      "stored-method:back": "Back to stored payments",
      "sepa_mandate:creditor": "Creditor",
      "sepa_mandate:account_holder": "Account Owner",
      "stored-method:set_default": "set as default",
      "sepa_mandate:mandate_info_second": "As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited."
    }
  },
  "merchantName": "CW Generic Merchant",
  "lastUpdateDateTime": "2021-07-06T11:28:33.491Z",
  "requestTime": "2021-07-09T10:05:20.261Z",
  "merchantKey": "23016498-3dd9-4be3-a76f-6454894564"
}

Response 200 (OK)

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

Content-Type: application/json
{
 
"merchantKey": "",
"message" : "The culture configuration has been successfully updated",
 
}

Response 400 (Bad Request)

Status Code:

400 (Bad Request)

Header:

Content-Type: application/json
Accept-Language: en-US

Content-Type: application/json
{
"message": "Some keys are missing. Refer to the list below."
{
"message":
    "culturesEnabled": {
        "en-US" : {
            "button_cancel": "CANCEL",
            "button_confirm": "CONFIRM"
        },
        "de-DE" : {
            "button_cancel": "CANCEL"
        }
    }
}

Delete Localization Data API (Reset to Default)

API Parameters

Request Parameters

Field Description Type Length Mandatory
merchantKey Merchant identifier. String 36 Yes

Response Parameters

Field Description Type Length
merchantKey Merchant identifier. GUID 36
merchantName The merchant's name. String 255
lastUpdateDateTime The time when the merchant's strings were updated last time. String 24
requestDateTime The time when the user has downloaded the file. String 24
culturesEnabled An object which consists of all culture codes enabled by the merchant. Object  
culturesEnabled.{cultureEntry} See String ID reference Name:Value pairs  

Example

Request

Path:

DELETE {Base URL}/payment/localization/{merchantKey}

Header:

Content-Type: application/json
Accept-Language: en-US

{}

Response

Status Code:

200 (OK)

Header:

Content-Type: application/json
Accept-Language: en-US

Content-Type: application/json
{
"merchantKey": "",
"message": "Default culture configuration has been successfully restored."
 
}