Paytia API Exception Handling

The Paytia API services provide status update webhooks to track processes and status changes. These updates include standard API posts as well as exception handling for telephony-related processes. Below are details about specific scenarios and their corresponding webhooks:

Confirming the Payment Amount

1. Customer Confirms Amount is Correct
   • Webhook Sent:

     payment_stage=amount_verify&reference_id=reference_id_is_number_106&amount_verify=accepted
     

2. Customer Rejects Amount
   • Webhook Sent:

     success=0&reference_id=reference_id_is_number_113
     

Call Leg Drops

1. Customer Ends the Call

   • Webhook Sent:

     success=0&reference_id=ref_new34_f1Ta11234521211&callhangup=customer
     

   • Explanation: This indicates the customer has disconnected the call.

2. Agent Ends the Call

   • Webhook Sent:

     success=0&reference_id=ref_new34_f1Ta11234521211121&callhangup=merchant
     

   • Explanation: This indicates the agent has disconnected the call.

Payment Session Resets

1. Customer Presses * to Abort

   • Webhook Sent:

     success=0&reference_id=ref_new34_f1Ta112345212118&custabort=1
     

   • Explanation: The customer reset the payment session and is back in communication with the agent.

2. Agent Presses * to Abort

   • Webhook Sent:

     success=0&reference_id=ref_new34_f1Ta112345212118&agentabort=1
     

   • Explanation: The agent reset the payment session and is back in communication with the customer.

Note

In scenarios where the session resets (via * key) or a call leg drops, the payment request should be considered as failed. A new payment session must be initiated with a fresh uniqueID.

Agent/User Licences and Assigned Payment Types

If an API request includes an agentid that lacks the necessary rights for the specified transaction_flag, Paytia will return an error in the statusDescription field.

Sample API Error Response

{
    "httpStatus": false,
    "reference_id": "reference_id_is_number_144",
    "status": {
        "statusCode": 400,
        "statusDescription": "The agent you are using doesn't have the right to use transaction type 3."
    }
}

• Impact: The agent will not be able to proceed with the payment if rights are not assigned.
• Resolution: User rights can be managed via the Paytia Administration Portal under Administer Users > Users. Click the Edit button to assign the necessary rights.

Managing Licences and Rights

1. Go to Administer Users > Users.
   
2. Select the user from the list and click the Edit button.
3. Update the following settings:
   • Menu Rights: Control which menus the user can access.
   • Licence Rights: Assign payment types and permissions based on active licences.
     
     

For any additional configurations or support, contact your Paytia account administrator.