GuidesAPI ReferenceDiscussions
Guides
Start typing to search…

Card Deposits via PaySafe

The following method IDs are covered in this section:

IDNameCredit / Debit state
1ECMC Deposit (Mastercard)AuthorisedByProvider (13)
CapturedByProvider (27)
2VISA DepositAuthorisedByProvider (13)
CapturedByProvider (27)
113AMEX DepositAuthorisedByProvider (13)
CapturedByProvider (27)
📘

AMEX Deposit not available

AMEX Deposits are not available for Moneris in Canada.

Payment method interaction type: Synchronous Execution (see Interaction Types)

The card integration with Paysafe follows a generic card integration flow. 3DS (without PSD2 specifics) and Applepay/GooglePay will be supported.

Redirect Integration

There are no specific steps for initiating Card Deposits with Redirect Integration. Refer to Initiate New Payment (Redirect) for the standard steps.

Backend2Backend Integration

Authorization

To initiate a card deposit the initiatePayment web method should be invoked. The following table contains additional data fields that can be passed in the specificPaymentData collection:

Key (value type, account type, required)Description
PaymentDescription (string)Payment description; set up in conjuction with the pre-defined merchant template. However, Paysafe only accepts the first 20 characters.
IsThreeDSecureConditionalRequired (boolean)Generic 3DS setup value
Is3DSecureRequired (boolean)Generic 3DS setup value
PaymentProviderIDPlease set provider ID "19".

The userIP may be passed in the initiatePaymentRequest:

key (value type, account type, required)value
userIP (string)Users IPv4. Paysafe does not support IPv6 addresses

For AVS the merchant may pass AVS related fields within specificPaymentData (AVSCountry, AVSStreetAddress, and AVSPostCode). Alternatively user details are sent to provider.

Example initiatePaymentRequest (without 3DS):

<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>{{merchant}}</merchantID>
	<shopID>{{shop}}</shopID>
	<merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
	<paymentMethodID>2</paymentMethodID>
	<amount currencyCode="cad">20.52</amount>
	<userID>{{newUserID}}</userID>
	<userData>
		<username>{{newUserName}}</username>
		<firstname>Sherlöck</firstname>
		<lastname>Hólms</lastname>
		<currencyCode>EUR</currencyCode>
		<languageCode>EN</languageCode>
		<email>[email protected]</email>
		<address>
			<street>Marxergasse</street>
			<houseNumber>1b</houseNumber>
			<postalCode>1030</postalCode>
			<city>Vienna</city>
			<countryCode2>AT</countryCode2>
			<telephoneNumber>00437778889999</telephoneNumber>
		</address>
		<dateOfBirth>1980-10-10T00:00:00</dateOfBirth>
		<gender>Male</gender>
	</userData>
	<userIP>80.121.151.158</userIP>
	<userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
	<creationTypeID>3</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>some description</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescriptionLanguageCode</key>
			<value>en</value>
		</data>
		<data xsi:type="keyBooleanValuePair">
			<key>IsThreeDSecureConditionalRequired</key>
			<value>false</value>
		</data>
		<data xsi:type="keyBooleanValuePair">
			<key>IsThreeDSecureRequired</key>
			<value>false</value>
		</data>
		<data xsi:type="keyIntValuePair">
			<key>PaymentProviderID</key>
			<value>19</value>
		</data>
	</specificPaymentData>
	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>CardNumber</key>
				<value>4111111111111111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>CardVerificationCode</key>
				<value>111</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryMonth</key>
				<value>12</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryYear</key>
				<value>2030</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>HolderName</key>
				<value>Sir Stenley Roise</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentRequest (with AVS details sent in specificPaymentData section):

