- インテグレーションガイドライン
- サポートされている機能(支払方法)
- ダイナミックカレンシーコンバージョン
ダイナミックカレンシーコンバージョン
QNB ALAHLI は、商品やサービスの価格に関する DCC プロバイダからのリアルタイムの換算レートをご希望の通貨で提供できます。この為替レートを支払者に提供すると、支払者は希望する通貨またはカードの通貨のいずれかで支払うことを選択できます。カード所有者には、このサービスを利用することで、自身の通貨でいくら課金されるかを購入時に正確に知ることができるという利点があります。
主な利点
- 支払者は、販売の時点で、その課金通貨によって商品やサービスに支払うことができます。
- 通貨換算の手数料の割当額を受け取ります。
- 注文用に設定した通貨で注文が処理されます。
- 支払者のカードの明細書には、自身の通貨で注文金額が表示されます。
- 支払者のカード明細書には、通貨換算手数料が表示されません(提示された換算レートに含まれているため)。
換算レートのための前提条件
- 使用する DCC プロバイダに登録する必要があります。
QNB ALAHLI は、現在、次のプロバイダをサポートしています。
- FEXCO。
QNB ALAHLI を使用した換算レートの管理
次のように、取引に DCC を適用するための 4 つの基本的かつ相互に排他的なシナリオがあります。
- 取引への DCC 適用を希望しません。たとえば、支払者のカードの通貨が希望する通貨と一致する場合などです。
- 検討中だったオファーが実際には存在しないときに DCC を実施します。
- DCC を実施します。DCC プロバイダがオファーを提示しました。支払者にこのオファーを提示しましたが、拒否されました。
- DCC を実施します。DCC プロバイダがオファーを提示しました。支払者にこのオファーを提示し、承諾されました。
Payment Options Inquiry (apiOperation=PAYMENT_OPTIONS_INQUIRY
) リクエストの次のフィールドにデータを提供することで、換算レートをリクエストできます。
order.amount
.order.currency
.paymentType
.提供されている場合、CREDIT
に設定する必要があります。
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND
が返されます。REST プロトコルを使用して、Payment Options Inquiry 操作を呼び出す場合、リクエストパラメータが JSON 本体ではなく、(クエリパラメータとして) URI に含まれている確認してください。以下は、DCC 換算レートのための curl で記述した REST リクエストのサンプルです。
curl --user merchant.TESTMERCHANT-DCC:<PASSWORD>"https://qnbalahli.test.gateway.mastercard.com/api/rest/version/72/merchant/TESTMERCHANT-DCC/paymentOptionsInquiry?order.amount=123.34&order.currency=USD&sourceOfFunds.provided.card.prefix=531335999"
QNB ALAHLI は、DCC オファーに関する次の情報を返します。これらの一部は、支払者に対して、支払画面や PED 端末上に表示される情報に含まれ、スキームや法的要件に沿っています。
currencyConversion.gatewayCode
:QUOTE_PROVIDED
:換算レートが提供されます。NOT_ELIGIBLE
:このカードまたは通貨(あるいはその両方)には DCC を使用できません。UNSUPPORTED_CARD_BRAND
:サポートされていないカードブランドです。INSUFFICIENT_INFORMATION
:リクエストに必須フィールドが指定されていません。ERROR
:DCC プロバイダがこの操作を処理できません。
currencyConversion.provider
:DCC 換算レートプロバイダの名前。currencyConversion.providerCode
:DCC プロバイダによって生成され、DCC 換算レートリクエストの正常終了またはその他のステータスを要約します。currencyConversion.providerReceipt
:換算レートに対する DCC プロバイダの一意の照会(常に提供されるわけではありません)。currencyConversion.exchangeRateSource
:為替レートのソースとして使用される財務データ代理店。currencyConversion.payerExchangeRate
:取引金額を支払者の通貨に変換するために使用される為替レート。これにはcurrencyConversion.marginPercentage
が含まれます。currencyConversion.payerAmount
:支払者の通貨での取引の総額。currencyConversion.payerCurrency
:DCC プロバイダによって提示された DCC 換算レートの通貨。currencyConversion.marginPercentage
:変換サービスを提供するために、取引金額に対する割合で適用される外国為替のマークアップ。currencyConversion.exchangeRateTime
:変換レートが有効になる時間を表すタイムスタンプ。currencyConversion.quoteExpiry
:DCC 換算レートオファーの有効期限を示すタイムスタンプ。(常に提供されるわけではありません)currencyConversion.offerText
:DCC オファーのための入力フォームを含む HTML の部分。これは、支払者の選択肢を収集するために支払者に提示する必要があります。currencyConversion.requestId
:PAYMENT_OPTIONS_INQUIRY レスポンスで返される、DCC 換算レートリクエストの一意の識別子。
-
DCC プロバイダ(
currencyConversion.gatewayCode=QUOTE_PROVIDED
)から換算レートを取得する場合、支払者に通貨換算オファーを提示できます。換算レートのオファーオファーのテキスト
Visa および Mastercard には、情報に基づいた選択をするために支払者に必要な情報を提示するために、支払者に DCC 情報を表示するための特定の要件があります。これには、DCC オファーや取引領収書(支払者がオファーを承諾した場合)の中の手数料および料金の詳細が含まれます。
DCC 規制の基本原則:
- カード所有者は、取引の詳細を完全に把握したうえで、加盟店の通貨で支払うか、カード所有者の自国通貨で支払かを選択できます。
- カード所有者には、DCC オファーを承諾するか拒否するかの選択肢が与えられます。
- カード所有者には、DCC に関連する利用規約が完全に開示されます。
オファーの提示
paymentTypes.card.currencyConversion.offerText
の中にオファーのテキストが提示されます。locale=<Valid language identifier or IETF language tag of payer's locale>
を設定することで、オファーテキストのロケールを指定できます(例: 英語にはen
、ブラジルポルトガル語にはpt-BR
、メキシコスペイン語にはes-MX
)。以下のサポート対象のロケールには、ロケール固有の HTML 形式の DCC オファーテキストが
paymentTypes.card.currencyConversion.offerText
に返されます。- フランス語(fr_FR)
- ドイツ語(de_DE)
- メキシコスペイン語(es_MX)
- 中国語:
- 簡体字中国語(zh_CN)
- 香港中国語(zh_HK)
- ブラジルポルトガル語(pt_BR)
- 日本語(ja_JP)
- インドネシア語(id_ID)
- 英語:
- 米国(en_US)
- 英国(en_UK)
- オーストラリア(en_AU)
ロケールがサポートされていない場合、QNB ALAHLI は次のスキームに従ってオファーテキストを提示します。
- 言語コードは、最も近いサポート対象のロケール(ある場合)に照合されます。
interaction.locale
が設定されていないか、提示したロケールと基本言語がサポートされていない場合、QNB ALAHLI は設定済みのデフォルトロケールを使用しようとします。そのロケールと基本言語がサポートされていない場合、オファーはen_US
で提示されます。
支払者は、次の中から選べます。
-
DCC オファーを承諾し、カード通貨で支払うことを選択します。
この場合、次のパラメータを使用して取引リクエストを開始します。
- QNB ALAHLI からのレスポンスで返される
currencyConversion.requestId
。 currencyConversion.uptake=ACCEPTED.
RETRIEVE_TRANSACTION
レスポンスのpaymentTypes.card.currencyConversion.receiptText
で提供されるレシートテキストを支払者に提示します。これはオファーテキストと同じロケールを使用します。支払いを実施する前に 3D セキュアサービスを利用して支払者を認証する場合は、Check 3DS Enrollment 操作でこれらの DCC フィールドも渡す必要があります。 - QNB ALAHLI からのレスポンスで返される
-
DCC オファーを拒否し、注文通貨で支払うことを選択します(
currencyConversion.uptake=DECLINED
)。この場合、次のパラメータを使用して取引リクエストを開始します。
- QNB ALAHLI からのレスポンスで返される
currencyConversion.requestId
。 currencyConversion.uptake=DECLINED.
- QNB ALAHLI からのレスポンスで返される
-
Payment Options Inquiry レスポンスで次のいずれかを受信した場合:
currencyConversion.gatewayCode=UNSUPPORTED_CARD_BRAND
currencyConversion.gatewayCode=NOT_ELIGIBLE
currencyConversion.gatewayCode=ERROR
取引リクエストに
currencyConversion.uptake=NOT_AVAILABLE
を設定し、正しいcurrencyConversion.requestId
を指定する必要があります。
これにより、DCC プロバイダが分析とレポートにデータを使用できます。
QNB ALAHLI 以外から換算レートを取得した場合は、DCC プロバイダが取引リクエストで返した DCC の詳細を明示的に提示する必要があります。
Capture/Refund DCC Transactions
Authorize 取引リクエストでは、DCC の詳細を提供する必要があります。DCC の詳細は注文の決済請求に適用されます。
全額決済請求には、Authorize リクエストの DCC の詳細が使用されます。
部分的決済請求または超過決済請求には、QNB ALAHLI が割合の案分として金額を計算します。
QNB ALAHLI の中で DCC に関して MSO によって設定されている場合、この設定が以降の返金に適用されます。
設定オプション:
CURRENT
:返金取引日の実際のレートを提供するために新しい換算レートがリクエストされます。HISTORICAL
:注文が作成されたときに使用されたレートが返金に適用されます。
初回取引で currencyConversion.uptake=ACCEPTED
の場合:
- 設定は
CURRENT
です。- 特定の返金額に対し、換算レートがリクエストされます。これにより新しい
currencyConversion.requestId
が生成されます。新しい換算レートが返金に適用されます。 - 取引応答が
currencyConversion.uptake=ACCEPTED
を返します。
- 特定の返金額に対し、換算レートがリクエストされます。これにより新しい
- 設定は
HISTORICAL
です。- 注文の開始取引のために提供された DCC の詳細が、返金の
currencyConversion.payerAmount
を計算するのに使用されます。 - 部分返金または超過返金の金額については、初回取引の
currencyConversion.payerAmount
が加盟店金額の割合の案分ベースで提供されます。案分が適用される際には標準の四捨五入が使用されます。 - 決済請求金額を全額返金するのに部分返金を使用する場合、最後の部分返金に決済請求の支払者未払い金額が含まれます。これは、部分的な金額の四捨五入を考慮するために実施されます。返金総額が決済請求の総額と等しくない場合、支払者の金額(例: 超過返金)に対する検証は行われません。
- 取引応答が
currencyConversion.uptake=ACCEPTED
を返します。
- 注文の開始取引のために提供された DCC の詳細が、返金の
初回取引で currencyConversion.uptake=DECLINED
、NOT_AVAILABLE
、または NOT_REQUIRED
の場合:
最初の承認と決済請求が非 DCC 取引として正常に処理され、その後、返金リクエストを送信した場合、加盟店の設定とは無関係に以下のようになります。
- 換算レートはリクエストされません。
- 返金取引応答または Retrieve Transaction 操作で
currencyConversion
フィールドが返されません。
DCC インテグレーションのテスト
テスト用加盟店プロファイルを使用して、DCC インテグレーションをテストできます。