PaysafeCash Deposit (via Paysafecard)

Paysafecash is an alternative cash-based payment method that makes it possible for the customer to pay securely and easily with cash on the Internet. Using Paysafecash, products or services can be ordered online and then paid for with cash offline at the nearest payment point by scanning a QR/barcode.

The following method IDs are covered in this section:

ID	Name	Credit/ Debit State
422	PaysafeCash Deposit	ExecutedByProvider
425	PaysafeCash Refund	Refunded

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

The customer selects Paysafecash as the preferred payment option in the merchant’s webshop.
The business partner initiates the payment with the correct amount, currency and other parameters.
The business partner redirects the customer to Paysafecash's hosted barcode application.
The customer has 30 minutes to login with its Paysafecash username/password and generate a barcode. The barcode will only be valid for this specific transaction.
The barcode can be viewed in various ways (e.g. online, Paysafecash app, download, e-mail, SMS or iOS / Android passbook file).
The customer brings the barcode to a payment point, has it scanned and pays for the transaction amount. A predefined time frame ("Transaction Timeout”) will be available for the payment completion.
The duration of this time frame is by default 72 hours, unless specified otherwise by the business partner.
Once the payment is done at the POS, the money will be assigned to the transaction and paysafecard captures the payment on behalf of the business partner.
A webhook notification request is sent to the business partner.
The business partner must verify the webhook notification.
Upon successfully verifying the webhook notification, the business partner completes the transaction in its database and delivers the product/service to the customer.

Redirect Integration

Currently not supported.

Backend2BackendIntegration

For non-US countries: Sending data of the user would improve user's experience by pre-populating his/ her data in the registration form for Paysafecard. The following parameters can be provided in the initiatePaymentRequest.userData xml section:

key (value type, account type, required)	value
firstname (string, optional)	The user´s first name
lastname (string, optional)	The user´s last name
dateOfBirth (dateTime, optional)	The user's date of birth
address.street (string, optional)	The user's street
address.houseNumber (string, optional)	The user's house number
address.postalCode (string, optional)	The user's postal code
address.city (string, optional)	The user's city
address.countryCode2 (twoLetterCode, optional)	The user´s country code
telephoneNumber (string, optional)	The user´s telephone number
email (string, optional)	The user’s email address

For US: Paysafecard account is not required and the barcode is directly displayed to the user upon creating an order.

🚧
Use same UserID for all payments initiated by the user
userID should be the same for all payments of the customer.

Example initiatePayment request:

<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>B2BPaysafeCashShop</shopID>
    <merchantTransactionID>{{$guid}}</merchantTransactionID>
    <paymentMethodID>422</paymentMethodID>
    <amount currencyCode="EUR">15.00</amount>
    <userID>TestUser_Paysafecash_01</userID>
    <userData>
        <username>TestUser_Paysafecash_01</username>
        <firstname>John</firstname>
        <lastname>Doe</lastname> 
        <email>[email protected]</email>
        <address>
            <street>Marxergasse</street>
            <houseNumber>1b</houseNumber>
            <postalCode>1010</postalCode>
            <city>Vienna</city>
            <countryCode2>AT</countryCode2>
            <telephoneNumber>00437778889999</telephoneNumber>
        </address>
         <dateOfBirth>1986-10-10T00:00:00</dateOfBirth>
        <gender>Male</gender>
        <identificationNumberType xsi:nil="true" />
        <drivingLicenseNumber xsi:nil="true" />
        <drivingLicenseIssuingState xsi:nil="true" />
    </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>7d810381-7449-4c6a-8bfd-6967880ceae6</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>SuccessPageUrl</key>
            <value>https://www.pxpfinancial.com</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ErrorPageUrl</key>
            <value>https://pxpfinancial.com/failed</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

Example initiatePayment response:

<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>B2BPaysafeCashShop</shopID>
        <paymentMethod>
            <key>422</key>
            <value>PaysafeCash Deposit</value>
        </paymentMethod>
        <merchantTransactionID>8dfb0adc-5a02-4e80-a765-ff7832f7157d</merchantTransactionID>
        <paymentID>cd3e55b5-cdf8-47fd-900b-dd65e8cdf29a</paymentID>
        <userID>TestUser_Paysafecash_01</userID>
        <paymentProvider>
            <key>19</key>
            <value>Paysafecard</value>
        </paymentProvider>
        <amount currencyCode="EUR">15.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>3d9015bf-4051-4c77-89e8-86e98cb35b6f</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2021-10-08T11:37:10.4330194Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://customer.test.at.paysafecard.com/rest/payment/panel?mid=1090001806&amp;mtid=pay_1090001806_5402f924-93fa-4d94-aa50-1f573f4b360f_EUR&amp;amount=15.00&amp;currency=EUR</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">15</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>pay_1090001806_5402f924-93fa-4d94-aa50-1f573f4b360f_EUR</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>38277625</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

The below diagram shows the workflow of states for PaysafeCash Deposit:

Refund

The refund feature provides the business partners the possibility to fully or partially refund a previously paid transaction back into the customer‘s my paysafecard account.

the customer needs to have paysafecard account
Refund is possible up to 45 days after the initial payment
Refund transaction must refer to a previous transaction
Only the full or less/partial amount can be refunded, higher amount can not be refunded
Refund will always be issued in the currency of the original payment transaction

🚧
Refunds are available only for non-US countries!

For triggering a card deposit refund the initiatePaymentFromReferenceRequest should be invoked.

The following fields should be provided in the initiatePaymentFromReference request:

Field	Description
amount	The amount to be refund to the customer credit card. Partial refunds are possible.
paymentMethodID	425
merchantTransactionID	The unique ID of the payment assigned by the merchant
originalPaymentID	The `paymentID` of the original payment
specificPaymentData.PaymentDescription	Your reason for the refund

Example initiatePaymentFromReference request:

<initiatePaymentFromReferenceRequest
  xmlns="http://www.cqrpayments.com/PaymentProcessing"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>PaysafecashPTShop</shopID>
    <originalPaymentID>cd3e55b5-cdf8-47fd-900b-dd65e8cdf29a</originalPaymentID>
    <merchantTransactionID>refa5998ec6-b460-4c12-81dd-b92a387cce2e</merchantTransactionID>
    <paymentMethodID>425</paymentMethodID>
    <amount currencyCode="EUR">10.00</amount>
    <specificPaymentData>              
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>YourReasonForRefund</value>
        </data>
    </specificPaymentData>
</initiatePaymentFromReferenceRequest>

Example initiatePaymentFromReference response:

<initiatePaymentFromReferenceResponse 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>PaysafecashPTShop</shopID>
        <paymentMethod>
            <key>425</key>
            <value>PaysafeCash Refund</value>
        </paymentMethod>
        <merchantTransactionID>refa5998ec6-b460-4c12-81dd-b92a387cce2e</merchantTransactionID>
        <paymentID>cd3e55b5-cdf8-47fd-900b-dd65e8cdf29a</paymentID>
        <userID>TestUser_Paysafecash_01</userID>
        <paymentProvider>
            <key>19</key>
            <value>Paysafecard</value>
        </paymentProvider>
        <amount currencyCode="EUR">10.00</amount>
        <creationType>
            <key>2</key>
            <value>MerchantOperator</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>1d67e89e-c39d-4bba-b24e-2ac3b305db07</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2021-09-13T14:51:53.0059561Z</createdOn>
            <paymentStateDetails xsi:nil="true"></paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">10</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>37920005</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>ref_1100003139_LSdvzAuT7TI5x7E7P8BZJybXTveOagjO_EUR</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>37920045</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentFromReferenceResponse>

Notifications

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

Notifications are sent for the following two states: ExecutedByProvider (142) and Expired (102).

Error Codes

When an error occurs, the payment is moved to state 'InitiateErrorReportedByProvider' - errors logged in the payments stated additional details in field 'ProviderErrorCode' and 'Provider Error Message'.

Code	Description
10007	General technical error.
10008	Authentication failed due to missing or invalid API key. Your key needs to be set to the HTTP auth username.
10028	One of the request parameters failed validation. The `message` and `param` fields contain more detailed information.
142	The supplied currency is not supported
2001	Transaction already exists.
2002	Transaction not found
3001	Merchant is not active.
3007	Debit attempt after expiry of dispo time window.
3014	The `submerchant_id` specified by you has not been configured.
3037	The time set in the parameter "expiration_time_minutes" is not in the allowed span (between 5 and 20160 minutes).
3172	Feature not active disabled
3017	It is mandatory to send an MCID.
3019	MCID contains invalid values.

Redirect Integration

Backend2BackendIntegration

🚧Use same UserID for all payments initiated by the user

Refund

🚧

Notifications

Error Codes

🚧
Use same UserID for all payments initiated by the user