Callback URLs and responses explained
When you register callbacks in the plugin they will also show up in the administration interface like this:
First of all, it is always important that the callbacks url are up to date. When you change credentials for example, they have to re-register so that salt keys and other data is really matching the data on Resurs Bank. This is however not a page about how that is made, but an explanation of the URLs. You may wonder why they look like this.
The callback urls are always using the format that WooCommerce and WordPress are using. From the method getWcApiUrl() in WooCommerce.php we will always get the proper API-call format from WooCommerce itself.
public static function getWcApiUrl()
{
return sprintf('%s', WC()->api_request_url('ResursDefault'));
}
By doing this, we never have to worry about if WooCommerce will be able to handle the inbound requests from a callback handler. The above image is very much based on "pretty urls". That said, in our case we are using apache and mod_rewrite. The URLs could therefore look differently on your site. The parameters are described below.
AUTOMATIC_FRAUD_CONTROL and TEST
Since we no longer use AUTOMATIC_FRAUD_CONTROL, there's more variables that is no longer in effect and not mentioned in the table. The callback TEST is only used internally so this can be ignored by you.
| Parameter | Description |
|---|---|
| c | Abbreviation for callback type. When Resurs Bank is sending a callback the specific callback type is mostly hard coded like this and can not be set with for example {CALLBACK}, because they do not support that variable dynamically. |
| t | An internal timestamp, based on time(). This is the plugin's own variable and wo'nt affect anything, but the time (your) when the registration was made. Be aware of this, since it much uses server time, so if you run a server in Los Angeles that is not properly configured the timestamp will probably be UTC+9. |
| p | Even if the payment id is most likely known to us during the payment, this variable is set by Resurs Bank, so it is dynamically set. Therefore, we use {paymentId}. |
| d | The same thing goes for d, as in digest. The digest is set by the salt key set when the callbacks was registered. The digest is rendered like something like this: sha1/md5($callbackPaymentId . ($callbackResult !== null ? $callbackResult : null) . $saltKey) sha1 is used by default. |
Callback responses
When a callback is sent from Resurs Bank, the plugin may answer differently depending on what happened during the callback. For the moment we return several response codes, described below. We are also returning a json-formatted response body in case someone wants to test callbacks manually. It looks like this:
{
"aliveConfirm": true,
"actual": "UPDATE",
"digestCode": 406,
"errors": {
"code": 0,
"message": ""
}
}
JSON explained
This body is not only visible in a production environment. However, as we know it the http response code is always visible in logs somewhere so for that part there's no problems. However, sometimes merchants or developers needs to extend their error checking som instead of push up breakpoints and such, in an environment, the json body response is an extra errorchecking layer. This is what you get from it (see the example above).
| Key | Description |
|---|---|
| aliveConfirm | Always true, when nothing has yet gone wrong. Set to false on exceptions. |
| actual | Which callback that has been send from Resurs (or you manually) to be handled. |
| digestCode | The result of Resurs or your action (see codes below). |
| errors | An extension that tells the sending part if something went wrong during the callback. This can be mocked from the "mockAdmin". {
"code": 0,
"message": ""
}
This is the default view of the error part. If there are no errors, the code will always be 0 and the message empty (unless there are special conditions that occurs on Resurs Bank which sometimes not returning a proper error code). |
Responses explained
First of all: Avoid using 200 as a response code. Since this is very much a system default, neither the plugin nor the support will be sure if a callback has been delivered if your system responds with 200 all the time. 200 can for example indicate reachability but not for the plugin. On specific case found on the field was that the platform itself actually had 403 error when a callback was sent, but the redirect created a 200 which made us believe that there was no errors. However, if a server blocks access with a 403, but repsonds with 200, the problem lies within the platform - not the plugin.
| Code | Response string | Description | Plugin constant |
|---|---|---|---|
| 202 | Order is not ours, but it is still accepted. | When option accept_rejected_callbacks is enabled in config and the plugin receives an order that is not explicitly created in the current platform. This status means that plugin has been rejected to handle the order, but responds as the callback was OK. | HTTP_RESPONSE_NOT_OURS_BUT_ACCEPTED |
| 204 | OK | Callback received handled and updated without errors. | HTTP_RESPONSE_OK |
| 204 | Test OK | When callbacks are tested and accepted by system. | HTTP_RESPONSE_TEST_OK |
| 406 | Digest rejected. | The salt key has been changed in the system and is no longer matching with Resurs Bank. The way the plugin are calculating the digest key will fail and return this error. | HTTP_RESPONSE_DIGEST_IS_WRONG |
| 410 | Order is not ours. | When option accept_rejected_callbacks is disabled in config and the plugin receives an order that is not explicitly created in the current platform. This status means the plugin is unconditionally rejecting the callback. | HTTP_RESPONSE_GONE_NOT_OURS |
| Unhandled | Errorstring generated automaticallly | This is an automatically generated and forwarded code and errormessage. It is only shown during exceptions that is catched by the system on unknown errors. | - |
Responses caused by someone else
Some errors may be unpredictable, so if you get any other message or response in the callback, you may want to look up that specific error. This is an example:
{
"aliveConfirm": false,
"actual": "UPDATE",
"errors": {
"code": 616,
"message": "You are not of type Skrull nor Kree."
},
"digestCode": 616
}
The error itself can also be seen in the HTTP response header in the (for Chrome) network section of the request:
