TRANSACTIONUPDATE - Trust Payments

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.

Nadat u verzoeken en transacties met ons hebt verwerkt, kunt u sommige gegevens op een later tijdstip bijwerken door een verzoek in te dienen op TRANSACTIONUPDATE.

Procesoverzicht

Hier volgen enkele voorbeelden van de updates die met deze functie kunnen worden uitgevoerd:

het verlagen van het bedrag voor een AUTH na autorisatie en voor afwikkeling.
het opschorten van een REFUND, het voorkomen van afwikkeling.
het wijzigen van de frequentie waarmee betalingen door een SUBSCRIPTION worden verwerkt.

Vereisten

U kunt alleen updates uitvoeren op verzoeken van de volgende typen:

Autorisatie (AUTH)
Terugbetaling (REFUND)
Abonnement (SUBSCRIPTION)

U kunt alleen AUTH en REFUND bijwerken als ze zich in een lopende Status betaling ('0', '1' of '2') bevinden en NIET als ze zich in een geannuleerde ('3') of afgehandelde ('100') status bevinden. Meer informatie over de Status betaling .

Stap-voor-stap voorbeeld

U hebt eerder een succesvolle AUTH verwerkt (met transactionreference "1-2-3") op uw site (met sitereference "test_site12345"). Het heeft een settlestatus van "1", wat betekent dat het binnen 24 uur automatisch wordt verrekend. U wilt de settlestatus op "2", waardoor de Afwikkeling van fondsen naar uw bankrekening.

Stap 1: Uw systeem dient een TRANSACTIONUPDATE verzoek in bij Trust Payments, inclusief:

sitereference "test_site12345" (ter identificatie van de site waarop de transactie werd verwerkt).
transactionreference "1-2-3" (om de bij te werken transactie te identificeren).
de updates die moeten worden uitgevoerd; in dit voorbeeld, settlestatus "2" (schorst de betaling).

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
  },
  "updates":{"settlestatus":"2"}
}

strequest = securetrading.Request()
strequest.update(update)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
  'filter' => array(
    'sitereference' => array(array('value' => 'test_site12345')),
    'transactionreference' => array(array('value' => '1-2-3'))
  ),
  'updates' => array('settlestatus' => '2')
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescriptions": ["TRANSACTIONUPDATE"],
    "filter":{
      "sitereference": [{"value":"test_site12345"}],
      "transactionreference": [{"value":"1-2-3"}]
    },
    "updates":{"settlestatus":"2"}
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONUPDATE"],
    "filter":{
      "sitereference":[{"value":"test_site12345"}],
      "transactionreference":[{"value":"1-2-3"}]
    },
    "updates":{"settlestatus":"2"}
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>1-2-3</transactionreference>
    </filter>
    <updates>
      <settlement>
        <settlestatus>2</settlestatus>
      </settlement>
    </updates>
  </request>
</requestblock>

Vervang <DOMAIN> met een ondersteund domein. Volledige lijst met domeinen weergeven.

Bij het uitvoeren van een enkel TRANSACTIONUPDATE verzoek:

U kunt slechts één transactie bijwerken. (Voor het bijwerken van meerdere transacties is één TRANSACTIONUPDATE verzoek per transactie nodig)
U kunt meerdere velden in een enkele transactie bijwerken met een enkel TRANSACTIONUPDATE verzoek.

Trust Payments ontvangt en interpreteert het TRANSACTIONUPDATE verzoek en voert de updates uit op de gespecificeerde transactie, mits het ingediende verzoek geldig was (anders wordt een fout geretourneerd).

Stap 2: Uw systeem ontvangt en interpreteert een TRANSACTIONUPDATE antwoord en werkt uw administratie bij, indien nodig. Uw systeem moet ervoor zorgen dat de errorcode waarde "0" is, wat wijst op een geslaagde bijwerking.

De AUTH "1-2-3" op sitereference "test_site12345" heeft nu toegewezen gekregen settlestatus "2", waardoor de betaling wordt opgeschort.

TRANSACTIONUPDATE verzoek

Het verzoek op TRANSACTIONUPDATE bestaat uit twee delen:

De filters worden gebruikt om de bij te werken transactie te specificeren.
De updates worden gebruikt om aan te geven welke updates van de transactie moeten worden uitgevoerd.

Hieronder volgt een voorbeeld van een TRANSACTIONUPDATE verzoek:

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
  },
  "updates":{"settlestatus":"2"}
}

strequest = securetrading.Request()
strequest.update(update)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
  'filter' => array(
    'sitereference' => array(array('value' => 'test_site12345')),
    'transactionreference' => array(array('value' => '1-2-3'))
  ),
  'updates' => array('settlestatus' => '2')
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescriptions": ["TRANSACTIONUPDATE"],
    "filter":{
      "sitereference": [{"value":"test_site12345"}],
      "transactionreference": [{"value":"1-2-3"}]
    },
    "updates":{"settlestatus":"2"}
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONUPDATE"],
    "filter":{
      "sitereference":[{"value":"test_site12345"}],
      "transactionreference":[{"value":"1-2-3"}]
    },
    "updates":{"settlestatus":"2"}
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>1-2-3</transactionreference>
    </filter>
    <updates>
      <settlement>
        <settlestatus>2</settlestatus>
      </settlement>
    </updates>
  </request>
