Konfigurieren Ihrer eigenen Bibliothek

Konfiguration

Sichere Verbindung

Ihre Bibliothek muss eine sichere Verbindung zu einem der beiden Systeme herstellen:

• "https://<DOMAIN>/json/" (für JSON - empfohlen)
• "https://<DOMAIN>/xml/" (für XML)

Ersetzen Sie <DOMAIN> mit einer unterstützten Webservices Domain. Klicken Sie hier für eine vollständige Liste.

Sie sollten sicherstellen, dass es über die folgenden Fähigkeiten verfügt:

• TLSv1.2 oder höhere Fähigkeiten.
• Die Server-Authentifizierung muss durch die Validierung einer Zertifikatskette bis hin zu einer bekannten, vertrauenswürdigen Certificate Authority erfolgen (siehe unten).
• Bei der Serverauthentifizierung muss geprüft werden, ob der Common Name (CN) des Serverzertifikats mit der Domäne übereinstimmt, zu der Sie eine Verbindung herstellen wollen. Wenn Common Name nicht übereinstimmt, sind Sie nicht mit Trust Payments verbunden und die Verbindung MUSS abgelehnt werden.
• Die Server-Authentifizierung muss am Ablaufdatum des Server-Zertifikats erfolgen. Alle abgelaufenen Zertifikate MÜSSEN zurückgewiesen werden.
• Ihre Bibliothek und Ihre Code-Basis müssen gepflegt werden und Sie müssen regelmäßig die neuesten Sicherheits-Patches und/oder Funktionen einspielen.

Ihre SSL/TLS-Richtlinie sollte eine regelmäßige Überprüfung und Aktualisierung dieser Zertifizierungsstellen vorsehen (z. B. einmal im Jahr).

Die Validierung einer Kette zu einem vertrauenswürdigen Certificate Authority bedeutet, dass Ihre Implementierung nicht geändert werden muss, wenn Trust Payments regelmäßig Serverzertifikate aktualisiert. Insbesondere sollten Sie NICHT mit einem einzelnen Zertifikatsfingerabdruck verifizieren, da dieser bei jeder Aktualisierung des Serverzertifikats aktualisiert werden muss und nicht funktioniert, wenn unser verteiltes System verschiedene Einzelzertifikate bereitstellt.

Lastausgleich

Trust Payments setzt den DNS-Lastausgleich ein. Der DNS-Lastausgleich ist so konzipiert, dass eine einzige IP-Adresse zurückgegeben wird, die das bevorzugte Ziel für Ihren Server ist, mit dem er sich zu diesem Zeitpunkt verbindet.

Die DNS-Loadbalancer geben nicht nur eine einzige IP zurück, sondern auch eine niedrige TTL, die derzeit auf weniger als 60 Sekunden eingestellt ist. Diese TTL wurde absichtlich niedrig gehalten, um die Exposition Ihres Servers gegenüber dem gesamten Zahlungssystem zu maximieren. Eine Erhöhung dieser TTL würde diese Exposition verringern, was bedeutet, dass Sie eine IP über einen längeren Zeitraum nutzen. Alle Probleme, die auftreten könnten (geplant oder nicht), werden sich dann auf Ihre Zahlungsabwicklung auswirken.

Trust Payments verfügt über eine Reihe von DNS-Servern, die für die Bereitstellung von DNS-Einträgen verwendet werden. Es ist wichtig, dass Ihr Server in der Lage ist, mit jedem dieser Server eine Verbindung für DNS-Lookups herzustellen. Wenn bei der Kommunikation mit einem DNS-Server ein DNS-Lookup fehlschlägt, müssen die anderen DNS-Server verwendet werden. Wenn Sie nicht alle DNS-Server nutzen, kann es zu Problemen bei der Auflösung von URLs des Zahlungssystems kommen.

Aus der Debug-Perspektive können Sie den folgenden Befehl ausführen, um die aktuelle Liste der verfügbaren DNS-Server zu erhalten:

• Für European Gateway:
  • Windows: nslookup -type=NS securetrading.net
  • Linux: dig NS securetrading.net
• Für US Gateway:
  • Windows: nslookup -type=NS securetrading.us
  • Linux: dig NS securetrading.us

Zeitüberschreitungen

Für den unwahrscheinlichen Fall, dass Ihr System bei der Verbindung mit uns Probleme hat, empfehlen wir Ihnen, für Ihre Lösung geeignete Timeouts zu implementieren. Betrachten Sie dieses Beispiel:

maximum retry number  – 20
maximum retry timeout - 40 Sekunden
maximum connect attempt timeout - 5 Sekunden
send and receive timeout - 60 Sekunden

Versuchen Sie es erneut, bis:

• Die maximum retry number überschritten wird; ODER
• Die maximum retry timeout durch einen weiteren Verbindungsversuch überschritten werden würde.

