Uw eigen bibliotheek configureren

De volgende inhoud gaat ervan uit dat u de noodzakelijke PCI-certificering hebt verkregen om gevoelige kaarthoudergegevens te verwerken en in te dienen in het verzoek aan onze Webservices API.
Lees dit artikel voor meer informatie.

  U mag nooit gevoelige betalingsgegevens op uw server vastleggen

Zorg ervoor dat alle extra debugging die tijdens het testen van uw integratie is ingeschakeld, wordt uitgeschakeld voordat u live gaat. Doet u dit niet, dan kan dit in strijd zijn met de vereisten om PCI compliance te behouden.

  Voordat u begint, heeft u een Web Services gebruikersnaam en wachtwoord nodig, zodat wij uw verzoeken kunnen verifiëren.

U kunt een Web Services gebruiker aanmaken via onze MyST interface. Uw systeem zal deze gebruikersnaam in elk verzoek moeten opnemen, samen met het wachtwoord. In onze aanvraagvoorbeelden gebruiken we een placeholder gebruikersnaam en wachtwoord, die u moet vervangen door uw eigen gegevens voordat u gaat testen.

Als u nog geen Web Services credentials heeft, klik dan hier om te leren hoe u dit kunt configureren.

 

Configuratie

Beveiligde verbinding

Uw bibliotheek moet een beveiligde verbinding tot stand brengen:

  • "https://<DOMAIN>/json/" (voor JSON - aanbevolen)
  • "https://<DOMAIN>/xml/" (voor XML)

Vervang <DOMAIN> met een ondersteund Webservices domein. Klik hier voor een volledige lijst.

Alle verbindingen tussen uw server en Trust Payments Web Services moeten correct worden geauthenticeerd en gecodeerd
Trust Payments maakt gebruik van TLS-encryptie van hoge kwaliteit. Wij raden u aan een actuele SSL/TLS-bibliotheekimplementatie te gebruiken voor de door u gekozen taal.

U moet ervoor zorgen dat het de volgende mogelijkheden heeft:

  • TLSv1.2 of hoger.
  • Serververificatie moet worden uitgevoerd door validatie van een certificaatketen tot een bekende, vertrouwde Certificate Authority (zie hieronder).
  • De serververificatie moet controleren of de Common Name (CN) van het servercertificaat overeenkomt met het domein waarmee u verbinding maakt. Als de Common Name niet overeenkomt, bent u niet verbonden met Trust Payments en MOET de verbinding worden geweigerd.
  • Serverauthenticatie moet plaatsvinden op de vervaldatum van het servercertificaat. Verlopen certificaten MOETEN worden geweigerd.
  • Uw bibliotheek en codebasis moeten worden onderhouden en u moet regelmatig updaten naar de laatste beveiligingspatches en/of functies.

Trust Payments gebruikt de Digicert Certificate Authority om alle certificaten te ondertekenen. Uw SSL/TLS-bibliotheek moet worden geconfigureerd om alle Digicert certificaten te vertrouwen:
https://www.digicert.com/digicert-root-certificates.htm

Opmerking: De meeste up-to-date besturingssystemen hebben de Digicert Roots standaard al vertrouwd en in hun vertrouwenswinkel, wat betekent dat de meeste winkeliers geen actie hoeven te ondernemen om deze vereiste te ondersteunen. Echter, als winkeliers niet de ingebouwde OS trust store gebruiken, en in plaats daarvan hun eigen trust store creëren, dan moeten zij alle Digicert Root certificaten toevoegen aan hun aangepaste trust store, omdat onze certificaten in de toekomst ondertekend kunnen worden door elk van de actieve Digicert root certificaten.

In uw SSL/TLS-beleid moet u deze Certificate Authorities regelmatig (bijvoorbeeld eenmaal per jaar) evalueren en bijwerken.

