- インテグレーションガイドライン
- <<batchIntegration>>のインテグレーションの実装
<<batchIntegration>>のインテグレーションの実装
前提条件
- 加盟店プロファイルが<<batchIntegration>>サービスで有効なことを確認する。
- インテグレーションを開始する前に、「ベストプラクティスとヒント」を確認する。
インテグレーションの手順
手順 1: ゲートウェイへのアクセス
最初の手順として、QNB ALAHLIへの接続を確認します。
手順 2: 入力フィールドを確認する
インテグレーションを構築する前に、入力が必要なフィールドの値を準備しておく必要があります。
手順 3: バッチ要求の作成
要求の本文の作成は、インテグレーションにとって重要な手順です。
手順 4: バッチ要求の送信
取引要求の本文をQNB ALAHLIに確実に安全に送信するための多数のコンポーネントがあります。
手順 5: バッチステータスの取得
バッチが送信されると、定期的にバッチステータスを要求してバッチ処理の現在の状態を決定できます。
手順 6: バッチ応答の処理
バッチの処理が完了すると、アップロードした各操作の結果が含まれている応答ファイルを要求できます。
手順 7: テストと実際の取引処理の開始
テストによって、インテグレーションが想定どおりに動作するかどうかを確認できます。
トラブルシューティングと FAQ
はい、各操作記録行の操作の資格情報(加盟店識別子と認証パスワード)が有効で、認証と承認を正常に実行できる場合は、1 つのバッチ要求で複数の加盟店プロファイルを使用できます。
デフォルトでは、バッチ内の各操作に対する操作資格情報は、バッチ要求ヘッダーで指定された認証資格情報(加盟店識別子とパスワードの両方)を使用します。デフォルトの方法を使用するか、各操作記録行に対して操作資格情報を指定することを選択できます。後者の場合、操作の認証では、操作レベルの資格情報を使用し、デフォルトでは、バッチアップロード資格情報になりません。操作レベルの資格情報が正しくない場合、バッチのアップロードは拒否されます。
以下のサンプルバッチファイルでは、VOID
操作は、加盟店識別子とパスワードが指定されていないため、バッチ要求ヘッダーの資格情報を使用します。
merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency, cardDetails.card.number, cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104169,TXID1,100,AUD,345678901234564,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
バッチの送信は、次のエラー条件が原因で失敗する可能性があります。
シナリオ | エラーメッセージ |
---|---|
SHA-1 メッセージダイジェストが一致しないため、バッチが不完全です | バッチの送信は、次のいずれかの理由で失敗しました。
|
重複するバッチ名
|
バッチの送信に失敗しました。同じ名前のバッチが現在アップロード中であるか、同じ名前で、内容が異なるバッチが既にアップロードされています。ファイルを既にアップロードし始めている場合、アップロードが完了するまでお待ちください。既に使用されているファイル名を使用している場合、ファイル名を変更してもう一度送信してください。 |
バッチを送信するために必要な特権がない場合、認証エラーが返されます。
|
認証に失敗しました。記録 <record number> で指定された資格情報が正しくありません。これは、次の原因で発生する可能性があります。
|
操作レベルでパスワードのみを指定し、加盟店 ID を指定しなかった場合、認証エラーが返されます。 | 認証に失敗しました。バッチファイルの記録 <record number> で、パスワードは指定されましたが、加盟店 ID がありません。加盟店 ID を追加するか、この記録にバッチレベルの加盟店資格情報を使用するためにパスワードを削除してから、要求を再度送信してください。 |
バッチの資格情報の形式が正しくない場合、認証エラーが返されます。 | 認証に失敗しました。ヘッダーで指定された資格情報が次のいずれかの状態です。
|
次の場合、認証エラーが返されます。
|
認証に失敗しました。バッチに指定された資格情報が無効です。資格情報を訂正して、要求を再度送信してください |
ヘッダーに無効な文字が含まれている場合、解析エラーが返されます。 | バッチの送信に失敗しました。ヘッダーに無効な文字が含まれていたため、バッチを解析できませんでした。使用できる文字は次のとおりです。
|
操作記録行にヘッダーに定義された値を上回る値が含まれている場合、解析エラーが返されます。 | バッチの送信に失敗しました。記録 <record number> に、ヘッダーに定義された値を上回る値が含まれていたため、バッチを解析できませんでした。バッチを訂正して、再度送信してください。 |
個別のフィールドの最大サイズを超えた場合、または操作記録で不明な解析エラーが発生した場合、解析エラーが返されます。 | バッチの送信に失敗しました。記録 <record number> でのエラーが原因でバッチを解析できませんでした。バッチがファイル形式に従っていること、正しいエンコーディングを使用していることを確認してから、バッチを再度送信してください。 |
エンコーディングが指定されていない場合、またはサポートされていないエンコーディングが指定された場合、エンコーディングエラーが返されます。 | 要求が失敗しました。指定されたエンコーディングはサポートされていません。サポートされているエンコーディングは UTF-8 と LATIN1 です。サポートされているエンコーディングを使用して要求を再度送信してください。 |
バッチが見つかりません | 要求が失敗しました。このバッチ名のバッチが見つかりません。 バッチ名を訂正して、要求を再度送信してください。 |
指定されたバージョンの長さチェックが失敗しました。 | 要求が失敗しました。指定されたバージョンは無効です。バージョンを訂正して、要求を再度送信してください。 |
指定されたバッチ名の長さチェックが失敗しました。 | 要求が失敗しました。指定されたバッチ名は無効です。バッチ名を訂正して、要求を再度送信してください。 |
指定された加盟店 ID の長さチェックが失敗しました。 | 要求が失敗しました。指定された加盟店 ID は無効です。加盟店 ID を訂正して、要求を再度送信してください。 |
ゲートウェイエラーが発生しました。 | ゲートウェイの内部エラーが原因で要求をゲートウェイに送信できませんでした。後でもう一度やり直してください。 |
<<batchIntegration>> による操作の処理は、次のエラーのいずれかが発生する通信またはシステムの障害が原因で失敗する可能性があります。
- 内部システム障害が原因で発生するエラー
- サーバにその時点で要求を処理するのに十分なリソースがなかったために発生するエラー
- <<tokenization>> 検証取引の処理中に発生するエラー
これが発生し、操作を再試行できる場合、<<batchIntegration>> は、再試行できない応答を操作で受信するまで、または再試行制限に到達するまで、処理のために操作の送信を再試行します。
<<batchIntegration>> では、アップロードされたバッチ名と対応するメッセージ完全性コード(MIC)を保存します。以前に送信されたバッチ名で内容の異なるバッチは識別できるので、<<batchIntegration>> によって拒否されます。
以前に送信されたバッチと名前と内容が同じバッチも識別できるので、<<batchIntegration>> は、以前にアップロードされたバッチと同じステータスを返します。このため、送信に関する問題があったと考えられる場合は、加盟店はバッチが <<batchIntegration>> に正常にアップロードされたかどうかを確認できます。
処理のために送信されるバッチ要求のヘッダー行の値には、<<webServicesIntegration>> NVP フィールド名にある文字のみを使用できます。次の文字を使用できます。
- 英数字(a ~ z、A ~ Z、0 ~ 9)
- ピリオド(.)
- 角かっこ([ ])
解析エラーが発生した場合、<<batchIntegration>> はバッチを拒否します。解析では、バッチを行に分割し、行をフィールドに分割します。
次の場合に解析エラーが発生する可能性があります。
- 操作記録に、ヘッダー記録に含まれているカンマよりも多くのカンマが含まれている
- 個別のフィールドの最大サイズを超過している
処理のためにバッチを再度送信する前にこのエラーを訂正する必要があります。
ベストプラクティスとヒント
<<batchIntegration>>サービスは、バッチファイルで指定された順序と同じ順序で操作を処理することを保証しません。<<batchIntegration>>ディスパッチャーは操作を並行して処理できるからです。この動作が発生する原因は再試行機能の可能性があります。つまり、バッチファイル内の一部の操作が再試行を必要とする場合、準備ができている操作は、指定された順序に関係なく最初に処理されます。たとえば、最初の操作の後に後続の操作が指定されている場合(Authorization の後に Capture、Pay の後に Void)でも、Capture が Authorization の前に行われ、Void が Pay の前に行われる可能性があります。
したがって、順序に厳密に従う必要がある操作では、操作の最初のバッチを最初に実行して、バッチ応答ファイルを待ち、成功したら操作の次のバッチを実行することをお勧めします。
<<tokenization>>はカードの詳細情報をトークンに保存します。<<tokenization>>を<<batchIntegration>>と一緒に使用するには、以下に示すように、バッチファイルでトークン識別子を使用する必要があります。
apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
操作の資格情報には加盟店識別子とパスワードが含まれます。バッチ内の各操作に対する操作資格情報は、デフォルトでは、バッチ要求ヘッダーで指定された認証資格情報(加盟店識別子とパスワードの両方)になります。ただし、操作記録行に対してこれらの両方のフィールドの値を指定しない場合、操作の認証では操作レベルの資格情報を使用し、デフォルトではバッチ資格情報がアップロードされません。
はい。操作タイプが同じ注文に関連していない (同じ注文識別子を含んでいない) 場合、1 つのバッチファイルで複数の操作タイプを処理できます。<<batchIntegration>>サービスは、バッチファイルで指定された順序と同じ順序で操作を処理することを保証しません。<<batchIntegration>>ディスパッチャーは操作を並行して処理できるからです。この動作が発生する原因は再試行機能の可能性があります。つまり、バッチファイル内の一部の操作が再試行を必要とする場合、準備ができている操作は、指定された順序に関係なく最初に処理されます。たとえば、Pay 操作と Void 操作が同じバッチファイルにある場合、Void は Pay の前に行われる可能性があります。ただし、操作が同じ注文に関連していない (異なる注文識別子を含む) 場合、1 つのバッチファイルに複数の操作タイプを含めることができます。
はい。支払セッション識別子を除いて、1 つのバッチファイルでカード詳細の複数のソースを使用できます。複数のソースについては、「カードの詳細情報の複数のソース」を参照してください。
次の例の Authorize 操作では、カード詳細の代わりにトークンを使用します。
apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,