<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>{{merchant}}</merchantID>
	<shopID>{{shop}}</shopID>
	<merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
	<paymentMethodID>1</paymentMethodID>
	<amount currencyCode="cad">156.06</amount>
	<userID>{{newUserID}}</userID>
	<userData>
		<username>{{newUserName}}</username>
		<firstname>John</firstname>
		<lastname>Doe</lastname>
		<currencyCode>EUR</currencyCode>
		<languageCode>EN</languageCode>
		<email>[email protected]</email>
		<address>
			<street>Marxergasse</street>
			<houseNumber>1b</houseNumber>
			<postalCode>1030</postalCode>
			<city>Vienna</city>
			<countryCode2>AT</countryCode2>
			<telephoneNumber>00437778889999</telephoneNumber>
		</address>
		<dateOfBirth>1980-10-10T00:00:00</dateOfBirth>
		<gender>Male</gender>
	</userData>
	<userIP>80.121.151.158</userIP>
	<userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>some description</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescriptionLanguageCode</key>
			<value>en</value>
		</data>
		<data xsi:type="keyBooleanValuePair">
			<key>IsThreeDSecureRequired</key>
			<value>false</value>
		</data>
		<data xsi:type="keyIntValuePair">
			<key>PaymentProviderID</key>
			<value>19</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>AVSCountry</key>
			<value>US</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>AVSStreetAddress</key>
			<value>4161 Red Maple Drive</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>AVSPostCode</key>
			<value>90017</value>
		</data>
	</specificPaymentData>
	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>CardNumber</key>
				<value>5266248793296818</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>CardVerificationCode</key>
				<value>111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>HolderName</key>
				<value>John Doe</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryMonth</key>
				<value>1</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryYear</key>
				<value>2033</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentResponse (AuthorisedByProvider):

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>2</key>
			<value>VISA Deposit</value>
		</paymentMethod>
		<merchantTransactionID>hc-20250521-120348</merchantTransactionID>
		<paymentID>b8dd40a8-d4f3-4a76-833e-7f235fe7507a</paymentID>
		<userID>hc20250521120348</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafecard</value>
		</paymentProvider>
		<amount currencyCode="CAD">20.52</amount>
		<creationType>
			<key>3</key>
			<value>Api</value>
		</creationType>
		<userIP>80.121.151.158</userIP>
		<state>
			<id>34ab89aa-f59b-4952-82b6-f8e33f9e7afe</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2025-05-21T10:03:49.8382128Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponse</key>
					<value>F</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponseMessage</key>
					<value>Exact match</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CVCResponse</key>
					<value>Matched</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Approved or completed successfully</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>211744</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">14.82</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ElectronicCommerceIndicator</key>
				<value>07</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>c96ef3be-9fca-4f3b-ae30-58d32e7283ae</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150702894</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>4ca12032-872b-4d58-a55d-5242008b3620</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>AT</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Credit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value/>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

The following payment state details are included in the initiatePaymentResponse:

DetailDescription
AVSResponseAVS response value
AVSResponseMessageAVS response message
CVCResponseCVC response value
ProviderResponseCodemapped ISO code
ProviderResponseMessagemapped ISO code message
ApprovalCodeapproval code
ProviderErrorResponseCodeerror code from Paysafe (on payments in state RefusedByProvider and in state AuthoriseErrorReportedByProvider)
ProviderErrorResponseMessageerror code from Paysafe (on payments in state RefusedByProvider and in state AuthoriseErrorReportedByProvider)

The following payment details are included in the initiatePaymentResponse:

DetailDescription
ElectronicCommerceIndicatorECI value
ProviderTransactionIDTransaction ID from Paysafe
ProviderExternalIDID sent by PXP to Paysafe