Het valideren van een keten naar een vertrouwde Certificate Authority betekent dat uw implementatie niet hoeft te worden aangepast wanneer Trust Payments regelmatig servercertificaten bijwerkt. In het bijzonder moet u NIET verifiëren met behulp van een enkele certificaatvingerafdruk, aangezien dit zal moeten worden bijgewerkt telkens als het servercertificaat wordt bijgewerkt en niet zal werken als ons gedistribueerde systeem verschillende individuele certificaten levert.

  De meeste implementaties van SSL/TLS-bibliotheken voldoen aan alle bovenstaande eisen, maar moeten mogelijk worden geconfigureerd om ze in te schakelen. Het is uw verantwoordelijkheid ervoor te zorgen dat al deze beveiligingseisen correct zijn ingeschakeld; anders kan de veiligheid van de verbindingen in gevaar komen. Het is ook uw verantwoordelijkheid ervoor te zorgen dat het besturingssysteem en de software die voor de verbindingen worden gebruikt, up-to-date worden gehouden met beveiligingspatches.

 

Lastenverdeling

Trust Payments maakt gebruik van DNS load balancing. DNS load balancing is ontworpen om één IP terug te sturen, die op dat moment de voorkeursbestemming is voor uw server om verbinding mee te maken.

Voorafgaand aan elk verzoek dat wordt ingediend bij Webservices, moet u een DNS lookup uitvoeren naar het juiste domein in uw toepassing om het IP van een beschikbare gateway te verkrijgen.

De DNS load balancers sturen niet alleen één IP terug, maar ook een lage TTL, momenteel ingesteld op minder dan 60 seconden. Deze TTL is bewust laag gehouden om de blootstelling van uw server aan het gehele betalingssysteem te maximaliseren. Het verhogen van deze TTL zou deze blootstelling verminderen, wat betekent dat u één IP voor een langere periode zult gebruiken. Alle problemen die kunnen optreden (gepland of anderszins) zullen dan gevolgen hebben voor uw betalingsverwerkingsmogelijkheden.

  Het is noodzakelijk dat u zich houdt aan de TTL die is ingesteld door Trust Payments en uw DNS-vermeldingen vernieuwt wanneer de TTL verloopt.

Trust Payments heeft een aantal DNS-servers die worden gebruikt om DNS-records te serveren. Het is belangrijk dat uw server een verbinding kan maken met elk van deze servers voor DNS lookups. Als u een DNS look up mislukking krijgt bij het communiceren met een DNS server, moeten de andere DNS servers worden gebruikt. Als niet alle DNS-servers worden gebruikt, kunnen er problemen ontstaan bij het oplossen van URL's van betalingssystemen.

Vanuit het oogpunt van debug kunt u het volgende commando uitvoeren om de huidige lijst van beschikbare DNS-servers te verkrijgen:

  • Voor de Europese Poort:
    • Windows: nslookup -type=NS securetrading.net
    • Linux: dig NS securetrading.net
  • Voor US Gateway:
    • Windows: nslookup -type=NS securetrading.us
    • Linux: dig NS securetrading.us

 

Time-outs

In het onwaarschijnlijke geval dat uw systeem problemen ondervindt bij de verbinding met ons, is het aanbevolen dat u passende time-outs implementeert voor uw oplossing. Overweeg dit voorbeeld:

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

Opnieuw proberen tot:

  • De maximum retry number wordt overschreden; OF
  • De maximum retry timeout zou worden overschreden door een andere verbindingspoging.

(Dit betekent stoppen met het opnieuw proberen van de verbinding na 35-40 seconden, want een poging die de maximum connect attempt timeout van 5 seconden zou de maximum retry timeout te worden overschreden)

Zodra de verbinding tot stand is gebracht, wacht u 60 seconden (de send and receive timeout waarde) om de gegevens te verzenden en te ontvangen alvorens de verbinding te sluiten. Als om welke reden dan ook de verbinding wordt verbroken nadat de overdracht van gegevens is begonnen, raden wij aan het verzoek niet opnieuw te proberen.

  De hierboven voorgestelde time-outimplementatie is een voorbeeldoplossing. U moet de vereisten van uw eigen toepassing in overweging nemen en time-outs implementeren die het best passen bij uw behoeften.

 

Verwerk verzoeken via onze Webservices API

Uw server moet nu een verzoek genereren met uw eigen bibliotheek. Bijvoorbeeld:

