GuidesAPI ReferenceDiscussions
Guides
Start typing to search…

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).

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:

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.

Updated 17 days ago