Example initiatePaymentResponse with account details:

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>1</key>
			<value>ECMC Deposit</value>
		</paymentMethod>
		<merchantTransactionID>hc-20250521-120749</merchantTransactionID>
		<paymentID>c9121203-f2ff-4edb-b424-d88f4aec8585</paymentID>
		<userID>hc20250521120749</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafecard</value>
		</paymentProvider>
		<amount currencyCode="CAD">156.06</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>80.121.151.158</userIP>
		<state>
			<id>6fdb7999-7857-48fd-96e9-4b1b4516e7e9</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2025-05-21T10:08:01.2083846Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponse</key>
					<value>F</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponseMessage</key>
					<value>Exact match</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CVCResponse</key>
					<value>Matched</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Approved or completed successfully</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>212414</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">112.7</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ElectronicCommerceIndicator</key>
				<value>07</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>16541b4e-1b80-4773-80ca-59c0de81444c</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150702897</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>11ba65dc-e654-42be-83a5-2f8a3d77f829</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>AT</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Debit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value>Some Bank</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>MaskedNumber</key>
					<value>526624******6818</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwnerToken</key>
					<value>085ce085-f91e-45f4-b67a-0d15b7cfa6a9</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryMonth</key>
					<value>1</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryYear</key>
					<value>2033</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>HolderName</key>
					<value>John Doe</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CardType</key>
					<value>Mastercard</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Sample initiatePaymentResponse for RefusedByProvider:

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>1</key>
			<value>ECMC Deposit</value>
		</paymentMethod>
		<merchantTransactionID>hc-20250521-135221</merchantTransactionID>
		<paymentID>cf63be25-0837-483e-9df8-9131009a9bcb</paymentID>
		<userID>hc20250521135221</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafecard</value>
		</paymentProvider>
		<amount currencyCode="CAD">0.04</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>80.121.151.158</userIP>
		<state>
			<id>59ad1d3d-f8ae-4ac2-93ca-fc1e2f3cb123</id>
			<definition>
				<key>100</key>
				<value>RefusedByProvider</value>
			</definition>
			<createdOn>2025-05-21T11:52:23.1940448Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponse</key>
					<value/>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponseMessage</key>
					<value/>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CVCResponse</key>
					<value>Matched</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseCode</key>
					<value>3015</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseMessage</key>
					<value>The bank has requested that you process the transaction manually by calling the cardholder's credit card company.</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>2</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Refer to card issuer's special condition</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">0.03</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ElectronicCommerceIndicator</key>
				<value>07</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>2ec72b45-172b-4115-997a-810706a5dd81</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150702934</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>d262d563-0bd1-4160-9336-611d8287e432</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>AT</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Debit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value>Some Bank</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>MaskedNumber</key>
					<value>526624******6818</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwnerToken</key>
					<value>085ce085-f91e-45f4-b67a-0d15b7cfa6a9</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryMonth</key>
					<value>1</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryYear</key>
					<value>2033</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>HolderName</key>
					<value>John Doe</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CardType</key>
					<value>Mastercard</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Note: This response includes the mapped ISO code in ProviderResponseCode and ProviderResponseCode and the error code from Paysafe in ProviderErrorResponseCode and ProviderErrorResponseMessage.

The payment will go to RefusedByProvider if the response from Paysafe includes a acquirerResponse - for Canada from Moneris - and in all other cases it will go to AuthoriseErrorReportedByProvider. This may include also cases where the acquirerResponse is present but authCode is missing or null.

Authorisation error codes for Paysafe are listed here.

Error code (from Paysafe)Description
3004The zip/postal code must be provided for an AVS check request.
3005You submitted an incorrect CVV value with your request.
3006You submitted an expired credit card number with your request.
3007Your request has failed the AVS check. Note that the amount has still been reserved on the customer's card and will be released in 3-5 business days. Please ensure the billing address is accurate before retrying the transaction.
3009Your request has been declined by the issuing bank.
3011Your request has been declined by the issuing bank because the card used is a restricted card. Contact the cardholder's credit card company for further investigation.
3012Your request has been declined by the issuing bank because the credit card expiry date submitted is invalid.
3013Your request has been declined by the issuing bank due to problems with the credit card account.
3014Your request has been declined - the issuing bank has returned an unknown response. Contact the card holder's credit card company for further investigation.
3015The bank has requested that you process the transaction manually by calling the cardholder's credit card company.
3016The bank has requested that you retrieve the card from the cardholder - it may be a lost or stolen card.
3017You submitted an invalid credit card number with your request.
3018The bank has requested that you retry the transaction.
3019Your request has failed the CVV check. Please note that the amount may still have been reserved on the customer's card, in which case it will be released in 3-5 business days.
3020The bank has requested that you retry the transaction.
3022The card has been declined due to insufficient funds.
3023Your request has been declined by the issuing bank due to its proprietary card activity regulations.
3024Your request has been declined because the issuing bank does not permit the transaction for this card.
3025The external processing gateway has reported invalid data.
3027The external processing gateway has reported a limit has been exceeded.
3028The external processing gateway has reported a system error.
3029The external processing gateway has rejected the transaction.
3030The external processing gateway has reported the transaction is unauthorized.
3035Your request has been declined due to exceeded PIN tries.
3036Your request has been declined due to an invalid issuer.
3037Your request has been declined because it is invalid.
3039Your request has been declined due to an invalid authentication value.
3040Your request has been declined because the request type is not permitted on the card.
3041Your request has been declined due to a timeout.
3042Your request has been declined due to a cryptographic error.
3054The transaction was declined due to suspected fraud.
3057Please tell cardholder to call the issuer. Do not retry transaction.
3073Your request has been declined due to closed customer account.
3703The external gateway has reported that you have submitted an invalid amount with your request.
4001The card number or email address associated with this transaction is in our negative database.
4002The transaction was declined by our Risk Management department.
5003You submitted an invalid amount with your request.
5017The merchant account submitted with your request is disabled.
5031Duplicate merchant reference
5031The transaction you have submitted has already been processed.
5034You submitted an invalid email address with your request.
5037You submitted an invalid zip/postal code with your request.
5040Your merchant account is not configured for the transaction you attempted.
5050An error occurred with your merchant account configuration.

