OTTVoucherWithdrawal (Callpay)

The OTTVoucherWithdrawal method supports OTT voucher withdrawals through provider Callpay in South Africa with Standard Bank Instant Money.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
439	OTTVoucherWithdrawal	WithdrawnByProvider (20)

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

Supported currency: only ZAR

Flow

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters can be provided in initiatePaymentRequest.User or the need to be present on the user before the initiatePaymentRequest is sent.

key (value type, account type, required)	Description
firstName (string, required)	User´s first name.
lastName (string, required)	User´s last name.
email (string, required)	User´s email address.
dateOfBirth (string, required)	User´s date of birth.
gender (string, required)	User´s gender ("Male" or "Female").
telephoneNumber (string, required)	User´s telephone number.
identificationNumber (string, required)	User´s identification number, valid ID or passport number.
identificationNumberType (string, required)	User´s identification number type - "RSAID" or "PASSPT"
nationality (string, required)	User´s nationality, eg. ZA
identificationIssuingCountry (string, required)	User´s identification document issuing country, e.g. ZA

The following parameters can be provided in initiatePaymentRequest.specificPaymentData

key (value type, account type, required)	Value
PaymentProviderID (string)	206 (Callpay)

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>B2BTestMerchant</merchantID>
	<shopID>CallpayProviderShop</shopID>
	<merchantTransactionID>OB-20230321-0002</merchantTransactionID>
	<paymentMethodID>439</paymentMethodID>
	<amount currencyCode="ZAR">50.00</amount>
	<userID>OB-20230321-0001</userID>
	<userData>
		<firstname>Oksana</firstname>
		<lastname>Bulgakova</lastname>
		<email>[email protected]</email>
		<address>
			<countryCode2>ZA</countryCode2>
			<telephoneNumber>27836677704</telephoneNumber>
		</address>
		<dateOfBirth>1984-11-04T00:00:00</dateOfBirth>
		<gender>Female</gender>
		<identificationNumber>8403241111111</identificationNumber>
		<identificationNumberType>PASSPT</identificationNumberType>
		<nationality>ZA</nationality>
		<identificationIssuingCountry>ZA</identificationIssuingCountry>
	</userData>
	<userIP>127.0.0.22</userIP>
	<userSessionID>08b980b9-b5be-4d0a-9e1b-a6541d6ac9ce</userSessionID>
	<creationTypeID>1</creationTypeID>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>CallpayProviderShop</shopID>
		<paymentMethod>
			<key>439</key>
			<value>OTT Voucher Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>6da35c60-c5a4-4f58-b63b-97b316d9e8c5</merchantTransactionID>
		<paymentID>8b69dc1c-5653-4a04-8249-b143d694c68e</paymentID>
		<userID>19b43207-d4cf-4820-852b-15bd61</userID>
		<paymentProvider>
			<key>206</key>
			<value>Callpay</value>
		</paymentProvider>
		<amount currencyCode="ZAR">100.10</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>fdb81e01-b4b7-4e65-81db-5e0fb33c8907</id>
			<definition>
				<key>20</key>
				<value>WithdrawnByProvider</value>
			</definition>
			<createdOn>2023-03-16T12:43:13.9618048Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Withdrawal successfully requested</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">7.57</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>4261780</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>1077</value>
			</detail>
		</paymentDetails>
	</payment>

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>B2BTestMerchant</merchantID>
        <shopID>CallpayProviderShop</shopID>
        <paymentMethod>
            <key>439</key>
            <value>OTT Voucher Withdrawal</value>
        </paymentMethod>
        <merchantTransactionID>c323c7f5-d4a2-46c8-b19a-39f47530cf54CC4</merchantTransactionID>
        <paymentID>fb962ca4-ffe3-4403-8a3f-098a83775102</paymentID>
        <userID>306111f7-d3e2-4e27-ba36-842e31</userID>
        <paymentProvider>
            <key>206</key>
            <value>Callpay</value>
        </paymentProvider>
        <amount currencyCode="ZAR">100.10</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>aa479665-e0cc-48bf-b588-1491e8eafc64</id>
            <definition>
                <key>100</key>
                <value>RefusedByProvider</value>
            </definition>
            <createdOn>2023-03-16T12:48:13.2657194Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>South African ID Number check digit fails, please check.</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">7.57</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1079</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Payments will go to InitiateRefusedProvider as the data is validated by Callpay.
On an error PXP returns the detail ProviderResponseMessage.

Example initiatePaymentResponse with error InitiateRequestProviderCommunicationErrorOccurred**:

<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>439</key>
			<value>OTT Voucher Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>OB-20230321-0001</merchantTransactionID>
		<paymentID>8f09256f-3cf1-4a92-b009-28f21452f504</paymentID>
		<userID>OB-20230321-0001</userID>
		<paymentProvider>
			<key>206</key>
			<value>Callpay</value>
		</paymentProvider>
		<amount currencyCode="ZAR">50.00</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.22</userIP>
		<state>
			<id>22e8d15b-2956-4911-ac3e-43cc614b0e78</id>
			<definition>
				<key>576</key>
				<value>WithdrawCommunicationErrorOccurred</value>
			</definition>
			<createdOn>2023-03-21T11:27:30.7476103Z</createdOn>
			<description>Error occurred while processing payment communication for Payment[ID='46220055'].</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">3.78</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>1944</value>
			</detail>
		</paymentDetails>
	</payment>
</initiatePaymentResponse>

Payments in state InitiateRequestProviderCommunicationErrorOccurred maybe be moved to InitiatedByProvider upon receiving notification from provider.

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.