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.
Om een abonnement bij te werken of te annuleren, kunt u een TRANSACTIONUPDATE verzoek indienen, waarbij u de transactionreference van de SUBSCRIPTION.
De subscriptionbegindate en subscriptionnumber velden kunnen nooit worden bijgewerkt.
Voorbeelden aanvragen
De structuur van het verzoek voor het bijwerken van abonnementen is dezelfde als die van een standaard TRANSACTIONUPDATE verzoek, met toevoeging van abonnementspecifieke velden. Zie de onderstaande voorbeelden voor meer informatie.
Abonnement bijwerken
Het volgende voorbeeldverzoek zou de baseamount van het abonnement op 100 (£1.00), de betalingsfrequentie op eenmaal per 7 dagen, en de subscriptionfinalnumber 24 zijn (waardoor het totale aantal verwerkte abonnementen verandert).
#!/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-345679"}]
},
"updates":{
"baseamount":"100",
"subscriptionfrequency":"7",
"subscriptionunit":"DAY",
"subscriptionfinalnumber":"24"
}
}
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-345679'))
),
'updates' => array(
'baseamount' => '100',
'subscriptionfrequency' => '7',
'subscriptionunit' => 'DAY',
'subscriptionfinalnumber' => '24'
)
);
$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-345679"}]
},
"updates":{
"baseamount":"100",
"subscriptionfrequency":"7",
"subscriptionunit":"DAY",
"subscriptionfinalnumber":"24"
}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{
"baseamount":"100",
"subscriptionfrequency":"7",
"subscriptionunit":"DAY",
"subscriptionfinalnumber":"24"
}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>17-9-2</transactionreference>
</filter>
<updates>
<billing>
<amount>2000</amount>
<subscription>
<finalnumber>12</finalnumber>
<frequency>1</frequency>
<unit>MONTH</unit>
</subscription>
</billing>
</updates>
</request>
</requestblock>
Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Let op: Het is mogelijk om de subscriptionfinalnumber veld, om een abonnement te verlengen. Indien dit echter wordt gedaan nadat een abonnement is voltooid, worden alle betalingen die zouden zijn gedaan indien het abonnement had mogen worden voortgezet, onmiddellijk verwerkt.
b.v. Als een abonnement van £10/maand is voltooid, en vijf maanden na voltooiing, de subscriptionfinalnumber wordt verhoogd met vijf, zullen vijf £10 betalingen worden verwerkt in de volgende afwikkeling run (gewoonlijk binnen de volgende 24 uur).
Om een abonnement met dezelfde facturatiegegevens te verlengen, zonder de betalingen "in te halen", moet u het bestaande abonnement stopzetten en een nieuwe aanvraag indienen, met inbegrip van de transactionreference van de bovengeschikte verzoek (om dezelfde facturatiegegevens te gebruiken). Dien het volgende verzoek in:
Een nieuwe AUTH SUBSCRIPTION verzoek op de dag van de maand dat u wilt dat de automatische betalingen voortaan worden verwerkt.
Abonnement tijdelijk uitschakelen
Om een actief abonnement tijdelijk uit te schakelen, kan de transactionactive veld in het TRANSACTIONUPDATE verzoek moet worden ingesteld op "0", zoals in het volgende voorbeeld:
Inactieve abonnementen kunnen op een later tijdstip weer worden ingeschakeld.
Zie de paragraaf Abonnement inschakelen hieronder voor een voorbeeld.
#!/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-345679"}]
},
"updates":{"transactionactive":"0"}
}
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-345679'))
),
'updates' => array('transactionactive' => '0')
);
$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-345679"}]
},
"updates":{"transactionactive":"0"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"0"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>12-64-1</transactionreference>
</filter>
<updates>
<billing>
<payment>
<active>0</active>
</payment>
</billing>
</updates>
</request>
</requestblock>
Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Abonnement inschakelen
Om een lopend of inactief abonnement te activeren, moet de transactionactive veld in het TRANSACTIONUPDATE verzoek moet worden ingesteld op "1".
Een lopend abonnement bijwerken (transactionactive van "2") actief is, zullen de resultaten van alle fraude of dubbel controles op het initiële AUTH 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-345679"}]
},
"updates":{"transactionactive":"1"}
}
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-345679'))
),
'updates' => array('transactionactive' => '1')
);
$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-345679"}]
},
"updates":{"transactionactive":"1"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"1"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>12-64-1</transactionreference>
</filter>
<updates>
<billing>
<payment>
<active>1</active>
</payment>
</billing>
</updates>
</request>
</requestblock>
Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Let op: Bij het activeren van een reeds bestaand abonnement worden alle betalingen die zouden zijn gedaan gedurende de periode dat het abonnement in behandeling of inactief was, onmiddellijk verwerkt.
Als bijvoorbeeld een abonnement van €10/maand vier maanden inactief of in afwachting is en vervolgens wordt geactiveerd, worden vier betalingen van €10 verwerkt in de volgende vereffeningsrun (gewoonlijk binnen de volgende 24 uur).
Om een abonnement met dezelfde factureringsgegevens voort te zetten, zonder de betalingen "in te halen", moet u het bestaande abonnement stopzetten en een nieuw verzoek indienen, met inbegrip van de transactionreference van de bovengeschikte verzoek (om dezelfde facturatiegegevens te gebruiken). Dien het volgende verzoek in:
Een nieuwe AUTH SUBSCRIPTION verzoek op de dag van de maand dat u wilt dat de automatische betalingen voortaan worden verwerkt.
Een abonnement zal nooit betalingen verwerken als de subscriptionnumber is groter dan de subscriptionfinalnumber. Om in een dergelijk geval een abonnement in te schakelen, moet u ook een hogere subscriptionfinalnumber in het verzoek TRANSACTIONUPDATE .
Abonnement definitief stopzetten
Om een abonnement definitief stop te zetten, moet de transactionactive veld in het TRANSACTIONUPDATE verzoek moet worden ingesteld op "3", zoals in het volgende voorbeeld:
Gestopte abonnementen worden permanent geannuleerd en kunnen later niet opnieuw worden ingeschakeld.
Als u het abonnement toch wilt voortzetten, moet u een geheel nieuwe AUTH SUBSCRIPTION 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-345679"}]
},
"updates":{"transactionactive":"3"}
}
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-345679'))
),
'updates' => array('transactionactive' => '3')
);
$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-345679"}]
},
"updates":{"transactionactive":"3"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"3"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>12-64-1</transactionreference>
</filter>
<updates>
<billing>
<payment>
<active>3</active>
</payment>
</billing>
</updates>
</request>
</requestblock>
Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Vervaldatum bijwerken
U moet ervoor zorgen dat de vervaldata op uw actieve abonnementen geldig en up-to-date zijn, omdat sommige uitgevers kaarten met verouderde vervaldata kunnen weigeren. U kunt de vervaldatum op de kaart van een klant bijwerken voor hun geplande abonnementsbetalingen door een TRANSACTIONUPDATE verzoek in te dienen met het veld expirydate, die de nieuwe waarde bevat.
#!/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-345679"}]
},
"updates":{"expirydate":"05/2025"}
}
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-345679'))
),
'updates' => array('expirydate' => '05/2025')
);
$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-345679"}]
},
"updates":{"expirydate":"05/2025"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"expirydate":"05/2025"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>12-64-1</transactionreference>
</filter>
<updates>
<billing>
<payment>
<expirydate>05/2025</expirydate>
</payment>
</billing>
</updates>
</request>
</requestblock>
Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Specificatie veld
De volgende velden hebben betrekking op het soort verzoek dat wordt ingediend:
| Veld | Formaat | Beschrijving | |
| requesttypedescriptions XPath: /@type |
Alpha (20) | U moet "TRANSACTIONUPDATE" indienen, zoals in het verzoekvoorbeeld. | |
| sitereference XPath: /filter/sitereference |
Alfanumeriek & underscore (50) |
De site referentie waarlangs het abonnement wordt verwerkt. | |
| expirydate XPath: /billing/payment/expirydate |
Datum MM/JJJJ | Een nieuwe expirydate om de waarde bij te werken die we zullen gebruiken bij het verwerken van toekomstige geplande abonnementsbetalingen. | |
| subscriptionfinalnumber XPath: /updates/billing/subscription/finalnumber |
Numeriek (5) |
subscriptionfinalnumber staat voor de positie van de laatste betaling in een reeks abonnementsbetalingen. Zodra dit aantal is bereikt, worden geen betalingen meer verwerkt. Als u dit veld bijwerkt, verandert het totaal aantal verwerkte abonnementsbetalingen.
Voorbeeld van updates die wij ondersteunen:
|
|
| subscriptionfrequency XPath: /updates/billing/subscription/frequency |
Numeriek (11) |
subscriptionfrequency is het aantal eenheden dat moet voorkomen voordat de volgende autorisatie wordt verwerkt. Het wordt gebruikt in combinatie met de subscriptionunit veld om het interval tussen de betalingen te bepalen.
Bijvoorbeeld het bijwerken van subscriptionfrequency van 2 tot 5, wanneer subscriptionunit is ingesteld op "DAY", verandert de verwerking van abonnementen van elke 2 dagen naar elke 5 dagen. |
|
| subscriptionunit XPath: /updates/billing/subscription/unit |
Alfa (5) |
subscriptionunit staat voor de tijdseenheid die wordt gebruikt om betalingen te plannen ("DAY" of "MONTH"). Het wordt gebruikt in combinatie met de subscriptionfrequency veld om het interval tussen de betalingen te bepalen.
Bijvoorbeeld het bijwerken van subscriptionunit van "DAY" naar "MONTH", wanneer subscriptionfrequency 2 is, verandert de verwerking van abonnementen van elke 2 dagen naar elke 2 maanden. |
|
| transactionactive XPath: /updates/billing/payment/active |
Numeriek (1) |
U kunt de abonnementsstatus bijwerken tot een van de volgende twee waarden:
"0" - Inactief: Schort geplande betalingen op totdat ze handmatig opnieuw worden ingeschakeld. "1" - Actief: Laat geplande betalingen doorgaan. "3" - Gestopt: Stopt permanent de geplande betalingen. |
|
| transactionreference XPath: /filter/transactionreference |
Alfanumeriek, inclusief koppeltekens (25) |
De Transactiereferentie waarde geassocieerd met het SUBSCRIPTION verzoek. |
Voorbeeld van een antwoord
Nadat u met succes een TRANSACTIONUPDATE verzoek hebt ingediend, krijgt u een antwoord terug. Het antwoord heeft een soortgelijke structuur als een standaard TRANSACTIONUPDATE antwoord, met toevoeging van extra abonnementsvelden.
{
u 'requestreference': u 'A3jbd6w7a',
u 'version': u '1.00',
u 'response': [{
u 'errorcode': u '0',
u 'requesttypedescription': u 'TRANSACTIONUPDATE',
u 'transactionstartedtimestamp': u '2017-09-28 09:32:42',
u 'errormessage': u 'Ok'
}]
}
array(3) {
["requestreference"] => string(9) "A057aegmt"
["version"] => string(4) "1.00"
["response"] => array(1) {
[0] => array(4) {
["errorcode"] => string(1) "0"
["requesttypedescription"] => string(17) "TRANSACTIONUPDATE"
["transactionstartedtimestamp"] => string(19) "2017-09-28 09:32:42"
["errormessage"] => string(2) "Ok"
}
}
}
{
"requestreference":"W23-tkrxwkc6",
"version":"1.00",
"response":[{
"errorcode":"0",
"requesttypedescription":"TRANSACTIONUPDATE",
"transactionstartedtimestamp":"2017-09-28 09:32:42",
"errormessage":"Ok"
}],
"secrand":"SptlJutnBnQ"
}
<responseblock version="3.67">
<requestreference>X675136983</requestreference>
<response type="TRANSACTIONUPDATE">
<timestamp>2010-03-11 16:38:47</timestamp>
<error>
<message>Ok</message>
<code>0</code>
</error>
</response>
<secrand>9PyI</secrand>
</responseblock>
Specificatie veld
De volgende velden hebben betrekking op het soort verzoek dat wordt ingediend:
| Veld | Formaat | Beschrijving | |
| errorcode XPath: /error/code |
Numeriek (1-5) |
Via Foutcode moet worden bepaald of de update geslaagd is of niet.
Klik hier voor een volledige lijst van errorcode en berichtwaarden. |
|
| errormessage XPath: /error/message |
Alfanumeriek (255) |
Dit is het bericht dat overeenkomt met de bovenstaande code. Klik hier voor een volledige lijst van errorcode en berichtwaarden. |
|
| requesttypedescription XPath: /@type |
Alpha (20) | "TRANSACTIONUPDATE" wordt teruggestuurd in het antwoord. | |
| transactionstartedtimestamp XPath: /timestamp |
Datum tijd JJJJ-MM-DD hh:mm:ss | Het tijdstip waarop het verzoek is verwerkt. |
Update maandelijkse abonnementsdatum
Om de datum waarop een maandabonnement betalingen verwerkt (bijv. van de 1e van elke maand naar de 15e) te wijzigen, moet u het bestaande abonnement stopzetten en handmatig een nieuw AUTH verzoek indienen (via onze Webservices API) op de dag van de maand dat u wilt dat de automatische betalingen voortaan worden verwerkt. U moet de transactionreference van de bovengeschikte verzoek om factuurgegevens te erven.
