Der folgende Inhalt setzt voraus, dass Sie die erforderliche PCI-Zertifizierung erhalten haben, um sensible Karteninhaberdaten in der Anfrage an unsere Webservices API zu verarbeiten und zu übermitteln.
Lesen Sie diesen Artikel, um mehr zu erfahren.
Sie dürfen niemals sensible Zahlungsdaten auf Ihrem Server speichern
Bitte stellen Sie sicher, dass alle zusätzlichen Debugging-Funktionen, die während der Tests Ihrer Integration aktiviert wurden, vor der Inbetriebnahme deaktiviert werden. Andernfalls kann es zu einem Verstoß gegen die Anforderungen kommen, die zur Einhaltung der PCI-Vorschriften erforderlich sind.
Bevor Sie beginnen, benötigen Sie einen Benutzernamen und ein Passwort für Web Services, damit wir Ihre Anfragen authentifizieren können
Sie können einen Webdienst-Benutzer über unsere MyST-Schnittstelle erstellen. Ihr System muss diesen Benutzernamen in jeder Anfrage zusammen mit dem Passwort übermitteln. In unseren Anfragebeispielen verwenden wir einen Platzhalter-Benutzernamen und ein Passwort, die Sie vor dem Testen durch Ihre eigenen Anmeldedaten ersetzen müssen.
Wenn Sie noch keine Zugangsdaten für die Webdienste haben, klicken Sie hier, um zu erfahren, wie Sie diese konfigurieren können.
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.
Alle Verbindungen zwischen Ihrem Server und Trust Payments Web Services müssen ordnungsgemäß authentifiziert und verschlüsselt werden.
Trust Payments verwendet eine dem Industriestandard entsprechende hochsichere TLS-Verschlüsselung. Wir empfehlen Ihnen, eine aktuelle SSL/TLS-Bibliotheksimplementierung für die von Ihnen gewählte Sprache zu verwenden.
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.
Trust Payments verwendet die Digicert Certificate Authority , um alle Zertifikate zu signieren. Ihre SSL/TLS-Bibliothek muss so konfiguriert sein, dass sie allen Digicert Zertifikaten vertraut:
https://www.digicert.com/digicert-root-certificates.htm
Hinweis: Bei den meisten aktuellen Betriebssystemen sollten die Digicert Roots-Zertifikate standardmäßig als vertrauenswürdig eingestuft und in den Vertrauensspeicher aufgenommen werden, d. h. die meisten Händler müssen nichts unternehmen, um diese Anforderung zu erfüllen. Wenn Händler jedoch nicht den eingebauten Vertrauensspeicher des Betriebssystems verwenden und stattdessen ihren eigenen Vertrauensspeicher erstellen, sollten sie alle Digicert Root-Zertifikate zu ihrem benutzerdefinierten Vertrauensspeicher hinzufügen, da unsere Zertifikate in Zukunft von jedem der aktiven Digicert Root-Zertifikate signiert werden könnten.
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.
Die meisten SSL/TLS-Bibliotheksimplementierungen erfüllen alle oben genannten Anforderungen, müssen aber möglicherweise konfiguriert werden, um sie zu aktivieren. Es liegt in Ihrer Verantwortung, sicherzustellen, dass alle diese Sicherheitsanforderungen korrekt aktiviert sind; andernfalls kann die Sicherheit der Verbindungen gefährdet sein. Es liegt auch in Ihrer Verantwortung, dafür zu sorgen, dass das Betriebssystem und die Software, die für die Verbindungen verwendet werden, mit Sicherheits-Patches auf dem neuesten Stand gehalten werden.
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.
Vor jeder an Webservices übermittelten Anfrage müssen Sie einen DNS-Lookup für die richtige Domäne in Ihrer Anwendung durchführen, um die IP eines verfügbaren Gateways zu erhalten.
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.
Halten Sie sich unbedingt an die von Trust Payments vorgegebene TTL und aktualisieren Sie Ihre DNS-Einträge, wenn die TTL abläuft.
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
- Windows:
- Für US Gateway:
- Windows:
nslookup -type=NS securetrading.us
- Linux:
dig NS securetrading.us
- Windows:
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.
Die oben vorgeschlagene Timeout-Implementierung ist eine Beispiellösung. Sie müssen die Anforderungen Ihrer eigenen Anwendung berücksichtigen und Timeouts implementieren, die Ihren Anforderungen am besten entsprechen.
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>
Wir akzeptieren alle Unicode-Zeichen in Ihrer Anfrage. Die verwendete Kodierung ist UTF-8, ein Multi-Byte-Kodierungsschema. Alle Antworten von uns werden mit UTF-8 kodiert. Ihr System muss darauf vorbereitet sein, alle gültigen Antworten in dieser Kodierung zu akzeptieren.
Sie müssen Ihre Firewall für unsere Webdienste-IPs öffnen, die auf dieser Webseite aufgeführt sind .
Bitte stellen Sie sicher, dass Sie diese Seite regelmäßig auf Aktualisierungen unserer IPs überprüfen.
Um die strengen Sicherheitsanforderungen zu erfüllen, können wir bei der Nutzung unserer Cross-origin resource sharing (CORS) Dienste die Herkunft https://localhost nicht akzeptieren.
Sie müssen eine gültige Domain verwenden, die über Trust Payments erreichbar ist.
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
Wie man eine Kopfzeile erstellt
Alle Anfragen, die über unsere Webservices API an Trust Payments übermittelt werden, müssen mit einer Reihe von Kopfzeilen beginnen, wie unten definiert. Wir verwenden diese, um eingehende Anfragen zu identifizieren und zu verwalten.
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".
Jede Anfrage muss entsprechend der im Header angegebenen Zeichenkodierung korrekt kodiert sein
Unser System akzeptiert alle Unicode-Zeichen. Die Standardkodierung für JSON ist UTF-8 (ein Multi-Byte-Kodierungsschema). Die meisten JSON-Parser verarbeiten dies automatisch.
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.
Zusammenfassung
Jetzt sollten Sie in der Lage sein, eine einfache Anfrage mit unserer Webservices API zu bearbeiten.
Nächste Schritte
- Es wird empfohlen, die in der Antwort zurückgegebenen Felder zu überprüfen.
- In unseren zusätzlichen Dokumenten können Sie sich über weitere Funktionen informieren, die im Rahmen Ihrer Implementierung konfiguriert werden können.
- Sobald Sie Ihre Lösung gründlich getestet haben, können Sie die Live-Schaltung beantragen und mit der Verarbeitung von Live-Zahlungen beginnen!