Sample initiatePaymentResponse for AuthoriseErrorReportedByProvider:

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>113</key>
			<value>AMEXDeposit</value>
		</paymentMethod>
		<merchantTransactionID>hc-20250521-123636</merchantTransactionID>
		<paymentID>2cbe444d-d406-4ec4-bfca-cde8c71aaf05</paymentID>
		<userID>hc20250521123636</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafecard</value>
		</paymentProvider>
		<amount currencyCode="CAD">0.25</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>1c7c2a45-5b3b-474f-ab16-6abc1bac8d2d</id>
			<definition>
				<key>14</key>
				<value>AuthoriseErrorReportedByProvider</value>
			</definition>
			<createdOn>2025-05-21T10:36:38.1281539Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponse</key>
					<value/>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AVSResponseMessage</key>
					<value/>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseCode</key>
					<value>4001</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorResponseMessage</key>
					<value>The card number or email address associated with this transaction is in our negative database.</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">0.18</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ElectronicCommerceIndicator</key>
				<value>07</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>74d8c4ad-a67a-443a-902c-a11d598e20ab</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150702926</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>75eeb8ec-cf8f-49ed-be7f-95d14fd2dc96</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>GB</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Credit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value>AMEX UK CONSUMER CHARGE</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>MaskedNumber</key>
					<value>374251*****0000</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwnerToken</key>
					<value>bc55af0e-e033-4d63-9d69-361e854ccdf2</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryMonth</key>
					<value>12</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryYear</key>
					<value>2030</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>HolderName</key>
					<value>Sir Stenley Roise</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CardType</key>
					<value>AmericanExpress</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Note: the response include the error code from Paysafe in ProviderErrorResponseCode and the error message in ProviderErrorResponseMessage.

Sample initiatePaymentResponse when a communication error occurs:

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>2</key>
			<value>VISA Deposit</value>
		</paymentMethod>
		<merchantTransactionID>hc-20250521-141743</merchantTransactionID>
		<paymentID>662bc794-2095-441b-848e-b7cc233b6392</paymentID>
		<userID>hc20250521141743</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafecard</value>
		</paymentProvider>
		<amount currencyCode="CAD">20.52</amount>
		<creationType>
			<key>3</key>
			<value>Api</value>
		</creationType>
		<userIP>80.121.151.158</userIP>
		<state>
			<id>8a8e12da-9461-48f7-b64d-89ff68d6a169</id>
			<definition>
				<key>336</key>
				<value>AuthoriseCommunicationErrorOccurred</value>
			</definition>
			<createdOn>2025-05-21T12:17:44.2960716Z</createdOn>
			<description>A communication error occurred during authorization.</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">14.82</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ElectronicCommerceIndicator</key>
				<value>07</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150702963</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>f231380c-c2ff-4dff-86de-edc876004b50</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>AT</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Credit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value/>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Refund

In order to refund an existing card deposit, the merchant should sent a initiatePaymentFromReference call.

📘

Refunds on production and sandbox

Refunds are recommended to be sent only when the related card deposit has been captured and cleared with the processor (Moneris).

In production, Paysafe sends captured payments to the processor every morning at 6 am EDT/EST (11 am UTC). In sandbox, captured payments are sent out every hour.

If a captured payment has not yet been sent to processor, and merchant will initiate a refund, PXP will return the state RefundAccepted indicating that sending the refund to provider is scheduled.

Following states can be returned in initiatePaymentFromReference response:

StateDescription
RefundAcceptedThis indicates that sending the refund to provider Paysafe is being scheduled. This occurs when the related deposit has not yet been sent out by the provider to the processor for capturing.
RefundInitiatedThe refund has been accepted by the provider Paysafe and is scheduled for sending out to the processor. A query will be executed at 11:00 am UTC.
RefundRefusedByProviderThe refund has been refused by the provider Paysafe. See below for the list of error codes.
RefundErrorOccurredAn error has been returned by the provider. See below for the list of error codes.
RefundCommunicationErrorOccurredWhen sending the refund to provider, a timeout occured and no response was received from provider. The refund may or may not have been processed by the provider. A query will be executed at 11:00 am UTC and the final payment status will be notified to merchant.

