Card Withdrawals

The following method IDs are covered in this section:

ID	Name	Credit/Debit State	Reversal State
12	VISA Withdrawal	WithdrawnByProvider (20)
38	ECMC Withdrawal	WithdrawnByProvider (20)

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

📘
Supported cards
At the moment, Paysafe only supports Visa Withdrawals. Support for Mastercard Withdrawals will be added later.

Redirect Integration

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

Backend2Backend Integration

The following table contains the fields to be sent in the initiatePaymentRequest for card withdrawals:

key (value type, account type, required)	value
specificPaymentData.CardNumber (string,Cards, required)	PAN, e.g. 4111111111111111
HolderName (string,Cards, optional)	Cardholder name, e.g. John Doe
specificPaymentData.ExpiryMonth (string,Cards, required)	Expiration month of the card, e.g. 12
specificPaymentData.ExpiryYear (string,Cards, required)	Expiration year of the card, e.g. 2019
userData.User.FirstName (string, N/A, required)	First name of recipient/cardholder
userData.User.LastName (string, N/A, required)	Last name of recipient/cardholder

The following specificPaymentData details may be passed with the request:

key value	description
PaymentDescription	PaymentDescription
PaymentDescriptionLanguageKey
PaymentProviderID	ID 19

🚧
Address information is required for Visa Withdrawals to Canada
Where a recipient is located in Canada, please ensure the address object is also provided and populated with at least:

Street Address

Zip Code

Country

ExampleinitiatePaymentRequest for Card Withdrawal:

<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID>B2BTestMerchant</merchantID>
	<shopID>PaysafeCCDepositsShop</shopID>
	<merchantTransactionID>4b7d2d07-9fb2-4bea-8d48-c9a0def2cd33</merchantTransactionID>
	<paymentMethodID>12</paymentMethodID>
	<amount currencyCode="CAD">10.99</amount>
	<userID>5da8e6e0-4ad2-47c9-a39d-d501fd</userID>
	<userData>
		<username>5da8e6e0-4ad2-47c9-a39d-d501fd</username>
		<firstname>Tony</firstname>
		<lastname>Stark</lastname>
		<currencyCode xsi:nil="true" />
		<languageCode xsi:nil="true" />
		<email>[email protected]</email>
		<address>
			<street>Yonge Street</street>
			<houseName xsi:nil="true" />
			<houseNumber>45</houseNumber>
			<houseNumberExtension xsi:nil="true" />
			<postalCode>M4W 1J7</postalCode>
			<city>Toronto</city>
			<state xsi:nil="true" />
			<countryCode2>CA</countryCode2>
			<telephoneNumber xsi:nil="true" />
		</address>
		<identificationNumberType xsi:nil="true" />
		<drivingLicenseNumber xsi:nil="true" />
		<drivingLicenseIssuingState xsi:nil="true" />
		<globalUserID xsi:nil="true" />
		<nationality xsi:nil="true" />
		<identificationIssuingCountry xsi:nil="true" />
		<identificationNumberState xsi:nil="true" />
	</userData>
	<userIP>127.0.0.0</userIP>
	<userSessionID>f4038f70-9213-41f5-8362-72f2570f8f12</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="keyIntValuePair">
			<key>PaymentProviderID</key>
			<value>19</value>
		</data>
	</specificPaymentData>
	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>CardNumber</key>
				<value>4111111111111517</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>2099</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>HolderName</key>
				<value>Test Cardholder</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>
</initiatePaymentRequest>

ExampleinitiatePaymentResponse for Card Withdrawal (successful, WithdrawnByProvider):

<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>PaysafeCCDepositsShop</shopID>
		<paymentMethod>
			<key>12</key>
			<value>VISA Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>4b7d2d07-9fb2-4bea-8d48-c9a0def2cd33</merchantTransactionID>
		<paymentID>5e233636-7b8f-431e-a9de-fff2c6225c96</paymentID>
		<userID>5da8e6e0-4ad2-47c9-a39d-d501fd</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">10.99</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.0</userIP>
		<state>
			<id>11d278c1-1ba7-41cb-9cc6-0f58f585dfc5</id>
			<definition>
				<key>20</key>
				<value>WithdrawnByProvider</value>
			</definition>
			<createdOn>2025-06-17T11:46:14.2410407Z</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">7.94</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2151190025</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>abcea0d0-3f19-4990-a235-8e47d11ffa6d</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>aec4fa71-0e1c-4003-8d72-a863cf822f07</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>

📘
Errors
Some errors (3009, 3014, 3016, 3023, 3036, 3040, 3054, 3073, 4001, 3013) are interpreted as a refusal, and the payment is moved to state RefusedByProvider.
Details are saved in _ProviderResponseCode _value and _ProviderResponseMessage _value.
All other errors codes result in the payment being moved to state WithdrawErrorReportedByProvider.
Details are saved in _ProviderErrorResponseCode _and ProviderErrorResponseMessage.

ExampleinitiatePaymentResponse for Card Withdrawal (failed, RefusedByProvider):

Error code	Message
1007	An internal error occurred.
3006	You submitted an expired credit card number with your request.
3009	Your request has been declined by the issuing bank.
3014	Your request has been declined - the issuing bank has returned an unknown response. Contact the card holder's credit card company for further investigation.
3016	The bank has requested that you retrieve the card from the cardholder - it may be a lost or stolen card.
3017	You submitted an invalid credit card number with your request.
3023	Your request has been declined by the issuing bank due to its proprietary card activity regulations.
3036	Your request has been declined due to an invalid issuer.
3040	Your request has been declined because the request type is not permitted on the card.
3054	The transaction was declined due to suspected fraud.
3073	Your request has been declined due to closed customer account.
4001	The card number or email address associated with this transaction is in our negative database.
5031	The transaction you have submitted has already been processed.
3013	Your request has been declined by the issuing bank due to problems with the credit card account.
3037	Your request has been declined because it is invalid.
3041	Your request has been declined due to a timeout.

