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

Refunds may only be sent once the related card deposit has been captured and cleared with the processor (Moneris). Payments are being captured in the morning at 6 am EDT/EST, please do not send refunds before 11 am UTC.

Payments collected for capturing before 5 am EDT/EST are captured one hour later.
Payments can not be refunded before they have been captured and cleared with the processor.

Refund are also sent out to the processor only once per day at the same time.
On TEST1 captures and refunds are sent out once per hours.


After sending the initiatePaymentFromReference call, the merchant can expect either the state RefundInitiated or RefundRefusedByProvider. In rare cases (only due to configuration error) RefundErrorOccurred or in case of network issues - RefundCommunicationErrorOccurred. These are standard states for the refund operation.
A payment will be updated from RefundInitiated to Refunded every day at 11 am UTC.

Sample initiatePaymentFromReference request (AMEX 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>5c505b23-1ed0-4484-821b-d1dc5393a422</originalPaymentID>
	<merchantTransactionID>{{refundMerchantTransactionID}}</merchantTransactionID>
	<paymentMethodID>115</paymentMethodID>
	<amount currencyCode="cad">1</amount>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>My refund payment</value>
		</data>
	</specificPaymentData>
	<creationTypeID>3</creationTypeID>
</initiatePaymentFromReferenceRequest>

Sample initiatePaymentFromReference response (AMEX Refund):

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

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.

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 20 days ago