Selecting a currency
Learn how to determine whether a currency is supported and how it is prioritized.
However, not all currencies contained in the ISO 4217 list are supported in the Digital River APIs. Instead, the
currency
you pass must be supported by the payment method used to fund the transaction. You should also remember that the
currency
you send in a POST/checkouts
or POST/checkouts/{id}
always takes priority over the value you pass when creating the payment source.To access a list of available currencies for each supported payment method, refer to the Payment method guide.
If the
currency
you send in a create or update Checkout request is not supported by the source, you receive the following error:409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "currency_unactivated",
"parameter": "currency",
"message": "Currency 'PAB' is not activated."
}
]
}
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
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "currency",
"message": "'YEM' is not a valid currency."
}
]
}
For some payment methods, it's required that you set
currency
in the configuration object of createSource()
, while for others it's optional. However, if you do pass
currency
, and then attach the source to a checkout, the source's currency
doesn't need to match the checkout's currency
. Both values just have to be supported by the underlying payment method. The checkout's
currency
always takes priority over the source's currency
. This means, upon order creation, 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 order's payment.charges[].currency
is also HKD
.Source
Checkout
Order
{
"clientId": "gc",
"channelId": "headless",
"liveMode": false,
"id": "721adac5-cbfa-4f4f-989b-58414dd231c3",
"clientSecret": "721adac5-cbfa-4f4f-989b-58414dd231c3_1e2b0d18-d57f-4033-b4c9-ce1e8a83e7cc",
"type": "creditCard",
"reusable": false,
"owner": {
"firstName": "William",
"lastName": "Brown",
"email": "[email protected]",
"address": {
"line1": "10381 Bren Rd W",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"state": "chargeable",
"creationIp": "209.87.180.27",
"createdTime": "2021-04-30T19:16:51.525Z",
"updatedTime": "2021-04-30T19:16:51.525Z",
"flow": "standard",
"browserInfo": {
"userAgent": "PostmanRuntime/7.28.0",
"acceptHeader": "*/*",
"browserIp": "209.87.180.27"
},
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111",
"paymentIdentifier": "00700"
}
}
{
"id": "b6992697-e621-4043-8e5a-1a7898320c9c",
"createdTime": "2021-04-30T19:15:52Z",
"currency": "HKD",
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "John Doe"
},
"shipFrom": {
"address": {
"country": "US"
}
},
"totalAmount": 26.89,
"subtotal": 25.0,
"totalFees": 0.0,
"totalTax": 1.89,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.0,
"items": [
{
"id": "5e59eb4f-f2fb-4741-981c-5c5e2cff88b2",
"skuId": "9289476d-660a-4631-abf4-9bf48f260449",
"amount": 20.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.51
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"shippingChoice": {
"amount": 5.0,
"description": "standard",
"serviceLevel": "SG",
"taxAmount": 0.38
},
"updatedTime": "2021-04-30T19:15:52Z",
"locale": "en_US",
"customerType": "individual",
"sellingEntity": {
"id": "C5_INC-ENTITY",
"name": "DR globalTech Inc."
},
"liveMode": false,
"payment": {
"sources": [
{
"id": "721adac5-cbfa-4f4f-989b-58414dd231c3",
"type": "creditCard",
"amount": 26.89,
"owner": {
"firstName": "William",
"lastName": "Brown",
"email": "[email protected]",
"address": {
"line1": "10381 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
}
}
],
"session": {
"id": "b22ac65b-499c-4809-8737-bf0b5ec2e447",
"amountContributed": 26.89,
"amountRemainingToBeContributed": 0.0,
"state": "requires_confirmation",
"clientSecret": "b22ac65b-499c-4809-8737-bf0b5ec2e447_0b250864-490c-447d-8dde-9d85d6c013bf"
}
}
}
{
"id": "188601460336",
"createdTime": "2021-04-30T19:23:13Z",
"currency": "HKD",
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "John Doe"
},
"shipFrom": {
"address": {
"country": "US"
}
},
"billTo": {
"address": {
"line1": "10381 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "William Brown",
"email": "[email protected]"
},
"totalAmount": 26.89,
"subtotal": 25.0,
"totalFees": 0.0,
"totalTax": 1.89,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.0,
"items": [
{
"id": "110117910336",
"skuId": "9289476d-660a-4631-abf4-9bf48f260449",
"amount": 20.0,
"quantity": 2,
"state": "created",
"stateTransitions": {
"created": "2021-04-30T19:23:13Z"
},
"tax": {
"rate": 0.07525,
"amount": 1.51
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"availableToRefundAmount": 0.0,
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"shippingChoice": {
"amount": 5.0,
"description": "standard",
"serviceLevel": "SG",
"taxAmount": 0.38
},
"updatedTime": "2021-04-30T19:23:13Z",
"locale": "en_US",
"customerType": "individual",
"sellingEntity": {
"id": "C5_INC-ENTITY",
"name": "DR globalTech Inc."
},
"liveMode": false,
"payment": {
"charges": [
{
"id": "82cbbfa5-e324-46fd-971c-7130eb10ccd3",
"createdTime": "2021-04-30T19:23:16Z",
"currency": "HKD",
"amount": 26.89,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "721adac5-cbfa-4f4f-989b-58414dd231c3",
"type": "customer_initiated"
}
],
"sources": [
{
"id": "721adac5-cbfa-4f4f-989b-58414dd231c3",
"type": "creditCard",
"amount": 26.89,
"owner": {
"firstName": "William",
"lastName": "Brown",
"email": "[email protected]",
"address": {
"line1": "10381 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
}
}
],
"session": {
"id": "b22ac65b-499c-4809-8737-bf0b5ec2e447",
"amountContributed": 26.89,
"amountRemainingToBeContributed": 0.0,
"state": "complete",
"clientSecret": "b22ac65b-499c-4809-8737-bf0b5ec2e447_0b250864-490c-447d-8dde-9d85d6c013bf"
}
},
"state": "accepted",
"stateTransitions": {
"accepted": "2021-04-30T19:23:16Z"
},
"fraudState": "passed",
"fraudStateTransitions": {
"passed": "2021-04-30T19:23:16Z"
},
"requestToBeForgotten": false,
"capturedAmount": 0.0,
"cancelledAmount": 0.0,
"availableToRefundAmount": 0.0,
"checkoutId": "b6992697-e621-4043-8e5a-1a7898320c9c"
}
Last modified 6mo ago