<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>PaysafeCCDepositsShop</shopID>
		<paymentMethod>
			<key>12</key>
			<value>VISA Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>41d80e37-72e8-4c1a-8ff2-03abd663dca2</merchantTransactionID>
		<paymentID>fef3dbab-ed2d-433a-aadb-1784f02c61eb</paymentID>
		<userID>0bc43a9e-379e-422a-8459-c315cd</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">10.99</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>d297d3bb-a655-474d-85ec-81e90638122f</id>
			<definition>
				<key>100</key>
				<value>RefusedByProvider</value>
			</definition>
			<createdOn>2025-06-17T11:48:59.8264206Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>3009</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseMessage</key>
					<value>Your request has been declined by the issuing bank.</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">7.94</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2151190028</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>ef62a32f-a243-427a-a0e0-fc8b405a9a5d</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>077786c6-6662-4f79-a26d-974f1413244f</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>

ExampleinitiatePaymentResponse for Card Withdrawal (failed, WithdrawErrorReportedByProvider):

<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>PaysafeCCDepositsShop</shopID>
		<paymentMethod>
			<key>12</key>
			<value>VISA Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>a21ca9a4-fc18-4962-a148-536115f28035</merchantTransactionID>
		<paymentID>08adbf59-ca3d-4a2f-ab54-5af920a6a4f7</paymentID>
		<userID>da4c6516-2ca4-46eb-9b4b-ca96a5</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">10.99</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.0</userIP>
		<state>
			<id>79f22715-ac31-4619-a90a-7f8e354294a6</id>
			<definition>
				<key>21</key>
				<value>WithdrawErrorReportedByProvider</value>
			</definition>
			<createdOn>2025-06-17T11:47:33.1099117Z</createdOn>
			<paymentStateDetails>
				<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>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">7.94</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>2151190027</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>66fec7e1-13b8-4462-851a-69c67111ee2e</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>6cc7dc14-c138-4986-a203-201f1f650650</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>

Notifications

ExamplehandlePaymentStateChangedNotificationRequest for VISA Withdrawal in Created state:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest
    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>KalixaAcceptDEMO</merchantID>
		<shopID>KalixaAcceptDEMO</shopID>
		<paymentMethod>
			<key>12</key>
			<value>VISA Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>20141215_8</merchantTransactionID>
		<paymentID>34927f83-1ba5-498e-8a88-d98f32448f52</paymentID>
		<userID>KalxiaTestUser_5</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">30</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>195.72.132.1</userIP>
		<state>
			<id>33fd269d-5700-4a1a-aa81-7d9d7989d9b4</id>
			<definition>
				<key>232</key>
				<value>Created</value>
			</definition>
			<createdOn>2014-12-15T12:30:50.9678178Z</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">30</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>207778</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>8d4dd05c-c280-49a5-8588-12e96329c359</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

📘
isExecuted = false
Note that when the withdrawal is created but not yet processed the isExecuted flag is equal to false.

ExamplehandlePaymentStateChangedNotificationRequest for VISA Withdrawal in WithdrawnByProvider state:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest
    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>KalixaAcceptDEMO</merchantID>
		<shopID>KalixaAcceptDEMO</shopID>
		<paymentMethod>
			<key>12</key>
			<value>VISA Withdrawal</value>
		</paymentMethod>
		<merchantTransactionID>20141215_8</merchantTransactionID>
		<paymentID>34927f83-1ba5-498e-8a88-d98f32448f52</paymentID>
		<userID>KalxiaTestUser_5</userID>
		<paymentProvider>
			<key>19</key>
			<value>Paysafe</value>
		</paymentProvider>
		<amount currencyCode="CAD">30.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>195.72.132.1</userIP>
		<state>
			<id>58b7abf2-8fbd-4817-96ff-01713e139e40</id>
			<definition>
				<key>20</key>
				<value>WithdrawnByProvider</value>
			</definition>
			<createdOn>2014-12-15T12:31:55.663</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">30.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>207778</value>
			</detail>
			<detail xsi:type="keyIntValuePair">
				<key>PaymentScoring</key>
				<value>713452</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>AuthorizationSequenceValue</key>
				<value>112874</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>8d4dd05c-c280-49a5-8588-12e96329c359</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Payment States for Card Withdrawal

State	Description
WithdrawnByProvider	Success state; payment has been executed
RefusedByProvider	Refusal state, payment was not accepted by provider
RefusedByPaymentScoring	Refusal state, Declined by PXP risk engine during risk checks
WithdrawCommunicationErrorOccurred	Error state; a communication error has occured. Please note that the payment can still be moved to a success state through the reconciliation
NotifyPaymentStateErrorReportedByMerchant	Error state; error reported by merchant during withdrawal approval.
DuplicatePaymentValidationFailed	Unsuccessful state; Duplication of payment.

Card Withdrawals - Paysafe

📘
Supported cards

Redirect Integration

Backend2Backend Integration

🚧
Address information is required for Visa Withdrawals to Canada

📘
Errors

Notifications

📘
isExecuted = false

Payment States for Card Withdrawal

📘Supported cards

Redirect Integration

Backend2Backend Integration

🚧Address information is required for Visa Withdrawals to Canada

📘Errors

Notifications

📘isExecuted = false

Payment States for Card Withdrawal

📘
Supported cards

🚧
Address information is required for Visa Withdrawals to Canada

📘
Errors

📘
isExecuted = false