All* the invoices that are added using the AddInvoice function are controlled by our anti-fraud system. This is done to make sure the customer is legit and minimize the risk of fraud.
In short, this is how it works:
- An invoice is created using AddInvoice method
- A normal credit check is done on the customer
- If approved, the invoice is received by the anti-fraud system which responds with InvoiceStatus 0 (OnHold) or 6 (Signing)*, depending of the requirements set by Collector based on the agreement.
- After controlling the invoice, the anti-fraud system updates the status to either 1 (Preliminary) or 5 (Rejected) (Rejected only possible if inital status is 0/OnHold)
- A callback is made to a URL located on the merchant's domain
*The Signing status will always be the initial status of B2B part payment invoices (Annuity purchases) since these types of purchases need to be signed by the autorized signatory before the order can be shipped.
What does this mean? If the status is 0 or 6, you should just wait until the invoice status is updated to either 1 or 5. The invoice can’t be activated unless the invoice’s status is 1. If the system responds with status 5, the invoice is rejected and cancelled. In these cases you can’t activate the invoice. Please note that rejected orders should not be shipped!
How long does it take for the anti-fraud system to respond? The majority of all responses are sent within a few seconds, but a callback can take up to 24 working hours in special cases. Keep in mind that when this happens, it normally means something’s wrong and therefore our anti-fraud department need to make a manual control. Often this turns out to be a fraud and even though it takes a few hours, the wait is well worth it.
Where does the system respond to? It responds with the invoice statuses to a callback located in your domain. This callback URL need to be username and password protected and the credentials need to be communicated to Collector. The callback uses basic HTTP authentication with Base64 encoding. Username and password must use characters in the ASCII character set.
What will the callback URL look like? The request from the anti-fraud system to the callback URL will contain the following parameters:
This request is sent with a GET web request and the string is appened to the receiveing URL in the following format:
To answer the question, the callback URL should therefore look like this:
When you have recieved the callback, you will need to have a logic implemented to match the invoice number and order number from the request to the one in your system and then update the invoice status thereafter. If all goes well, you can activate the invoice as soon as the order is ready to be shipped. If the invoice is rejected, you will need to cancel the invoice.
|0||OnHold (screening needed)|
|1||Preliminary (Approved, can be activated)|
|5||Rejected (Denied by Collector, can not be activated)|
|6||Signing (Customer must sign the agreement with Collector)|
Collector applies a retry functionality on the status change notification callbacks. Should the callback fail, Collector will run a series of retries; once every ten minute for ten times.
Collector require a code equivalent to "OK" or a GONE response. The following response codes will be accepted as "OK":
- Codes 200 - 299
- Code 410 (GONE)
You therefore must return any of the above codes when a callback has been recieved sucessfully by your system.
Examples of codes that will initiate retries on the callback:
- 301 (moved)
- 403 (Forbidden)
- 404 (not found)
- 500 (Internal server error)
*In some special cases, this control can be turned off.