Skip to content

Commit 9be0b7b

Browse files
chris-nowickibc-terra
chris-nowicki
and
bc-terra
authored
DEVDOCS-6664 - Adds docs for payment method translations (#1211)
<!-- Ticket number or summary of work --> # [DEVDOCS-6664] ## What changed? <!-- Provide a bulleted list in the present tense --> * Adds documentation for Payment Method Translations ## Release notes draft * Adds documentation for Payment Method Translations ping @bigcommerce/dev-docs [DEVDOCS-6664]: https://bigcommercecloud.atlassian.net/browse/DEVDOCS-6664?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ --------- Co-authored-by: Terra Hyde <terra.hyde@bigcommerce.com>
1 parent 4c1b32b commit 9be0b7b

2 files changed

Lines changed: 313 additions & 6 deletions

File tree

‎docs/store-operations/translations/index.mdx‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,10 @@ The API currently supports translations for the following resource types, and mo
2222

2323
Refer to the [Error Handling](/docs/store-operations/translations/errors) guide for understanding and handling errors while managing translations.
2424

25-
<Callout type="info">
26-
Translation API allows users to add content translations to any non-default channel locale. In order to update content on a default channel language, please use respective management API.
25+
<Callout type='info'>
26+
Translation API allows users to add content translations to any non-default
27+
channel locale. In order to update content on a default channel language,
28+
please use respective management API.
2729
</Callout>
2830

2931
## How does this API work?
@@ -43,10 +45,10 @@ Access to the Translations Admin GraphQL API requires valid API credentials. Gra
4345

4446
#### OAuth scopes
4547

46-
| Name | Permission | Description |
47-
|:-----|:-----------|:------------|
48-
| Store Translations | read-only | View translation details |
49-
| Store Translations | modify | View and modify translation details |
48+
| Name | Permission | Description |
49+
| :----------------- | :--------- | :---------------------------------- |
50+
| Store Translations | read-only | View translation details |
51+
| Store Translations | modify | View and modify translation details |
5052

5153
For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).
5254