</requestblock>

Vervang <DOMAIN> met een ondersteund domein. Volledige lijst met domeinen weergeven.

Filters

	Veld	Formaat	Beschrijving
Verplicht	sitereference XPath: /filter/sitereference	Alfanumeriek inclusief underscore (50)	De unieke referentie voor de Trust Payments site die verband houdt met de transactie die u wilt bijwerken.
Verplicht	transactionreference XPath: /filter/transactionreference	Alfanumeriek, inclusief koppeltekens (25)	De unieke Trust Payments referentie voor de transactie die u wilt bijwerken.

Updates

De volgende velden kunnen worden bijgewerkt wanneer updates worden uitgevoerd op AUTH en REFUND verzoeken.

	Veld	Formaat	Beschrijving
Optioneel	orderreference XPath: /updates/merchant/orderreference	Alfanumeriek met inbegrip van symbolen (25) Aanbevolen lengte 25 tekens of minder (exacte lengte afhankelijk van de wervende bank). Niet-naleving van deze eis kan ertoe leiden dat de tekst in de transactie wordt ingekort.	Update de unieke orderreferentie die kan worden opgeslagen op het Trust Payments systeem.
Optioneel	settlebaseamount XPath: /updates/settlement/settlebaseamount	Numeriek (13)	Het bedrag van de transactie in basiseenheden, zonder komma's of decimalen, dus €10,50 zou 1050 zijn. Deze waarde moet hoger zijn dan nul en lager dan of gelijk aan het oorspronkelijke autorisatiebedrag.
Optioneel	settleduedate XPath: /updates/settlement/settleduedate	Datum JJJJ-MM-DD	Datum waarop de transactie zal worden afgewikkeld. Indien vandaag of eerder, wordt de transactie afgewikkeld wanneer afwikkeling de volgende keer wordt uitgevoerd (mits niet opgeschort of geannuleerd).
Optioneel	settlestatus XPath: /updates/settlement/settlestatus	Numeriek (3)	Deze waarde heeft betrekking op de status van de transactie.

Voor het bijwerken van verschillende soorten verzoeken zijn verschillende velden nodig. Raadpleeg de volgende bronnen voor meer informatie:

Informatie over het bijwerken van abonnementen

Over Status betaling

Een opgeschorte (status 2) transactie wordt automatisch teruggedraaid of geannuleerd (status 3) na 7 dagen vanaf autorisatie, omdat de code autorisatie dan verlopen is. (autorisatie codes zijn 7 dagen geldig).
Zodra een transactie is ingesteld op teruggedraaid/geannuleerd (status 3), zal de transactie niet worden afgewikkeld en kan de status niet worden gewijzigd.

Meer informatie over de Status betaling.

TRANSACTIONUPDATE antwoord

Hieronder staat een voorbeeld van een TRANSACTIONUPDATE antwoord dat is teruggestuurd na een geslaagde transactie-update.

{
'requestreference': 'A3jbd6w7a',
'version': '1.00',
'responses': [{
'errorcode': '0',
'requesttypedescription': 'TRANSACTIONUPDATE',
'transactionstartedtimestamp': '2019-12-17 10:58:20',
'errormessage': 'Ok',
'operatorname': 'webservices@example.com'
}]
}

array(3) {
  ["requestreference"] => string(9) "A057aegmt"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(5) {
      ["errorcode"] => string(1) "0"
      ["requesttypedescription"] => string(17) "TRANSACTIONUPDATE"
      ["transactionstartedtimestamp"] => string(19) "2019-12-17 10:58:20"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "webservices@example.com"
    }
  }
}

{
  "requestreference":"W23-tkrxwkc6",
  "version":"1.00",
  "response":[{
    "errorcode":"0",
    "requesttypedescription":"TRANSACTIONUPDATE",
    "transactionstartedtimestamp":"2019-12-17 10:58:20",
    "errormessage":"Ok",
    "operatorname":"webservices@example.com"
  }],
  "secrand":"SptlJutnBnQ"
}

<responseblock version="3.67">
  <requestreference>Xj73e17g4</requestreference>
  <response type="TRANSACTIONUPDATE">
    <timestamp>2019-12-17 10:58:20</timestamp>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
  </response>
  <secrand>qfZtw074MBlmIq</secrand>
</responseblock>

Zorg ervoor dat de errorcode is "0". Dit geeft aan dat het TRANSACTIONUPDATE verzoek met succes is verwerkt. Indien de errorcode niet "0" is, is het verzoek misschien niet verwerkt zoals verwacht.

Problemen oplossen

Als u een TRANSACTIONUPDATE verzoek indient onmiddellijk na de transactie die u probeert bij te werken, kunt u een "20004 Bovengeschikte transactie ontbreekt" foutmelding krijgen. Wacht in dat geval enkele seconden en probeer het opnieuw.

Aanvullende middelen