See further below for final states.

Sample initiatePaymentFromReference request (Visa Refund):

<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>{{merchant}}</merchantID>
	<shopID>{{shop}}</shopID>
	<originalPaymentID>{{originalPaymentUniqueID}}</originalPaymentID>
	<merchantTransactionID>{{refundMerchantTransactionID}}</merchantTransactionID>
	<paymentMethodID>88</paymentMethodID>
	<amount currencyCode="cad">2</amount>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>refund payment</value>
		</data>
	</specificPaymentData>
	<creationTypeID>3</creationTypeID>
</initiatePaymentFromReferenceRequest>

Sample initiatePaymentFromReferenceResponse (Visa Refund) with state RefundAccepted:

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>88</key>
			<value>VISA Refund</value>
		</paymentMethod>
		<merchantTransactionID>hc-refund-20250605-113758</merchantTransactionID>
		<paymentID>4c5d1ac5-472f-43c1-8092-b28089bcdf40</paymentID>
		<userID>hc20250605113707</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">2</amount>
		<creationType>
			<key>3</key>
			<value>Api</value>
		</creationType>
		<userIP>80.121.151.158</userIP>
		<state>
			<id>1cbb9077-d99c-48c1-9d28-ce9170aa0cb6</id>
			<definition>
				<key>642</key>
				<value>RefundAccepted</value>
			</definition>
			<createdOn>2025-06-05T09:37:59.0027435Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">1.44</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyLongValuePair">
				<key>OriginalPaymentID</key>
				<value>2150989608</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150989617</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>67b655ef-0e61-4e84-ba99-d5aace4ac62b</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>AT</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Credit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value/>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>MaskedNumber</key>
					<value>411111******1111</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwnerToken</key>
					<value>532ea578-41fb-4132-a159-c4bcdc091c0a</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryMonth</key>
					<value>12</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryYear</key>
					<value>2030</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>HolderName</key>
					<value>Sir Stenley Roise</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CardType</key>
					<value>Visa</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentFromReferenceResponse>

Sample initiatePaymentFromReference response (AMEX Refund) with state RefundInitiated:

<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>PaysafeCCDepositsProviderTestingShop</shopID>
		<paymentMethod>
			<key>115</key>
			<value>AMEXRefund</value>
		</paymentMethod>
		<merchantTransactionID>hc-refund-20250604-134448</merchantTransactionID>
		<paymentID>fdf9cb39-875f-4971-8f46-29333fc14e2e</paymentID>
		<userID>hc20250530131855</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">1</amount>
		<creationType>
			<key>3</key>
			<value>Api</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>81f9d9cb-d18e-4ef8-8a32-de264c6165b5</id>
			<definition>
				<key>320</key>
				<value>RefundInitiated</value>
			</definition>
			<createdOn>2025-06-04T11:44:50.1729643Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">0.72</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyLongValuePair">
				<key>OriginalPaymentID</key>
				<value>2150878793</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>f75bf156-af8c-426e-977b-b1ce208737a0</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2150960442</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>114c9a7f-d137-45ae-a6e8-235fc6b5e4b1</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerCountry</key>
					<value>GB</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountFundingSource</key>
					<value>Credit</value>
				</detail>
				<detail xsi:type="keyBooleanValuePair">
					<key>FastFunds</key>
					<value>false</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>IssuerName</key>
					<value>AMEX UK CONSUMER CHARGE</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>MaskedNumber</key>
					<value>374251*****0000</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwnerToken</key>
					<value>bc55af0e-e033-4d63-9d69-361e854ccdf2</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryMonth</key>
					<value>12</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryYear</key>
					<value>2030</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>HolderName</key>
					<value>Sir Stenley Roise</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CardType</key>
					<value>AmericanExpress</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</initiatePaymentFromReferenceResponse>

Final states are being notified to the merchant:

Initial state

Final state

Description

RefundAccepted

Refunded

A refund was scheduled to be sent to provider Paysafe after the deposit transaction was captured with processor. In the success case, the refund will go to Refunded state and a notification will be sent to merchant.

RefundInitiated

Refunded

A refund was directly sent to provider Paysafe. After being queued there to be sent to the processor, eventually the refund will be successful and will be moved to Refunded state.

RefundAccepted

RefundErrorOccurred / RefundRefusedByProvider / RefundCommunicationErrorOccurred

When the scheduled refund is actually sent to provider, an error or a timeout can occur.

