Introduction and list of postbacks

Postbacks also called callbacks or webhooks. They are a way for Vendo's platform to post information to your system. You just need to configure your postback endpoint in Vendo's back office.

It's essential that your postback endpoint script is continuously available and handling exceptions properly as it is the way your system is kept up-to-date with user, subscription and payment transactions details.

❗️

Important note for Vendo Payment Gateway API users.

If you are using Vendo's Payment Gateway API then you do not need to process postbacks. Do not configure any postback URL.

👍

Tip

Your Vendo Client Services representative can assist you with preparing and testing your postback endpoint.

📘

NATS v4 and NATS v5

You must use the VSERVICES biller with NATS. It implements all available Vendo postbacks.

🚧

Vendo will only send postbacks from a limited list of IP addresses

You can secure your postback endpoint from unauthorized access by whitelisting our IP address.

How postbacks are structured

Before you begin

  • Postbacks are HTTP POST requests to your postback endpoint.
  • The request parameters are sent as application/x-www-form-urlencoded key-value pairs in the body of the request.
  • Responses must be sent back in XML format.

The following parameters are common for all postback types:

ParameterData typeDescription
callbackstringThe name of the postback type, f.ex. "checkUser" or "transaction"
is_testbooleanWhether or not this request is related to a test transaction or subscription.
0 for no (real transaction)
1 for yes (test transaction)

Responses

Your server must respond to the postback request with an HTTP/1.1 compliant response with the status 200 OK.

The body of the response must be valid UTF-8 encoded XML with a root element and a child element inside, named after the type of the postback, f.ex.:

<?xml version="1.0" encoding="UTF-8"?>
<postbackResponse>  
 <checkUser>       
  <code>1</code> 
 </checkUser>
</postbackResponse>
<?xml version="1.0" encoding="UTF-8"?>
<postbackResponse> 
 <checkUser>  
  <code>2</code>  
  <errorMessage>Custom error message</errorMessage> 
 </checkUser>
</postbackResponse>

The response codes have the following general meaning:

Response codeMeaningExplanation
1OKThe postback was correctly received and processed.
2ERRORAn error occurred while trying to receive and process the postback request.

Please provide a meaningful error message in the element <errorMessage> right after the <code> element.
Others?Depends on the postback type, see corresponding documentation.

What’s Next

Continue here to see how to implement your first postback processor: