GuidesAPI ReferenceDiscussions

VoucherRedirectDeposit (Callpay)

Suggest Edits

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:

IDNameCredit/Debit State
299VoucherRedirectDepositDepositedByProvider (29)

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

Flow

781

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>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
        <paymentMethod>
            <key>299</key>
            <value>VoucherRedirectDeposit</value>
        </paymentMethod>
        <merchantTransactionID>OB-20230301-1107</merchantTransactionID>
        <paymentID>f8834cc1-19ba-4aad-a136-9de682561422</paymentID>
        <userID>OB-20230301-1107</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>6f68ad84-7606-4b93-a681-421feec28841</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2023-03-01T10:50:20.6820235Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://agent.callpay.com/pay/hosted?payment_key=e2a8f1dececf5d55a66a06af75fc4b02&amp;payment_type=bluvoucher</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>62</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&amp;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&amp;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>

📘

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>

Updated 2 months ago