Localization API
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:
- Get currently valid localization data (if use first time, it will return SmartPay default language configuration).
- Upload custom localization data for some or all supported languages.
- Upload languages which are not supported by SmartPay default langauge set.
- 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:
- Basic merchant information & version timestamps
culturesEnabledarray 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.
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 status page 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 |
The request must have the following headers:
Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
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": {
"3ri:CC": "Neue Kredit-/Debitkarte hinzufügen",
"3ri:instruction": "Gespeicherte Zahlungsarten",
"3ri:instruction_detail": "Bitte wählen Sie eine Ihrer gespeicherten Zahlungsarten aus oder speichern Sie eine neue Zahlungsart.",
"3ri:legal-text": "J.P. Mobility Payments Solutions S.A. verarbeitet als Datenverantwortlicher Ihre personenbezogenen Daten, unter anderem für die Abwicklung des Zahlungsvorgangs (weitere Einzelheiten entnehmen Sie in unserer Datenschutzerklärung)",
"3ri:privacy-notice": "Datenschutzerklärung",
"3ri:save-card": "Speicherung der Zahlungsinformationen für eine schneller Bezahlung beim nächsten Mal",
"button:as-guest": "Als Gast zahlen",
"button:back-to-methods-selection": "Zurück",
"button:cancel": "Abbrechen",
"button:continue-guest": "Zahlung fortsetzen",
"button:continue-registration": "Registrierung fortsetzen",
"button:payment": "Bezahlen ${currencySign}${amount}",
"button:stored-payment": "Speichern",
"button:submit": "Bestätigen",
"button:try_again": "Versuchen Sie es erneut",
"hpp:activePaymentError": "Mit dieser Anfrage ist bereits eine aktive Zahlung verbunden.",
"hpp:billingAddress": "Rechnungsstellung",
"hpp:button:proceedToPayment": "Weiter zur Zahlung",
"hpp:discountAmount": "Rabattbetrag",
"hpp:discountPercent": "Rabattprozentsatz",
"hpp:failure_header": "Bezahlung fehlgeschlagen",
"hpp:failure_long_text": "Bitte versuchen Sie es mit einer anderen Karte oder einer anderen Zahlungsmethode",
"hpp:grossAmount": "Bruttobetrag",
"hpp:itemName": "Artikelname",
"hpp:orderSummary": "Zusammenfassung der Bestellung",
"hpp:quantity": "Menge",
"hpp:shippingAddress": "Versand",
"hpp:success:please-quote": "Bitte geben Sie diese Nummer bei Ihrer Überweisung im Verwendungszweck an.",
"hpp:success:your-transaction": "Ihre Transaktionsreferenz ist",
"hpp:success_header": "Danke!",
"hpp:success_long_text": "Ihre Zahlung wurde erfolgreich verarbeitet.",
"hpp:totalDue": "Gesamtbetrag fällig",
"main-panel-guest:instruction": "Zahlungsart",
"main-panel-guest:instruction_detail": "Bitte wählen Sie eine Zahlungsart aus. Die Zahlungsinformationen geben Sie im letzten Schritt ein.",
"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 Zahlungsart.",
"main-panel-registration:instruction": "Neue Zahlungsart speichern",
"main-panel-registration:instruction_detail": "Bitte wählen Sie eine Zahlungsart aus. Die Zahlungsinformationen geben Sie im letzten Schritt ein.",
"payment-method:AMEX": "AMEX",
"payment-method:APPLPAY": "Apple Pay",
"payment-method:BNKACCT": "SEPA Direct Debit",
"payment-method:CC": "Kreditkarte",
"payment-method:CRTBANCAIR": "Carte Bancaire",
"payment-method:IDEAL": "Ideal",
"payment-method:JCB": "JCB",
"payment-method:KLARNA_PAY_LATER": "Klarna Rechnungskauf",
"payment-method:KLARNA_PAY_OVER_TIME": "Klarna Ratenkauf",
"payment-method:MSTRCRD": "Mastercard",
"payment-method:PAYINVC": "Kauf auf Rechnung",
"payment-method:PAYPAL": "PayPal",
"payment-method:PAYU": "PayU",
"payment-method:PAYUBLK": "BLIK",
"payment-method:PAYUBNK": "Bank Transfer",
"payment-method:PREPMNT": "Vorauskasse",
"payment-method:VISA": "VISA",
"popup-registration:instruction_detail": "Bitte geben Sie unten Ihre Zahlungsinformationen ein, um Ihre Zahlungsoption zu registrieren. Es erfolgt keine Zahlung.",
"sepa_mandate:account_holder": "Kontoinhaber",
"sepa_mandate:address": "Adresse",
"sepa_mandate:agree": "Zustimmen",
"sepa_mandate:city": "Stadt",
"sepa_mandate:country": "Land",
"sepa_mandate:creditor": "Gläubiger",
"sepa_mandate:creditor_identifier": "Gläubiger Id",
"sepa_mandate:date": "Datum",
"sepa_mandate:iban": "IBAN",
"sepa_mandate:mandate_info_first": "Ich ermächtige/ Wir ermächtigen (A) $(fi-creditor-name), Zahlungen von meinem/ unserem Konto mittels Lastschrift einzuziehen. Zugleich (B) weise ich mein/ weisen wir unser Kreditinstitut an, die von $(fi-creditor-name) auf mein/ unser Konto gezogenen Lastschriften einzulösen.",
"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.",
"sepa_mandate:mandate_reference": "Mandatsreferenz",
"sepa_mandate:name": "Name",
"sepa_mandate:post_code": "PLZ",
"sepa_mandate:state": "Bundesland",
"stored-method:add": "Neue Zahlungsart hinzufügen",
"stored-method:back": "Zurück zu den vorhandenen Zahlungsarten",
"stored-method:default": "Bevorzugt",
"stored-method:empty": "Keine gespeicherten Zahlungsarten vorhanden. Bitte fügen Sie eine neue Zahlungsart hinzu.",
"stored-method:expiry_date": "Gültig bis:",
"stored-method:remove": "Entfernen",
"stored-method:set_default": "Als Bevorzugt setzen"
},
"en-EN": {
"3ri:CC": "Add new credit / debit card",
"3ri:instruction": "Choose a payment method",
"3ri:instruction_detail": "Continue with one of your saved payment methods or add a new one.",
"3ri:legal-text": "J.P. Mobility Payments Solutions S.A., as a data controller, processes your personal data for the completion of the payment transaction among other purposes (more details in our privacy notice)",
"3ri:privacy-notice": "privacy notice",
"3ri:save-card": "Save payment info to pay faster next time",
"button:as-guest": "Pay as a guest",
"button:back-to-methods-selection": "Back",
"button:cancel": "Cancel",
"button:continue-guest": "Continue Payment",
"button:continue-registration": "Continue Registration",
"button:payment": "Pay ${currencySign}${amount}",
"button:stored-payment": "Confirm",
"button:submit": "Continue",
"button:try_again": "Try again",
"hpp:activePaymentError": "There is already an active payment associated with this request.",
"hpp:billingAddress": "Billing",
"hpp:button:proceedToPayment": "Proceed to payment",
"hpp:discountAmount": "Discount Amount",
"hpp:discountPercent": "Discount Percent",
"hpp:failure_header": "Payment failed",
"hpp:failure_long_text": "Please try another card or a different payment method",
"hpp:grossAmount": "Gross Amount",
"hpp:itemName": "Item Name",
"hpp:orderSummary": "Order summary",
"hpp:quantity": "Qty",
"hpp:shippingAddress": "Shipping",
"hpp:success:please-quote": "Please quote this number in the purpose of payment when submitting your bank transfer.",
"hpp:success:your-transaction": "Your transaction reference is",
"hpp:success_header": "Thank you!",
"hpp:success_long_text": "Your payment has been successfully processed.",
"hpp:totalDue": "Total due",
"main-panel-guest:instruction": "Please select your payment method",
"main-panel-guest:instruction_detail": "We will ask you to enter your details in the next step.",
"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.",
"main-panel-registration:instruction": "Please select your new payment method",
"main-panel-registration:instruction_detail": "We will ask you to enter your details in the next step to register your payment option.",
"payment-method:AMEX": "AMEX",
"payment-method:APPLPAY": "Apple Pay",
"payment-method:BNKACCT": "SEPA Direct Debit",
"payment-method:CC": "Credit Card / Debit Card",
"payment-method:CRTBANCAIR": "Carte Bancaire",
"payment-method:IDEAL": "Ideal",
"payment-method:JCB": "JCB",
"payment-method:KLARNA_PAY_LATER": "Klarna pay later",
"payment-method:KLARNA_PAY_OVER_TIME": "Klarna pay over time",
"payment-method:MSTRCRD": "Mastercard",
"payment-method:PAYINVC": "Pay upon Invoice",
"payment-method:PAYPAL": "PayPal",
"payment-method:PAYU": "PayU",
"payment-method:PAYUBLK": "BLIK",
"payment-method:PAYUBNK": "Bank Transfer",
"payment-method:PREPMNT": "Prepayment",
"payment-method:VISA": "VISA",
"popup-registration:instruction_detail": "Please enter your payment method details below in order to register your payment option. No payment will be performed.",
"sepa_mandate:account_holder": "Account Owner",
"sepa_mandate:address": "Address",
"sepa_mandate:agree": "Agree",
"sepa_mandate:city": "City",
"sepa_mandate:country": "Country",
"sepa_mandate:creditor": "Creditor",
"sepa_mandate:creditor_identifier": "Creditor identifier",
"sepa_mandate:date": "Date",
"sepa_mandate:iban": "IBAN",
"sepa_mandate:mandate_info_first": "By signing this mandate form, you authorise (A) $(fi-creditor-name) to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from $(fi-creditor-name)",
"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.",
"sepa_mandate:mandate_reference": "Mandate reference",
"sepa_mandate:name": "Name",
"sepa_mandate:post_code": "PostCode",
"sepa_mandate:state": "State",
"stored-method:add": "Add new payment method",
"stored-method:back": "Back to stored payments",
"stored-method:default": "default",
"stored-method:empty": "No stored payments available. Please add a new payment method.",
"stored-method:expiry_date": "Expires",
"stored-method:remove": "delete",
"stored-method:set_default": "set as default"
},
},
"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 | - |
The request must have the following headers:
Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
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) $(fi-creditor-name) to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from $(fi-creditor-name)",
"button:submit": "Continue",
"payment-method:PAYINVC": "Pay upon Invoice",
"sepa_mandate:agree": "Agree",
"button:as-guest": "Pay as a guest",
"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: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
{
"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
{
"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 |
The request must have the following headers:
Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
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
{
"merchantKey": "",
"message": "Default culture configuration has been successfully restored."
}