Selecting a currency
Learn how to determine whether a currency is supported and how it is prioritized.
You're required to specify currency when creating a Checkout or Invoice. Additionally, the value you provide must consist of three alphabetic letters that conform to the ISO 4217 standard.
However, not all currencies contained in the ISO 4217 list are supported in the Digital River API. Instead, you can only pass a currency that is supported by the payment method used to fund the transaction. In the Payments integration section, for each supported payment method, you can find a list of these currencies .
You should also remember that the currency you send in a POST/checkouts, POST/checkouts/{id}, or POST/invoices request always takes priority over the value you pass when creating the transaction's payment source.

Supported currencies

For each supported payment method, our documentation provides you a list of currencies that can be included in a create or update Checkout request or a create Invoice request.
If the currency sent in any of these requests is not supported, you receive a 409 Conflict error with a currency not yet activated code and message:
409 Conflict
1
{
2
"type": "conflict",
3
"errors": [
4
{
5
"code": "currency_unactivated",
6
"parameter": "currency",
7
"message": "Currency 'PAB' is not activated."
8
}
9
]
10
}
Copied!
You might also receive a 409 Conflict response that contains a code of invalid_parameter. In this case, the error could have been thrown because currency consisted of incorrect characters, an obsolete, Euro-zone currency, or another currency no longer in circulation.
409 Conflict
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "currency",
7
"message": "'YEM' is not a valid currency."
8
}
9
]
10
}
Copied!

How currency is prioritized

