Skip to content

Commit da8e922

Browse files
chris-nowickibc-terra
chris-nowicki
and
bc-terra
authored
DEVDOCS-6664 - Add documentation for Payment Method Translations (#1255)
<!-- Ticket number or summary of work --> # [DEVDOCS-6664] ## What changed? <!-- Provide a bulleted list in the present tense --> * Add documentation for Payment Method Translations (GraphQL Translations Admin API) * Add `docs/store-operations/translations/payments.mdx` with query, update, and delete examples for payment method display names and payment instructions * Update translations index to include payment methods and adjust formatting ## Release notes draft <!-- Provide an entry for the release notes using simple, conversational language. Don't be too technical. Explain how the change will benefit the merchant and link to the feature. Examples: * The newly-released [X feature] is now available to use. Now, you'll be able to [perform Y action]. * We're happy to announce [X feature], which can help you [perform Y action]. * [X feature] helps you to create [Y response] using the [Z query parameter]. Now, you can deliver [ex, localized shopping experiences for your customers]. * Fixed a bug in the [X endpoint]. Now the [Y field] will appear when you click [Z option]. --> * Documentation for Payment Method Translations is now available. You can translate payment method display names and payment instructions for checkout, order confirmation, and My Account using the Translations Admin GraphQL API. ## Anything else? <!-- Add related PRs, salient notes, additional ticket numbers, etc. --> ping @bigcommerce/dev-docs @bc-terra @bc-rowan [DEVDOCS-6664]: https://bigcommercecloud.atlassian.net/browse/DEVDOCS-6664?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ --------- Co-authored-by: Terra Hyde <terra.hyde@bigcommerce.com>
1 parent 07e2d13 commit da8e922

File tree

2 files changed

+313
-6
lines changed

2 files changed

+313
-6
lines changed

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

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

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

30-
<Callout type="info">
31-
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.
30+
<Callout type='info'>
31+
Translation API allows users to add content translations to any non-default
32+
channel locale. In order to update content on a default channel language,
33+
please use respective management API.
3234
</Callout>
3335

3436
## How does this API work?
@@ -48,10 +50,10 @@ Access to the Translations Admin GraphQL API requires valid API credentials. Gra
4850

4951
#### OAuth scopes
5052

51-
| Name | Permission | Description |
52-
|:-----|:-----------|:------------|
53-
| Store Translations | read-only | View translation details |
54-
| Store Translations | modify | View and modify translation details |
53+
| Name | Permission | Description |
54+
| :----------------- | :--------- | :---------------------------------- |
55+
| Store Translations | read-only | View translation details |
56+
| Store Translations | modify | View and modify translation details |
5557

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

‎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)