​
Why Instant Payment Notifications

All payment-related transactions (and some non-payment-related) requests on Xente are processed asynchronously. This is because most transactions require user approval and may take time to complete. Below is how we process transactions:

  1. You POST a transaction to Xente.

  2. We queue it up.

  3. We process the transaction - this might involve user approval.

  4. We call back your webhook to notify you of the status of the payment.

  5. You respond with an HTTP OK that you have received the notification and we commit the payment as complete.

As a result, it is necessary to set up an Instant Payment Notification (IPN) webhook on your end in order to receive updates on the final status of a transaction

​
Handling Instant Payment Notification (IPN)

When it comes to handling Instant Payment Notification (IPN), there are a few key steps for you to follow:

  1. Set up an IPN URL: Create an endpoint on your server to receive IPN messages. This URL should be capable of handling incoming POST requests.

  2. JSON parsing: Ensure that your IPN URL can parse JSON data. This means extracting relevant information from the incoming request payload.

  3. Response status: If the JSON parsing is successful, make sure your IPN URL responds with a 200 OK status code. This lets the sender know that the notification was received and processed correctly.

  4. Transaction completion: Remember that a transaction is only marked as complete when your system receives a successful response from the IPN URL.

Below is some sample code to help you set up your Instant Payment Notification


curl -X POST 'your-url' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_number": "string",
    "subscription_id": "string",
    "transaction_id": "string",
    "batch_id": "string",
    "client_referenceId": "string",
    "status_message": "string",
    "status_code": 0,
    "correlation_id": "string",
    "created_on": "YYYY-MM-DD HH:mm:ss",
    "amount": 0.0,
    "currency": "string"
}'

​
Response message

KeyTypeDescription
TokenstringAuthentication token that you will use to authenticate subsquent API calls
refreshTokenstringThe refresh token is used to refresh session without requiring new user login
successbooleanStatus of authentication request
messagestringA description of status

​
Secure your Instant Payment Notifications (IPN) endpoint

Your Instant Payment Notifications (IPN) endpoint will receive transaction confirmations from Xente, so it’s important to ensure that it is secure. To secure the IPN, we will:

  1. Use symmetric encryption: This means we will exchange keys. We will have your public key and you will have our public key. We must authenticate the keys before completing the transaction. This functionality is crucial and you cannot go live without testing it.

  2. IP whitelisting: As an added layer of security, whitelist the following IPs: 41.2.2.10 and 41.2.2.11

Authentication & AuthorizationCards overview