GuidesAPI ReferenceDiscussions
Guides

PaysafeCash Deposit (via Paysafecard)

Suggest Edits

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:

IDNameCredit/ Debit State
422PaysafeCash DepositExecutedByProvider
425PaysafeCash RefundRefunded

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

777
  • 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:

671

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:

FieldDescription
amountThe amount to be refund to the customer credit card. Partial refunds are possible.
paymentMethodID425
merchantTransactionIDThe unique ID of the payment assigned by the merchant
originalPaymentIDThe paymentID of the original payment
specificPaymentData.PaymentDescriptionYour 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'.

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

Updated about 3 years ago