In the rare event of a timeout, the refund may or may not have been processed by the provider. A query will be executed at 11:00 am UTC and the final state will be notified to the merchant.

RefundInitiated

RefundRefusedByProvider

In rare cases, the refund is refused by provider.


Refund error codes:

Error codeDescriptionState
3402The requested Refund amount exceeds the remaining Settlement amount.RefundRefusedByProvider
3403You have already processed the maximum number of refunds allowed for this Settlement.RefundRefusedByProvider
3404The Settlement has already been fully refunded.RefundRefusedByProvider
3405The Settlement you are attempting to Refund has expired.RefundRefusedByProvider
3406The Settlement you are attempting to Refund has not been batched yet. There are no settled funds available to Refund.RefundRefusedByProvider
3407The Settlement referred to by the transaction response ID you provided cannot be found.RefundErrorOccurred
3408You have submitted an invalidly formatted response ID for the original Purchase or Settlement (= capture).RefundErrorOccurred
3412The Refund transaction you attempted was not permitted because your merchant account is in overdraft.RefundRefusedByProvider
3413The requested Refund amount exceeds the permissible Visa credit ratio.RefundRefusedByProvider
3414The Refund referred to by the transaction response ID you provided cannot be found.RefundErrorOccurred
3416The external processing gateway for which your merchant account is configured does not support partial Settlements.RefundErrorOccurred
3417here is already another request being processed on the transaction referenced for this request.RefundErrorOccurred
3418The external processing gateway for which your merchant account is configured does not support partial Credits.RefundErrorOccurred
3419This type of transaction cannot be refunded.RefundErrorOccurred
3420An error occurred while processing the purchase return authorization.RefundErrorOccurred
3421The purchase return authorization has been declined by the issuing bank.RefundRefusedByProvider
any other codeRefundErrorOccurred

Refund errors are also listed here @Paysafe.

State notification

Sample handlePaymentStateChangedNotification for state Refunded:

<?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>PaysafeCCDepositsShop</shopID>
		<paymentMethod>
			<key>89</key>
			<value>ECMC Refund</value>
		</paymentMethod>
		<merchantTransactionID>95a3bc63-6a71-4f91-850b-bedd40e1ff9d</merchantTransactionID>
		<paymentID>1ae5aaa4-41f1-4ce8-a217-6888ea219f8d</paymentID>
		<userID>98323aac-e68e-4984-a8c7-a6f50d</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">13.0200</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>f37522a8-436a-422b-96c6-c3d3ca750887</id>
			<definition>
				<key>125</key>
				<value>Refunded</value>
			</definition>
			<createdOn>2025-09-03T21:22:08.913</createdOn>
			<paymentStateDetails xsi:nil="true"/>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">9.4000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2152706375</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>1f658cdc-97f9-4dd5-b1b4-917c66cb26b5</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentID</key>
				<value>68ffe76a-deef-437d-8334-e4a193241e69</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentMerchantTransactionID</key>
				<value>14c8e754-c41b-4e72-81dd-812024d618d0</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentMethodID</key>
				<value>1</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalPaymentMethodName</key>
				<value>ECMC Deposit</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>2bfac59b-b72a-4344-b219-a3ea3f2445ec</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>MaskedNumber</key>
					<value>526600******8730</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>AccountOwnerToken</key>
					<value>c46d2e64-4fd6-4a67-9c58-a1cb4cc7477a</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryMonth</key>
					<value>12</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>ExpiryYear</key>
					<value>2099</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>HolderName</key>
					<value>John Dole</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>CardType</key>
					<value>Mastercard</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Testing

Authorization testing with provider

Authorization payments can be tested by passing request with specific payment accounts. The amounts are listed here.

Authorization testing with mock

Additional information on testing specific states such as AuthorizeCommunicationErrorOccurred will be provided on request.

Refund testing with mock

In order test specific test cases, the following mock parameters should be sent in the header of the request:

  • x-pxp-scenario-id (a GUID)
  • x-pxp-scenario-actions

Expected refund payment statex-pxp-scenario-actions value
RefundInitiatedRefundRes=status_PENDING
RefundRefusedByProvider (Error 3402; "The requested Refund amount exceeds the remaining Settlement amount")RefundRes=refused_Error_3402
RefundErrorOccurred (Unexpected status)RefundRes=UnexpectedStatus_UNKNOWN
RefundCommunicationErrorOccurredRefundRes= 500_ResponseWithEmptyContent

Updated 19 days ago