VoucherRedirectDeposit (Callpay)
The VoucherRedirectDeposit method supports EasyPay Voucher, Blu Voucher and OTT Voucher payments through provider Callpay in South Africa.
The following method IDs are covered in this section:
ID | Name | Credit/Debit State |
---|---|---|
299 | VoucherRedirectDeposit | DepositedByProvider (29) |
Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).
Flow
Redirect Integration
Currently not supported.
Backend2BackendIntegration
The following parameters can be provided in initiatePaymentRequest.specificPaymentData:
key (value type, account type, required) | value |
---|---|
SuccessPageUrl (string, required) | URL to redirect for successful payments |
CancelPageUrl (string, required) | URL to redirect if payment is cancelled |
ErrorPageUrl (string, required) | URL to redirect in case of error |
ProductCode (string, required) | Voucher method |
Product Code
Supported value for the product code are:
- bluvoucher
- kazangvoucher
- ott_voucher
Example initiatePaymentRequest:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>{{merchant}}</merchantID>
<shopID>{{shop}}</shopID>
<merchantTransactionID>OB-20230301-1107</merchantTransactionID>
<paymentMethodID>299</paymentMethodID>
<amount currencyCode="ZAR">11.01</amount>
<userID>OB-20230301-1107</userID>
<userData>
<username>testuser</username>
<firstname>Test</firstname>
<lastname>User</lastname>
<currencyCode>ZAR</currencyCode>
<email>[email protected]</email>
<address>
<street>123 home street</street>
<postalCode>123456</postalCode>
<city>Test city</city>
<state>Test state</state>
<countryCode2>ZA</countryCode2>
<telephoneNumber>0016479325666</telephoneNumber>
</address>
<gender>Male</gender>
</userData>
<userIP>127.0.0.22</userIP>
<userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://success.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancel.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ErrorPageUrl</key>
<value>https://error.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ProductCode</key>
<value>bluvoucher</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayProviderShop</shopID>
<merchantTransactionID>OB-20230301-1109</merchantTransactionID>
<paymentMethodID>299</paymentMethodID>
<amount currencyCode="ZAR">11.01</amount>
<userID>OB-20230301-1109</userID>
<userData>
<username>testuser</username>
<firstname>Test</firstname>
<lastname>User</lastname>
<currencyCode>ZAR</currencyCode>
<email>[email protected]</email>
<address>
<street>123 home street</street>
<postalCode>123456</postalCode>
<city>Test city</city>
<state>Test state</state>
<countryCode2>ZA</countryCode2>
<telephoneNumber>0016479325666</telephoneNumber>
</address>
<gender>Male</gender>
</userData>
<userIP>127.0.0.22</userIP>
<userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://success.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancel.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ErrorPageUrl</key>
<value>https://error.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ProductCode</key>
<value>kazangvoucher</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayProviderShop</shopID>
<merchantTransactionID>OB-20230301-1108</merchantTransactionID>
<paymentMethodID>299</paymentMethodID>
<amount currencyCode="ZAR">11.01</amount>
<userID>OB-20230301-1108</userID>
<userData>
<username>testuser</username>
<firstname>Test</firstname>
<lastname>User</lastname>
<currencyCode>ZAR</currencyCode>
<email>[email protected]</email>
<address>
<street>123 home street</street>
<postalCode>123456</postalCode>
<city>Test city</city>
<state>Test state</state>
<countryCode2>ZA</countryCode2>
<telephoneNumber>0016479325666</telephoneNumber>
</address>
<gender>Male</gender>
</userData>
<userIP>127.0.0.22</userIP>
<userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://success.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancel.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ErrorPageUrl</key>
<value>https://error.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ProductCode</key>
<value>ott_voucher</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
Example initiatePaymentResponse:
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayProviderShop</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>OB-20230822-1440</merchantTransactionID>
<paymentID>54b82577-00a7-47e5-853a-e2d8f8f56350</paymentID>
<userID>OB-20230324-1030</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">0.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.22</userIP>
<state>
<id>60ef7c4b-8724-46e6-a21d-4aa6c0539699</id>
<definition>
<key>30</key>
<value>RedirectURLCreated</value>
</definition>
<createdOn>2023-08-22T12:44:52.9472861Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://agent.callpay.com/pay/hosted?payment_key=b1af6aec026b847c9715f704fa8a97e0&payment_type=kazangvoucher</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">0</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderSessionKey</key>
<value>b1af6aec026b847c9715f704fa8a97e0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>10583</value>
</detail>
</paymentDetails>
</payment>
</initiatePaymentResponse>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>{{merchant}}</merchantID>
<shopID>{{shop}}</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>OB-20230301-1109</merchantTransactionID>
<paymentID>9fc8d884-1bad-4f6e-8b9f-b72e4984e0fc</paymentID>
<userID>OB-20230301-1109</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">11.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.22</userIP>
<state>
<id>73affe02-3f86-41fc-b187-d8972b155353</id>
<definition>
<key>30</key>
<value>RedirectURLCreated</value>
</definition>
<createdOn>2023-03-01T11:06:24.6384766Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://agent.callpay.com/pay/hosted?payment_key=862491d0d117f4a464d3a6caecb0f3f0&payment_type=kazangvoucher</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">0.83</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>67</value>
</detail>
</paymentDetails>
</payment>
</initiatePaymentResponse>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>{{merchant}}</merchantID>
<shopID>{{shop}}</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>OB-20230301-1108</merchantTransactionID>
<paymentID>4a54a7a9-3b77-45ed-9161-484e1701f38a</paymentID>
<userID>OB-20230301-1108</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">11.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.22</userIP>
<state>
<id>35b077e1-c3eb-44ca-b036-ca049359eecb</id>
<definition>
<key>30</key>
<value>RedirectURLCreated</value>
</definition>
<createdOn>2023-03-01T11:04:25.542057Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://agent.callpay.com/pay/hosted?payment_key=017a88d787c09bee1cefd920eb29dc02&payment_type=ott_voucher</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">0.83</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>65</value>
</detail>
</paymentDetails>
</payment>
</initiatePaymentResponse>
The following parameters will be provided in initiatePaymentResponse:
Key | Value |
---|---|
RedirectionUrl | URL to which the user should be redirected to |
ProviderSessionKey | SessionKey from Call. Part of the RedirectionURL. Can be used within a checkout widget implementation to render a FORM POST to pass the voucher details. |
ProviderExternalID | ProviderExternalID from PXP. Reference that is sent to Callpay. |
Error States
Relevant error cases for the merchant include:
InitiateRefusedByProvider
RefusedByProvider
Example initiatePaymentResponse with error InitiateRefusedByProvider:
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xsi:type="paymentWithPaymentAccount">
<merchantID>{{merchant}}</merchantID>
<shopID>{{shop}}</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>OB-20230301-11003133</merchantTransactionID>
<paymentID>edd3fe55-0cb2-40b4-b262-cfb15b056e57</paymentID>
<userID>OB-20230301-1109</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">11.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.22</userIP>
<state>
<id>6f558ffb-e39d-4c8d-aa97-2febb8f8fad9</id>
<definition>
<key>550</key>
<value>InitiateRefusedByProvider</value>
</definition>
<createdOn>2023-03-23T09:20:26.2684978Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseMessage</key>
<value>Invalid merchant data specified. Success Url is not a valid URL.</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">0.83</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>2332</value>
</detail>
</paymentDetails>
</payment>
</initiatePaymentResponse>
Notifications
The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.
Example handlePaymentStateChangedNotificationRequest (DepositedByProvider):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xmlns="http://www.cqrpayments.com/PaymentProcessing"
xsi:type="paymentWithPaymentAccount">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayProviderShop</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>hc-20230302-125607</merchantTransactionID>
<paymentID>a6b3b9d6-e557-4fb4-8cc9-1cc06121c714</paymentID>
<userID>hc20230302125607</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">10.0000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>cdb3d698-629f-40bf-9d43-eba93bbac0c3</id>
<definition>
<key>29</key>
<value>DepositedByProvider</value>
</definition>
<createdOn>2023-03-02T11:57:08.093</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderStatusCode</key>
<value>complete</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">0.7600</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>318</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>91677465</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Example handlePaymentStateChangedNotificationRequest (RefusedByProvider):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xmlns="http://www.cqrpayments.com/PaymentProcessing"
xsi:type="paymentWithPaymentAccount">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayProviderShop</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>hc-20230302-125538</merchantTransactionID>
<paymentID>6857fe6c-44be-4a42-8285-2628f1b9cde3</paymentID>
<userID>hc20230302125538</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">10.0000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>31a58ee2-4dc1-4f45-b478-d3a3ccdc9e32</id>
<definition>
<key>100</key>
<value>RefusedByProvider</value>
</definition>
<createdOn>2023-03-02T11:56:07.407</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseMessage</key>
<value>Insufficient funds</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderStatusCode</key>
<value>failed</value>
</detail>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">0.7600</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>317</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>91677403</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Example handlePaymentStateChangedNotificationRequest (Aborted):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<payment xmlns="http://www.cqrpayments.com/PaymentProcessing"
xsi:type="paymentWithPaymentAccount">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayMockShop</shopID>
<paymentMethod>
<key>299</key>
<value>VoucherRedirectDeposit</value>
</paymentMethod>
<merchantTransactionID>890db329-b444-4bb3-8435-cbe21b349a84</merchantTransactionID>
<paymentID>37879d2a-435b-4696-9fe0-52efd83a88c9</paymentID>
<userID>fea02f70-4bc6-428c-898b-0fc6ff</userID>
<paymentProvider>
<key>206</key>
<value>Callpay</value>
</paymentProvider>
<amount currencyCode="ZAR">20.0200</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>8abb1a3f-ff3e-4cfd-bb27-4d75dd962f9e</id>
<definition>
<key>524</key>
<value>Aborted</value>
</definition>
<createdOn>2023-03-27T15:46:41.377</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseMessage</key>
<value>Aborted</value>
</detail>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">1.5100</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>2567</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Testing
The states InitiateRefusedByProvider, InitiateRequestProviderCommunicationErrorOccurred and InitiateErrorReportedByProvider may be tested with the merchant mock - see the instructions in the XML below.
All other states should be tested with provider.
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>B2BTestMerchant</merchantID>
<shopID>CallpayMockShop</shopID>
<merchantTransactionID>OB-20230829-04</merchantTransactionID>
<paymentMethodID>299</paymentMethodID>
<amount currencyCode="ZAR">33.15</amount>
<!--33.13 InitiateRefusedByProvider
33.14 InitiateRequestProviderCommunicationErrorOccurred
33.15 InitiateErrorReportedByProvider
any other amount RedirectURLCreated -->
<userID>OB-20230829-01</userID>
<userData>
<username>testuser</username>
<firstname>Test</firstname>
<lastname>User</lastname>
<currencyCode>ZAR</currencyCode>
<email>[email protected]</email>
<address>
<street>123 home street</street>
<postalCode>123456</postalCode>
<city>Test city</city>
<state>Test state</state>
<countryCode2>ZA</countryCode2>
<telephoneNumber>0016479325666</telephoneNumber>
</address>
<gender>Male</gender>
</userData>
<userIP>127.0.0.22</userIP>
<userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://success.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancel.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ErrorPageUrl</key>
<value>https://error.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ProductCode</key>
<value>bluvoucher</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
Updated over 1 year ago