Webhooks sent from Paytia to API users for the payment capture IVR flow

Webhooks sent from Paytia to API users for the payment capture IVR flow

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

Also see artical

    • Related Articles

    • Paytia API exception handling

      The Paytia API services generate status update webhook posts to allow the process and status updates to be tracked. Outside of the standard API posts there is also exception handling required for telephony. Paytia will send update webhooks for status ...
    • How do I use Paytia Webhooks?

      Configure webhooks in the Paytia merchant administrative portal Webhooks are used to notify and send information out from the Paytia platform to third party service providers. At present the webhook service allows telephony partners that wish to add ...
    • Webhook request button

      What does the Webhook request button show me? Webhook request button The Webhook Request button will show you all the webhooks associated with the call that has been made/received. The webhooks are shown in the order that the Paytia platform has sent ...
    • Third-party webhook logs

      What does the third-party webhook log show me? The Third-party webhook log shows all the data reviewed from a third-party system into the Paytia platform filtered by the X-PAYTIA-API key the data was sent with. The X-PAYTIA-API is unique to each ...
    • Adding custom fields to capture more payment information

      How do I add fields to send additional custom values to Paytia and a payment gateway? Note: Custom fields is an additional licence. If you require this please contact sales@paytia.com Paytia has now introduced Custom fields as an additional licence ...