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 language set.
- Delete all custom localization data to transition back to SmartPay standard localization.
info
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 perstringID
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 (consisting 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.
info
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 language 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 }
User-Agent: { User-Agent }
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
Origin: { Origin }
User-Agent: { User-Agent }
Response
Status Code:
200 (OK)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"culturesEnabled": {
"de-DE": {
"hpp:orderSummary": "Zusammenfassung der Bestellung",
"hpp:success_long_text": "Ihre Zahlung wurde erfolgreich verarbeitet.",
"stored-method:expired-warning": "Eine abgelaufene Zahlungsmethode ist nicht nutzbar.",
"main-panel-registration:instruction": "Neue Zahlungsart speichern",
"stored-method:add": "Neue Zahlungsart hinzufügen",
"button:stored-payment": "Speichern",
"main-panel-registration:instruction_detail": "Bitte wählen Sie eine Zahlungsart aus. Die Zahlungsinformationen geben Sie im letzten Schritt ein.",
"stored-method:expires-soon": "Läuft bald ab",
"sepa_mandate:creditor_identifier": "Gläubiger Id",
"sepa_mandate:state": "Bundesland",
"button:cancel": "Abbrechen",
"3ri:instruction_detail": "Bitte wählen Sie eine Ihrer gespeicherten Zahlungsarten aus oder speichern Sie eine neue Zahlungsart.",
"payment-method:APPLPAY": "Apple Pay",
"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)",
"payment-method:PAYINVC": "Kauf auf Rechnung",
"sepa_mandate:agree": "Zustimmen",
"button:as-guest": "Als Gast zahlen",
"hpp:itemName": "Artikelname",
"hpp:quantity": "Menge",
"hpp:success:your-transaction": "Ihre Transaktionsreferenz ist",
"hpp:button:proceedToPayment": "Weiter zur Zahlung",
"button:continue-guest": "Zahlung fortsetzen",
"hpp:failure_long_text": "Bitte versuchen Sie es mit einer anderen Karte oder einer anderen Zahlungsmethode",
"payment-method:PAYUBLK": "BLIK",
"payment-method:VISA": "VISA",
"hpp:success:please-quote": "Bitte geben Sie diese Nummer bei Ihrer Überweisung im Verwendungszweck an.",
"payment-method:BNKACCT": "SEPA Direct Debit",
"sepa_mandate:date": "Datum",
"3ri:privacy-notice": "Datenschutzerklärung",
"payment-method:PAYU": "PayU",
"payment-method:PREPMNT": "Vorauskasse",
"stored-method:default": "Bevorzugt",
"stored-method:disabled": "Wartet auf Aktivierung / Inaktiv",
"payment-method:CRTBANCAIR": "Carte Bancaire",
"stored-method:back": "Zurück zu den vorhandenen Zahlungsarten",
"button:try_again": "Versuchen Sie es erneut",
"hpp:discountPercent": "Rabattprozentsatz",
"sepa_mandate:account_holder": "Kontoinhaber",
"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.",
"popup-registration:instruction_detail": "Bitte geben Sie unten Ihre Zahlungsinformationen ein, um Ihre Zahlungsoption zu registrieren. Es erfolgt keine Zahlung.",
"sepa_mandate:name": "Name",
"payment-method:PAYPAL": "PayPal",
"hpp:activePaymentError": "Mit dieser Anfrage ist bereits eine aktive Zahlung verbunden.",
"hpp:discountAmount": "Rabattbetrag",
"sepa_mandate:country": "Land",
"stored-method:expiry_date": "Gültig bis:",
"3ri:save-card": "Speicherung der Zahlungsinformationen für eine schneller Bezahlung beim nächsten Mal",
"payment-method:CC": "Kreditkarte",
"stored-method:active": "Aktiv",
"hpp:failure_header": "Bezahlung fehlgeschlagen",
"sepa_mandate:iban": "IBAN",
"3ri:CC": "Neue Kredit-/Debitkarte hinzufügen",
"3ri:instruction": "Gespeicherte Zahlungsarten",
"sepa_mandate:mandate_reference": "Mandatsreferenz",
"hpp:totalDue": "Gesamtbetrag fällig",
"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.",
"hpp:shippingAddress": "Versand",
"button:submit": "Bestätigen",
"hpp:billingAddress": "Rechnungsstellung",
"main-panel-guest:instruction_detail": "Bitte wählen Sie eine Zahlungsart aus. Die Zahlungsinformationen geben Sie im letzten Schritt ein.",
"hpp:success_header": "Danke!",
"payment-method:AMEX": "AMEX",
"payment-method:JCB": "JCB",
"button:continue-registration": "Registrierung fortsetzen",
"payment-method:MSTRCRD": "Mastercard",
"payment-method:PAYUBNK": "Bank Transfer",
"payment-method:IDEAL": "Ideal",
"button:back-to-methods-selection": "Zurück",
"stored-method:empty": "Keine gespeicherten Zahlungsarten vorhanden. Bitte fügen Sie eine neue Zahlungsart hinzu.",
"sepa_mandate:address": "Adresse",
"main-panel-guest:instruction": "Zahlungsart",
"stored-method:remove": "Entfernen",
"sepa_mandate:city": "Stadt",
"sepa_mandate:post_code": "PLZ",
"button:payment": "Bezahlen ${currencySign}${amount}",
"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.",
"sepa_mandate:creditor": "Gläubiger",
"stored-method:set_default": "Als Bevorzugt setzen",
"hpp:grossAmount": "Bruttobetrag",
"stored-method:expired": "Abgelaufen"
},
"en-EN": {
"hpp:orderSummary": "Order summary",
"hpp:success_long_text": "Your payment has been successfully processed.",
"stored-method:expired-warning": "An expired payment method cannot be used.",
"main-panel-registration:instruction": "Please select your new payment method",
"stored-method:add": "Add new payment method",
"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.",
"stored-method:expires-soon": "Expires soon",
"sepa_mandate:creditor_identifier": "Creditor identifier",
"sepa_mandate:state": "State",
"button:cancel": "Cancel",
"3ri:instruction_detail": "Continue with one of your saved payment methods or add a new one.",
"payment-method:APPLPAY": "Apple Pay",
"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)",
"payment-method:PAYINVC": "Pay upon Invoice",
"sepa_mandate:agree": "Agree",
"button:as-guest": "Pay as a guest",
"hpp:itemName": "Item Name",
"hpp:quantity": "Qty",
"hpp:success:your-transaction": "Your transaction reference is",
"hpp:button:proceedToPayment": "Proceed to payment",
"button:continue-guest": "Continue Payment",
"hpp:failure_long_text": "Please try another card or a different payment method",
"payment-method:PAYUBLK": "BLIK",
"payment-method:VISA": "VISA",
"hpp:success:please-quote": "Please quote this number in the purpose of payment when submitting your bank transfer.",
"payment-method:BNKACCT": "SEPA Direct Debit",
"sepa_mandate:date": "Date",
"3ri:privacy-notice": "privacy notice",
"payment-method:PAYU": "PayU",
"payment-method:PREPMNT": "Prepayment",
"stored-method:default": "default",
"stored-method:disabled": "Pending Activation / Inactive",
"payment-method:CRTBANCAIR": "Carte Bancaire",
"stored-method:back": "Back to stored payments",
"button:try_again": "Try again",
"hpp:discountPercent": "Discount Percent",
"sepa_mandate:account_holder": "Account Owner",
"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.",
"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:name": "Name",
"payment-method:PAYPAL": "PayPal",
"hpp:activePaymentError": "There is already an active payment associated with this request.",
"hpp:discountAmount": "Discount Amount",
"sepa_mandate:country": "Country",
"stored-method:expiry_date": "Expires",
"3ri:save-card": "Save payment info to pay faster next time",
"payment-method:CC": "Credit Card / Debit Card",
"stored-method:active": "Active",
"hpp:failure_header": "Payment failed",
"sepa_mandate:iban": "IBAN",
"3ri:CC": "Add new credit / debit card",
"3ri:instruction": "Choose a payment method",
"sepa_mandate:mandate_reference": "Mandate reference",
"hpp:totalDue": "Total due",
"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)",
"hpp:shippingAddress": "Shipping",
"button:submit": "Continue",
"hpp:billingAddress": "Billing",
"main-panel-guest:instruction_detail": "We will ask you to enter your details in the next step.",
"hpp:success_header": "Thank you!",
"payment-method:AMEX": "AMEX",
"payment-method:JCB": "JCB",
"button:continue-registration": "Continue Registration",
"payment-method:MSTRCRD": "Mastercard",
"payment-method:PAYUBNK": "Bank Transfer",
"payment-method:IDEAL": "Ideal",
"button:back-to-methods-selection": "Back",
"stored-method:empty": "No stored payments available. Please add a new payment method.",
"sepa_mandate:address": "Address",
"main-panel-guest:instruction": "Please select your payment method",
"stored-method:remove": "delete",
"sepa_mandate:city": "City",
"sepa_mandate:post_code": "PostCode",
"button:payment": "Pay ${currencySign}${amount}",
"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.",
"sepa_mandate:creditor": "Creditor",
"stored-method:set_default": "set as default",
"hpp:grossAmount": "Gross Amount",
"stored-method:expired": "Expired"
}
},
"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 }
User-Agent: { User-Agent }
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
Origin: { Origin }
User-Agent: { User-Agent }
{
"culturesEnabled": {
"en-EN": {
"hpp:orderSummary": "Order summary",
"hpp:success_long_text": "Your payment has been successfully processed.",
"stored-method:expired-warning": "An expired payment method cannot be used.",
"main-panel-registration:instruction": "Please select your new payment method",
"stored-method:add": "Add new payment method",
"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.",
"stored-method:expires-soon": "Expires soon",
"sepa_mandate:creditor_identifier": "Creditor identifier",
"sepa_mandate:state": "State",
"button:cancel": "Cancel",
"3ri:instruction_detail": "Continue with one of your saved payment methods or add a new one.",
"payment-method:APPLPAY": "Apple Pay",
"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)",
"payment-method:PAYINVC": "Pay upon Invoice",
"sepa_mandate:agree": "Agree",
"button:as-guest": "Pay as a guest",
"hpp:itemName": "Item Name",
"hpp:quantity": "Qty",
"hpp:success:your-transaction": "Your transaction reference is",
"hpp:button:proceedToPayment": "Proceed to payment",
"button:continue-guest": "Continue Payment",
"hpp:failure_long_text": "Please try another card or a different payment method",
"payment-method:PAYUBLK": "BLIK",
"payment-method:VISA": "VISA",
"hpp:success:please-quote": "Please quote this number in the purpose of payment when submitting your bank transfer.",
"payment-method:BNKACCT": "SEPA Direct Debit",
"sepa_mandate:date": "Date",
"3ri:privacy-notice": "privacy notice",
"payment-method:PAYU": "PayU",
"payment-method:PREPMNT": "Prepayment",
"stored-method:default": "default",
"stored-method:disabled": "Pending Activation / Inactive",
"payment-method:CRTBANCAIR": "Carte Bancaire",
"stored-method:back": "Back to stored payments",
"button:try_again": "Try again",
"hpp:discountPercent": "Discount Percent",
"sepa_mandate:account_holder": "Account Owner",
"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.",
"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:name": "Name",
"payment-method:PAYPAL": "PayPal",
"hpp:activePaymentError": "There is already an active payment associated with this request.",
"hpp:discountAmount": "Discount Amount",
"sepa_mandate:country": "Country",
"stored-method:expiry_date": "Expires",
"3ri:save-card": "Save payment info to pay faster next time",
"payment-method:CC": "Credit Card / Debit Card",
"stored-method:active": "Active",
"hpp:failure_header": "Payment failed",
"sepa_mandate:iban": "IBAN",
"3ri:CC": "Add new credit / debit card",
"3ri:instruction": "Choose a payment method",
"sepa_mandate:mandate_reference": "Mandate reference",
"hpp:totalDue": "Total due",
"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)",
"hpp:shippingAddress": "Shipping",
"button:submit": "Continue",
"hpp:billingAddress": "Billing",
"main-panel-guest:instruction_detail": "We will ask you to enter your details in the next step.",
"hpp:success_header": "Thank you!",
"payment-method:AMEX": "AMEX",
"payment-method:JCB": "JCB",
"button:continue-registration": "Continue Registration",
"payment-method:MSTRCRD": "Mastercard",
"payment-method:PAYUBNK": "Bank Transfer",
"payment-method:IDEAL": "Ideal",
"button:back-to-methods-selection": "Back",
"stored-method:empty": "No stored payments available. Please add a new payment method.",
"sepa_mandate:address": "Address",
"main-panel-guest:instruction": "Please select your payment method",
"stored-method:remove": "delete",
"sepa_mandate:city": "City",
"sepa_mandate:post_code": "PostCode",
"button:payment": "Pay ${currencySign}${amount}",
"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.",
"sepa_mandate:creditor": "Creditor",
"stored-method:set_default": "set as default",
"hpp:grossAmount": "Gross Amount",
"stored-method:expired": "Expired"
}
},
"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 }
User-Agent: { User-Agent }
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
Origin: { Origin }
User-Agent: { User-Agent }
Response
Status Code:
200 (OK)
Header:
Content-Type: application/json
Accept-Language: en-US
{
"merchantKey": "",
"message": "Default culture configuration has been successfully restored."
}