Uw eigen bibliotheek 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.

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.

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.

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.

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.

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.

Verwerk verzoeken via onze Webservices API

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

{
  "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>

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:

{
  "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

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".

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:

{"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>

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.