JSON verzoek XML verzoek
{
"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"
}]
}

  Wij aanvaarden alle Unicode-tekens in uw verzoek. De gebruikte codering is UTF-8, een multi-byte coderingsschema. Alle antwoorden van ons zijn gecodeerd met UTF-8. Uw systeem moet voorbereid zijn om alle geldige antwoorden die op deze manier gecodeerd zijn, te aanvaarden.

U moet uw firewall openstellen voor onze Web Services IP's, zoals vermeld op deze webpagina.
Zorg ervoor dat u een proces hebt ingesteld om deze pagina regelmatig te controleren op updates van onze reeks IP's.

Om te voldoen aan strenge beveiligingseisen kunnen we een oorsprong van https://localhost niet accepteren bij gebruik van onze Cross-origin resource sharing (CORS) services.
Je moet een geldig domein gebruiken dat toegankelijk is via Trust Payments.

Uw bibliotheek moet een beveiligde verbinding tot stand brengen:

  • "https://<DOMAIN>/json/" (voor JSON - aanbevolen)
  • "https://<DOMAIN>/xml/" (voor XML)

Vervang <DOMAIN> met een ondersteund Webservices domein. Klik hier voor een volledige lijst.

 

Daarnaast moet u de request string en headers sturen zoals in onderstaand voorbeeld:

JSON verzoek string JSON Request Headers XML Aanvraagstring XML Request Headers
{
"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"
}]
}

  Hoe maak je een kopregel

Alle verzoeken die via onze Webservices API worden ingediend bij Trust Payments moeten beginnen met een reeks headers zoals hieronder gedefinieerd. Wij gebruiken deze om inkomende verzoeken te identificeren en te beheren.

 

Lengte van de inhoud

Content-Length moet de lengte zijn van de verzoekbytes in de gekozen tekenset. Dit moet worden berekend nadat de tekencodering is uitgevoerd.

 

Type inhoud

Content-Type zal altijd worden ingesteld als:

  • "application/json" (voor JSON)
  • "text/xml" (voor XML)

charset moet de karakterset van de post zijn, bijvoorbeeld "utf-8".

Elk verzoek moet correct gecodeerd zijn volgens de tekencodering die in de header is gespecificeerd
Ons systeem accepteert alle Unicode-tekens. De standaardcodering voor JSON is UTF-8 (een multi-byte codering). De meeste JSON parsers zullen dit automatisch verwerken.

 

Autorisatie

“Basic “, gevolgd door een base64 codering van uw Web Services referenties in het formaat gebruikersnaam:wachtwoord (ontdaan van spaties).

Bijvoorbeeld voor gebruikersnaam webservices@example.com en wachtwoord pa55word.

Base64 encodeer webservices@example.com:pa55word om d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=

De uiteindelijke waarde die in dit geval in de header moet worden opgenomen is: Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=

 

Accepteer

Het formaat van de gegevens die worden ingediend bij Trust Payments.

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

 

Behandeling van het antwoord

Uw systeem krijgt talrijke velden terug in het antwoordobject. U zult de inhoud van deze velden moeten interpreteren om er zeker van te zijn dat het de verwachte waarden zijn.

Het volgende is een voorbeeld van een AUTH antwoord:

Ruwe JSON Ruwe XML
{"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"}

Het is vooral belangrijk om de Foutcode en Status betaling waarden in het antwoord te controleren.

Naast de verwerking van authorisaties ondersteunt Trust Payments tal van andere verzoektypes. Meer informatie over deze verzoektypes vindt u op de andere pagina's binnen onze onlinedocumenten.

 

  Overzicht

Op dit punt zou u een basisverzoek moeten kunnen verwerken met onze Webservices API.


Volgende stappen

  • Wij raden aan controles uit te voeren op de velden die in het antwoord worden teruggestuurd.
  • U kunt onze aanvullende documenten raadplegen voor meer informatie over andere functies die als onderdeel van uw implementatie kunnen worden geconfigureerd.
  • Zodra u uw oplossing grondig heeft getest, kunt u verzoeken om live te gaan en beginnen met het verwerken van live betalingen!
Was dit artikel nuttig?
0 van de 0 vonden dit nuttig
Hebt u meer vragen? Dien een verzoek in