‎docs/store-operations/translations/payments.mdx‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
# Translations for Payments (Beta)
2+
3+
The following entities are translatable for payments:
4+
5+
- Display Name as `display_name`
6+
- Payment Instruction as `payment_instruction`
7+
8+
Translations appear in the following storefront views:
9+
10+
- Checkout page (payment methods listing)
11+
- Order confirmation page
12+
- Order email
13+
- My Account page (payment methods and orders)
14+
15+
## Resource fields
16+
17+
For payment method related translation entries, the `resourceId` follows this structure:
18+
19+
`bc/store/paymentMethod/{payment_method_id}.{currency}`
20+
21+
| **Segment** | **Description** |
22+
| ------------------------ | -------------------------------------------------------------------- |
23+
| `bc/store/paymentMethod` | Namespace prefix for payment translation resources. |
24+
| `{payment_method_id}` | Payment method identifier (e.g., `authorizenet.credit_card`). |
25+
| `{currency}` | The ISO currency code configured for the payment method (e.g `USD`). |
26+
27+
A single `resourceId` corresponds to all payment profiles that share the same payment method ID and currency. As a result:
28+
29+
- Translations apply at the payment method \+ currency level.
30+
- If a provider has multiple profiles (e.g., multiple gateway configurations) using the same payment method ID and same currency, they share the same translation resource.
31+
- Updating the translation updates the display for every profile in that set.
32+
33+
### Example
34+
35+
In this example, the payment method is `authorizenet.credit_card` and the currency is `USD`. The translation will be applied to all payment profiles that use the same payment method ID and currency.
36+
37+
`"resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD"`
38+
39+
## Querying Payment Method Translations
40+
41+
This query retrieves all payment method translations for a specific channel and locale, including the original and translated values for display names and payment instructions.
42+
43+
<Tabs items={['Request', 'Response']}>
44+
<Tab>
45+
```graphql
46+
query ListPaymentMethodTranslations {
47+
store {
48+
translations(
49+
filters: {
50+
resourceType: PAYMENT_METHODS
51+
channelId: "bc/store/channel/1"
52+
localeId: "bc/store/locale/en-AU"
53+
}
54+
) {
55+
edges {
56+
node {
57+
resourceId
58+
fields {
59+
fieldName
60+
original
61+
translation
62+
}
63+
}
64+
cursor
65+
}
66+
pageInfo {
67+
hasNextPage
68+
hasPreviousPage
69+
startCursor
70+
endCursor
71+
}
72+
}
73+
}
74+
}
75+
```
76+
</Tab>
77+
<Tab>
78+
```json
79+
{
80+
"data": {
81+
"store": {
82+
"translations": {
83+
"edges": [
84+
{
85+
"node": {
86+
"resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD",
87+
"fields": [
88+
{
89+
"fieldName": "display_name",
90+
"original": "Authorize.Net",
91+
"translation": null
92+
},
93+
{
94+
"fieldName": "payment_instruction",
95+
"original": "",
96+
"translation": null
97+
}
98+
]
99+
},
100+
"cursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA"
101+
}
102+
],
103+
"pageInfo": {
104+
"hasNextPage": false,
105+
"hasPreviousPage": false,
106+
"startCursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA",
107+
"endCursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA"
108+
}
109+
}
110+
}
111+
}
112+
}
113+
```
114+
</Tab>
115+
</Tabs>
116+
117+
## Querying Payment Method Translations by resourceId
118+
119+
<Callout type='info'>
120+
When querying a translation by `resourceId`, you must provide the full `resourceId` in the format `bc/store/paymentMethod/{payment_method_id}.{currency}`.
121+
</Callout>
122+
123+
This query returns a translation by `resourceId`.
124+
125+
<Tabs items={['Request', 'Response']}>
126+
<Tab>
127+
```graphql
128+
query {
129+
store {
130+
translations(
131+
filters: {
132+
resourceType: PAYMENT_METHODS
133+
channelId: "bc/store/channel/1"
134+
localeId: "bc/store/locale/en"
135+
resourceIds: [
136+
"bc/store/paymentMethod/authorizenet.credit_card.USD"
137+
]
138+
}
139+
) {
140+
edges {
141+
node {
142+
resourceId
143+
fields {
144+
fieldName
145+
original
146+
translation
147+
}
148+
}
149+
cursor
150+
}
151+
}
152+
}
153+
}
154+
```
155+
</Tab>
156+
<Tab>
157+
```json
158+
{
159+
"data": {
160+
"store": {
161+
"translations": {
162+
"edges": [
163+
{
164+
"node": {
165+
"resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD",
166+
"fields": [
167+
{
168+
"fieldName": "display_name",
169+
"original": "Authorize.Net",
170+
"translation": null
171+
},
172+
{
173+
"fieldName": "payment_instruction",
174+
"original": "",
175+
"translation": null
176+
}
177+
]
178+
},
179+
"cursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA"
180+
}
181+
]
182+
}
183+
}
184+
}
185+
}
186+
```
187+
</Tab>
188+
</Tabs>
189+
190+
## Update a Payment Method Translation
191+
192+
This mutation updates the translated values for payment method display names and payment instructions for a specific payment method, channel, and locale.
193+
194+
<Tabs items={['Request', 'Response']}>
195+
<Tab>
196+
```graphql
197+
mutation UpdatePaymentMethodTranslations {
198+
translation {
199+
updateTranslations(
200+
input: {
201+
resourceType: PAYMENT_METHODS
202+
channelId: "bc/store/channel/1"
203+
localeId: "bc/store/locale/en-AU"
204+
entities: [
205+
{
206+
resourceId: "bc/store/paymentMethod/authorizenet.credit_card.USD"
207+
fields: [
208+
{ fieldName: "display_name", value: "Translated display" }
209+
{ fieldName: "payment_instruction", value: "Translated instrumention" }
210+
]
211+
}
212+
]
213+
}
214+
) {
215+
errors {
216+
__typename
217+
... on ValidationError {
218+
message
219+
}
220+
... on EntityNotFoundError {
221+
id
222+
message
223+
}
224+
... on InvalidTranslationEntityFieldsError {
225+
id
226+
message
227+
fields
228+
}
229+
}
230+
}
231+
}
232+
}
233+
```
234+
</Tab>
235+
<Tab>
236+
```json
237+
{
238+
"data": {
239+
"translation": {
240+
"updateTranslations": {
241+
"errors": []
242+
}
243+
}
244+
}
245+
}
246+
```
247+
</Tab>
248+
</Tabs>
249+
250+
## Delete a Payment Method Translation
251+
252+
This mutation removes translated values for specified payment method fields, reverting them to the original values for a specific payment method, channel, and locale.
253+
254+
<Tabs items={['Request', 'Response']}>
255+
<Tab>
256+
```graphql
257+
mutation {
258+
translation {
259+
deleteTranslations(
260+
input: {
261+
resourceType: PAYMENT_METHODS
262+
channelId: "bc/store/channel/1"
263+
localeId: "bc/store/locale/en-AU"
264+
resources: [
265+
{
266+
resourceId: "bc/store/paymentMethod/authorizenet.credit_card.USD"
267+
fields: ["display_name", "payment_instruction"]
268+
}
269+
]
270+
}
271+
) {
272+
errors {
273+
__typename
274+
... on ValidationError {
275+
message
276+
}
277+
... on EntityNotFoundError {
278+
id
279+
message
280+
}
281+
... on InvalidTranslationEntityFieldsError {
282+
id
283+
message
284+
fields
285+
}
286+
}
287+
}
288+
}
289+
}
290+
```
291+
</Tab>
292+
<Tab>
293+
```json
294+
{
295+
"data": {
296+
"translation": {
297+
"deleteTranslations": {
298+
"errors": []
299+
}
300+
}
301+
}
302+
}
303+
```
304+
</Tab>
305+
</Tabs>

0 commit comments

Comments
 (0)