When you create a payment source, some payment methods require you to specify a currency while for others it's optional. However, if you do pass currency when creating a source, and then apply that source to a transaction, the source's currency value doesn't need to match the value of the checkout or invoice. Both values just have to be supported by the underlying payment method. This is due to the fact that a transaction's currency is ultimately determined by the payment session.
However, the checkout's currency always takes priority over the payment source's currency. In other words, when the order is submitted, we generate a charge in the checkout's currency.
The following example demonstrates this concept. In this case, a payment source created in USD is attached to a checkout with a currency of HKD. After the checkout is converted to an order, the response from the Orders API returns a payment.charges[].currency of HKD.
Source
Checkout
Order
1
{
2
"clientId": "gc",
3
"channelId": "headless",
4
"liveMode": false,
5
"id": "721adac5-cbfa-4f4f-989b-58414dd231c3",
6
"clientSecret": "721adac5-cbfa-4f4f-989b-58414dd231c3_1e2b0d18-d57f-4033-b4c9-ce1e8a83e7cc",
7
"type": "creditCard",
8
"reusable": false,
9
"owner": {
10
"firstName": "William",
11
"lastName": "Brown",
12
"email": "[email protected]",
13
"address": {
14
"line1": "10381 Bren Rd W",
15
"city": "Minnetonka",
16
"state": "MN",
17
"country": "US",
18
"postalCode": "55343"
19
}
20
},
21
"state": "chargeable",
22
"creationIp": "209.87.180.27",
23
"createdTime": "2021-04-30T19:16:51.525Z",
24
"updatedTime": "2021-04-30T19:16:51.525Z",
25
"flow": "standard",
26
"browserInfo": {
27
"userAgent": "PostmanRuntime/7.28.0",
28
"acceptHeader": "*/*",
29
"browserIp": "209.87.180.27"
30
},
31
"creditCard": {
32
"brand": "Visa",
33
"expirationMonth": 7,
34
"expirationYear": 2027,
35
"lastFourDigits": "1111",
36
"paymentIdentifier": "00700"
37
}
38
}
Copied!
1
{
2
"id": "b6992697-e621-4043-8e5a-1a7898320c9c",
3
"createdTime": "2021-04-30T19:15:52Z",
4
"currency": "HKD",
5
"email": "[email protected]",
6
"shipTo": {
7
"address": {
8
"line1": "10380 Bren Road W",
9
"city": "Minnetonka",
10
"postalCode": "55343",
11
"state": "MN",
12
"country": "US"
13
},
14
"name": "John Doe"
15
},
16
"shipFrom": {
17
"address": {
18
"country": "US"
19
}
20
},
21
"totalAmount": 26.89,
22
"subtotal": 25.0,
23
"totalFees": 0.0,
24
"totalTax": 1.89,
25
"totalImporterTax": 0.0,
26
"totalDuty": 0.0,
27
"totalDiscount": 0.0,
28
"totalShipping": 5.0,
29
"items": [
30
{
31
"id": "5e59eb4f-f2fb-4741-981c-5c5e2cff88b2",
32
"skuId": "9289476d-660a-4631-abf4-9bf48f260449",
33
"amount": 20.0,
34
"quantity": 2,
35
"tax": {
36
"rate": 0.07525,
37
"amount": 1.51
38
},
39
"importerTax": {
40
"amount": 0.0
41
},
42
"duties": {
43
"amount": 0.0
44
},
45
"fees": {
46
"amount": 0.0,
47
"taxAmount": 0.0
48
}
49
}
50
],
51
"shippingChoice": {
52
"amount": 5.0,
53
"description": "standard",
54
"serviceLevel": "SG",
55
"taxAmount": 0.38
56
},
57
"updatedTime": "2021-04-30T19:15:52Z",
58
"locale": "en_US",
59
"customerType": "individual",
60
"sellingEntity": {
61
"id": "C5_INC-ENTITY",
62
"name": "DR globalTech Inc."
63
},
64
"liveMode": false,
65
"payment": {
66
"sources": [
67
{
68
"id": "721adac5-cbfa-4f4f-989b-58414dd231c3",
69
"type": "creditCard",
70
"amount": 26.89,
71
"owner": {
72
"firstName": "William",
73
"lastName": "Brown",
74
"email": "[email protected]",
75
"address": {
76
"line1": "10381 Bren Rd W",
77
"city": "Minnetonka",
78
"postalCode": "55343",
79
"state": "MN",
80
"country": "US"
81
}
82
},
83
"creditCard": {
84
"brand": "Visa",
85
"expirationMonth": 7,
86
"expirationYear": 2027,
87
"lastFourDigits": "1111"
88
}
89
}
90
],
91
"session": {
92
"id": "b22ac65b-499c-4809-8737-bf0b5ec2e447",
93
"amountContributed": 26.89,
94
"amountRemainingToBeContributed": 0.0,
95
"state": "requires_confirmation",
96
"clientSecret": "b22ac65b-499c-4809-8737-bf0b5ec2e447_0b250864-490c-447d-8dde-9d85d6c013bf"
97
}
98
}
99
}
Copied!
1
{
2
"id": "188601460336",
3
"createdTime": "2021-04-30T19:23:13Z",
4
"currency": "HKD",
5
"email": "[email protected]",
6
"shipTo": {
7
"address": {
8
"line1": "10380 Bren Road W",
9
"city": "Minnetonka",
10
"postalCode": "55343",
11
"state": "MN",
12
"country": "US"
13
},
14
"name": "John Doe"
15
},
16
"shipFrom": {
17
"address": {
18
"country": "US"
19
}
20
},
21
"billTo": {
22
"address": {
23
"line1": "10381 Bren Rd W",
24
"city": "Minnetonka",
25
"postalCode": "55343",
26
"state": "MN",
27
"country": "US"
28
},
29
"name": "William Brown",
30
"email": "[email protected]"
31
},
32
"totalAmount": 26.89,
33
"subtotal": 25.0,
34
"totalFees": 0.0,
35
"totalTax": 1.89,
36
"totalImporterTax": 0.0,
37
"totalDuty": 0.0,
38
"totalDiscount": 0.0,
39
"totalShipping": 5.0,
40
"items": [
41
{
42
"id": "110117910336",
43
"skuId": "9289476d-660a-4631-abf4-9bf48f260449",
44
"amount": 20.0,
45
"quantity": 2,
46
"state": "created",
47
"stateTransitions": {
48
"created": "2021-04-30T19:23:13Z"
49
},
50
"tax": {
51
"rate": 0.07525,
52
"amount": 1.51
53
},
54
"importerTax": {
55
"amount": 0.0
56
},
57
"duties": {
58
"amount": 0.0
59
},
60
"availableToRefundAmount": 0.0,
61
"fees": {
62
"amount": 0.0,
63
"taxAmount": 0.0
64
}
65
}
66
],
67
"shippingChoice": {
68
"amount": 5.0,
69
"description": "standard",
70
"serviceLevel": "SG",
71
"taxAmount": 0.38
72
},
73
"updatedTime": "2021-04-30T19:23:13Z",
74
"locale": "en_US",
75
"customerType": "individual",
76
"sellingEntity": {
77
"id": "C5_INC-ENTITY",
78
"name": "DR globalTech Inc."
79
},
80
"liveMode": false,
81
"payment": {
82
"charges": [
83
{
84
"id": "82cbbfa5-e324-46fd-971c-7130eb10ccd3",
85
"createdTime": "2021-04-30T19:23:16Z",
86
"currency": "HKD",
87
"amount": 26.89,
88
"state": "capturable",
89
"captured": false,
90
"refunded": false,
91
"sourceId": "721adac5-cbfa-4f4f-989b-58414dd231c3",
92
"type": "customer_initiated"
93
}
94
],
95
"sources": [
96
{
97
"id": "721adac5-cbfa-4f4f-989b-58414dd231c3",
98
"type": "creditCard",
99
"amount": 26.89,
100
"owner": {
101
"firstName": "William",
102
"lastName": "Brown",
103
"email": "[email protected]",
104
"address": {
105
"line1": "10381 Bren Rd W",
106
"city": "Minnetonka",
107
"postalCode": "55343",
108
"state": "MN",
109
"country": "US"
110
}
111
},
112
"creditCard": {
113
"brand": "Visa",
114
"expirationMonth": 7,
115
"expirationYear": 2027,
116
"lastFourDigits": "1111"
117
}
118
}
119
],
120
"session": {
121
"id": "b22ac65b-499c-4809-8737-bf0b5ec2e447",
122
"amountContributed": 26.89,
123
"amountRemainingToBeContributed": 0.0,
124
"state": "complete",
125
"clientSecret": "b22ac65b-499c-4809-8737-bf0b5ec2e447_0b250864-490c-447d-8dde-9d85d6c013bf"
126
}
127
},
128
"state": "accepted",
129
"stateTransitions": {
130
"accepted": "2021-04-30T19:23:16Z"
131
},
132
"fraudState": "passed",
133
"fraudStateTransitions": {
134
"passed": "2021-04-30T19:23:16Z"
135
},
136
"requestToBeForgotten": false,
137
"capturedAmount": 0.0,
138
"cancelledAmount": 0.0,
139
"availableToRefundAmount": 0.0,
140
"checkoutId": "b6992697-e621-4043-8e5a-1a7898320c9c"
141
}
Copied!
Last modified 8mo ago