(Das bedeutet, dass Sie die Verbindung nicht mehr nach 35-40 Sekunden erneut versuchen sollten, da ein Versuch, der die maximum connect attempt timeout von 5 Sekunden würde dazu führen, dass die maximum retry timeout überschritten werden)

Sobald die Verbindung hergestellt ist, warten Sie 60 Sekunden (die send and receive timeout Wert), um die Daten zu senden und zu empfangen, bevor die Verbindung geschlossen wird. Wenn die Verbindung aus irgendeinem Grund unterbrochen wird, nachdem die Datenübertragung begonnen hat, wird nicht empfohlen, die Anfrage erneut zu versuchen.

Verarbeiten Sie Anfragen mit unserer Webservices API

Ihr Server muss nun eine Anfrage mit Ihrer eigenen Bibliothek erstellen. Zum Beispiel:

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "baseamount":"1050",
    "orderreference":"My_Order_123",
    "accounttypedescription":"ECOM",
    "pan":"4111111111111111",
    "expirydate":"12/2022",
    "securitycode":"123"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <payment>
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
      </payment>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

Ihre Bibliothek muss eine sichere Verbindung zu einem der beiden Systeme herstellen:

• "https://<DOMAIN>/json/" (für JSON - empfohlen)
• "https://<DOMAIN>/xml/" (für XML)

Ersetzen Sie <DOMAIN> mit einer unterstützten Webservices Domain. Klicken Sie hier für eine vollständige Liste.

Außerdem müssen Sie den Anfragestring und die Kopfzeilen wie im nachstehenden Beispiel senden:

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "baseamount":"1050",
    "orderreference":"My_Order_123",
    "accounttypedescription":"ECOM",
    "pan":"4111111111111111",
    "expirydate":"12/2022",
    "securitycode":"123"
  }]
}

{
'Content-length': '<LENGTH OF POST>',
'Content-type': 'application/json', 
'Authorization': '<BASIC AUTH CREDENTIALS HERE>', 
'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8'
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <payment>
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
      </payment>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

Content-length: <LENGTH OF POST>
Content-type: text/xml;charset=utf-8
Authorization: <BASIC AUTH CREDENTIALS HERE>
Accept: text/xml

Länge des Inhalts

Content-Length muss die Länge der Anfrage-Bytes im gewählten Zeichensatz sein. Diese muss nach einer eventuellen Zeichenkodierung berechnet werden.

Art des Inhalts

Content-Type wird immer als gesetzt:

• "application/json" (für JSON)
• "text/xml" (für XML)

charset muss der Zeichensatz des Beitrags sein, zum Beispiel "utf-8".

Autorisierung

“Basic “, gefolgt von einer base64 Kodierung Ihrer Webdienste-Anmeldeinformationen im Format Benutzername:Passwort (ohne Leerzeichen).

z.B. für Benutzername webservices@example.com und Passwort pa55word.

Base64 verschlüsseln webservices@example.com:pa55word zu erhalten d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=

Der endgültige Wert, der in die Kopfzeile aufgenommen werden muss, wäre in diesem Fall Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=

Akzeptieren

Das Format der Daten, die an Trust Payments übermittelt werden.

z.B.. text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

Umgang mit der Antwort

Ihr System wird zahlreiche Felder im Antwortobjekt zurückerhalten. Sie müssen den Inhalt dieser Felder interpretieren, um sicherzustellen, dass es sich um die erwarteten Werte handelt.

Nachfolgend ein Beispiel für eine AUTH Antwort:

{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:08:47","livestatus":"0","issuer":"Test Issuer","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"23-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST96","errormessage":"Ok","operatorname":"webservices@example.com","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"zO9"}

<responseblock version="3.67">
<requestreference>X6mh36u8g</requestreference>
<response type="AUTH">
<merchant>
<merchantname>example UNICODE merchantname</merchantname>
<orderreference>AUTH_VISA</orderreference>
<tid>27882788</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>23-9-80006</transactionreference>
<security>
<postcode>2</postcode>
<securitycode>2</securitycode>
<address>2</address>
</security>
<billing>
<amount currencycode="GBP">1050</amount>
<payment type="VISA">
<issuer>Test Issuer</issuer>
<issuercountry>ZZ</issuercountry>
<pan>411111######1111</pan>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST96</authcode>
<timestamp>2012-10-08 12:46:02</timestamp>
<settlement>
<settleduedate>2012-10-08</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<acquirerresponsecode>00</acquirerresponsecode>
<operation>
<splitfinalnumber>1</splitfinalnumber>
<authmethod>PRE</authmethod>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>

Es ist besonders wichtig, die Fehlercode und Abrechnungsstatus Werte, die in der Antwort zurückgegeben werden.

Neben der Bearbeitung von Autorisierungen unterstützt Trust Payments zahlreiche weitere Anfragetypen. Weitere Informationen zu diesen Antragstypen finden Sie auf den anderen Seiten unserer Online-Dokumente.