Paytia IVR webhook flow
The initial post into Paytia will return a URL for the Paytia iframe. If you do not want to use the iframe you can ignore that response post ‘url’ value.
Note: Paytia will maintain the reference_id value throughout the payment flow on each webhook sent.
{
"httpStatus": true,
"reference_id": "{the reference ID you sent}",
"url": "<https://accounts.pay729>.{domain extension}/thirdparty/embededurl/{dynamic GUID Mjk4ODAw/cmVmZXJlbmNlX2lkX2lzX251bWJlcl8yMDM=}",
"status": {
"statusCode": 200,
"statusDescription": "Success"
}
}
Note: In the above example and value with { } delimiters will represent a specific syntax or value based on the response sent and Paytia platform being utilised.
The iframe will load the data you posted
Note: there are more post values that control the payment types, form locking and notification alerts that can be used. Refer to the Paytia API guides for further details.
The following are webhooks that will be returned as the transaction processing continues
When the agent has successfully entered their agent ID
this webhook will be received. The IVR will now allow the customer to proceed with their IVR steps.
payment_stage=agent_id&reference_id=reference_id_is_number_106&agent_id=100
The customer will be asked to confirm the amount being transacted.
Customer presses 1 to confirm the amount was correct
payment_stage=amount_verify&reference_id=reference_id_is_number_106&amount_verify=accepted
Customer presses 2 to say amount was wrong
success=0&reference_id=reference_id_is_number_113
Move to stage = Capture payment card
payment_stage=card_number&reference_id=reference_id_is_number_106
Now the
Customer enters their card number
The Paytia system will send representation X's for the number of digits collected (the total number vary based on card type from 13-19 digits)
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=X
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXXXXXXX
payment_stage=pan_digit&reference_id=reference_id_is_number_106&pan_digit=XXXXXXXXXXXXXXXX
The customer now presses the # key on their telephone keypad to confirm card
Card validation
Paytia now enters card validate mode and performs a LUHN calculation on the full number captured. Then, if that test passes, Paytia performs a BIN match to locate the card type and brand.
Note: Exception - If the card number validation fails Paytia will return a webhook of
return to card_number stage start
payment_stage=card_number&reference_id=reference_id_is_number_106
If all tests pass when the customer presses # key to confirm the card entry has concluded Paytia will follow
Validate mode
LUHN - pass
BIN - pass
BIN validation passed
BIN success will now return card type match values and this webhook will be sent
payment_stage=card_type&reference_id=reference_id_is_number_106&card_type=mastercard
The customer will now be read back the card brand and the last 4 digits of the card number they entered and they will be asked to press 1 to accept it was correct or 2 to re-enter their card again.
An additional webhook for card verify will be sent including the last 4 digits of the card number captured
payment_stage=card_verify&reference_id=reference_id_is_number_106&card_verify=4444
Next we move the customer to the
Card expiry date capture stage
(we now send a webhook of)
payment_stage=card_date&reference_id=reference_id_is_number_106
For each digit collected Paytia will send a webhook representing the Month (M), Month (M), Year (Y), Year (Y) of the card expiry date
payment_stage=expiry_digit&reference_id=reference_id_is_number_106&expiry_digit=M
payment_stage=expiry_digit&reference_id=reference_id_is_number_106&expiry_digit=MM
payment_stage=expiry_digit&reference_id=reference_id_is_number_106&expiry_digit=MM+Y
payment_stage=expiry_digit&reference_id=reference_id_is_number_106&expiry_digit=MM+YY
Note: Exception - If the date is entered incorrectly or fails Paytia validation checks then the stage is reset. Paytia will send a webhook of
payment_stage=card_date&reference_id=reference_id_is_number_106
If the date captured is correct Paytia will move to the CVV capture stage and will issue a webhook of
payment_stage=cv2&reference_id=reference_id_is_number_106
Note: there are variations in card brand for how long a CVV value is
(In the case of card brands other than American Express)
payment_stage=cvv_digit&reference_id=reference_id_is_number_106&cvv_digit=X
payment_stage=cvv_digit&reference_id=reference_id_is_number_106&cvv_digit=XX
payment_stage=cvv_digit&reference_id=reference_id_is_number_106&cvv_digit=XXX
(In the case of American Express)
payment_stage=cvv_digit&reference_id=reference_id_is_number_106&cvv_digit=XXXX
Transaction processing stage
Paytia now passes on the card and transaction details onto the payment processing gateway for processing.
Responses
Failed
success=0&reference_id=reference_id_is_number_106&message={{Error message from paytia/PSP}}
Success
success=1&reference_id=reference_id_is_number_106&message={{Success message from paytia/PSP}}
Note: From 19th March 2024
Paytia has added a new control for merchants looking to capture the card expiry date into their systems.
success=1&reference_id=reference_no26&authcode=8ac7a4a28e539763018e568a38581294&transaction_result=8ac7a4a28e539763018e568a38581294&card_expiry=12-29
(In this example you will see the format for the returned expiry date in the format MM-YY)
Note: this service requires activation in the Paytia administration portal
Exceptions that can occur across the payment flow
Customer says the amount was incorrect in the IVR
success=0&reference_id=reference_id_is_number_107
The customer presses * on their telephone keypad in the IVR to cancel and return to the agent
success=0&reference_id=reference_id_is_number_108&custabort=1
The agent presses * in the IVR to cancel and return to the customer
success=0&reference_id=reference_id_is_number_109&custabort=1
The customer call leg hangs up/disconnects
success=0&reference_id=reference_id_is_number_112&callhangup=agent
The agent call leg hangs up/disconnects
success=0&reference_id=reference_id_is_number_112&callhangup=merchant