Paypal Withdrawal - PayPal Payouts API

PayPal is a online wallet allowing customers to make instant financial transactions to other individuals and businesses world-wide.

This page describes the newer PayPal integration using the PayPal Payouts API.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
64	PayPalWithdrawal	WithdrawnByProvider (20)

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

The ‘AccountNumber’, ‘EmailAddress’ parameters should be taken from a deposit notification message. See example of the notification message in Paypal Express Checkout Deposit.

State diagram

Redirect Integration

Supported.

Backend2BackendIntegration

The following table contains the fields to be sent in the initiatePaymentRequest.specificPaymentData xml section:

key (value type, account type)	value
UserStatementText (string, optional)	User statement text. If not present, then depending on configuration this is Merchant´s holding name or merchant name or shop name.

The ‘AccountNumber’, ‘EmailAddress’ parameters should be taken from a deposit notification message. See example of the notification message in Paypal Express Checkout Deposit.

The following table contains the fields to be sent in the initiatePaymentRequest.specificPaymentAccountData xml section:

key (value type, account type, required)	value
EMailAddress (string, required)	The eMail address of the PayPal Express Checkout account.
AccountNumber (string, required)	The account number of PayPal Express Checkout account.

Possible payment states in initiatePaymentResponse (PayPal Payout API phase2):

Payment States	Description
PaymentScheduledForExecution (295)	Pending state; Withdrawal is queued for submittance to PayPal.

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<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>PaypalPayoutsShop</shopID>
	<merchantTransactionID>09d6db12-eb81-45c7-aed1-c0cd6137d014</merchantTransactionID>
	<paymentMethodID>64</paymentMethodID>
	<amount currencyCode="EUR">20</amount>
	<userID>72bd9156-5859-4b21-a384-633969</userID>
	<userData>
		<username>72bd9156-5859-4b21-a384-633969</username>
		<firstname xsi:nil="true" />
		<lastname xsi:nil="true" />
		<currencyCode xsi:nil="true" />
		<languageCode xsi:nil="true" />
		<email xsi:nil="true" />
		<address xsi:nil="true" />
		<gender>Male</gender>
		<identificationNumberType xsi:nil="true" />
		<drivingLicenseNumber xsi:nil="true" />
		<drivingLicenseIssuingState xsi:nil="true" />
	</userData>
	<userIP>127.0.0.1</userIP>
	<userSessionID>937f3b28-b6d9-4389-a515-a1153961d23f</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>UserStatementText</key>
			<value>d01Py28DM65g</value>
		</data>
	</specificPaymentData>
	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>AccountNumber</key>
				<value>G3WFKV42MC5RJ1</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>EmailAddress</key>
				<value>[email protected]</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentResponse (for state PaymentScheduledForExecution):

<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>PaypalPayoutsProviderTesting</shopID>
        <paymentMethod>
            <key>64</key>
            <value>PayPalWithdrawal</value>
        </paymentMethod>
        <merchantTransactionID>d16ad23a-f2ea-4f4c-937e-7d7eba59feaf</merchantTransactionID>
        <paymentID>36a3ad0a-eca9-4bb7-8f7b-7b61e688cc95</paymentID>
        <userID>d48693ca-e96e-4ca1-9e01-035645a79300</userID>
        <paymentProvider>
            <key>56</key>
            <value>PayPal</value>
        </paymentProvider>
        <amount currencyCode="USD">1</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>ef970162-a9b3-4d01-a02b-0c8e6e67edb2</id>
            <definition>
                <key>295</key>
                <value>PaymentScheduledForExecution</value>
            </definition>
            <createdOn>2022-03-30T14:54:59.37057Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">0.75</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1815187</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

After the payment goes to PaymentScheduledForExecution, the payment will reach the following states. The merchant will receive a handlePaymentStateChangedNotification for that state.

Payment States	Description
WithdrawnByProvider (2)	Final execution state. Consider the withdrawal has successful. Note: Withdrawal returns are possible.
RefusedByProvider (100)	The payment has been refused by provider.

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotificationRequest for Paypal Withdrawal in state WithdrawnByProvider:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<payment xmlns="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>PaypalPayoutsShop</shopID>
        <paymentMethod>
            <key>64</key>
            <value>PayPalWithdrawal</value>
        </paymentMethod>
        <merchantTransactionID>423dd72c-cb75-4434-9a73-852189574a7f</merchantTransactionID>
        <paymentID>10953a10-4bec-4cc4-a55e-25a313556537</paymentID>
        <userID>fc83b50c-4246-41fe-82ab-c013de</userID>
        <paymentProvider>
            <key>56</key>
            <value>PayPal</value>
        </paymentProvider>
        <amount currencyCode="EUR">11.1100</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>eb297f59-ab3d-49e0-ac7b-a736d0deaea7</id>
            <definition>
                <key>20</key>
                <value>WithdrawnByProvider</value>
            </definition>
            <createdOn>2022-05-18T15:35:22.917</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderStatusDescription</key>
                    <value>Test</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">11.1100</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>41799601</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>375817a0-94dc-474a-a96e-8d5591495f82</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>PaypalWithdrawalAckCode</key>
                <value>PENDING</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>PaypalWithdrawalPaymentStatus</key>
                <value>SUCCESS</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderOrderID</key>
                <value>83ae56d4-a390-4254-86a6-405434638bf4</value>
            </detail>
        </paymentDetails>
    </payment>
</handlePaymentStateChangedNotificationRequest>

The following payment details are passed on the notification for state WithdrawnByProvider:

PaymentDetail	Description
ProviderExternalID	PXP Financial´s transaction ID that is sent to PayPal
ProviderTransactionID	The transaction ID from PayPal, typically a value such as "0C413693MN970190K". Note: A transactionID is not returned if the receiver account is invalid. When that happens no transaction ID will be returned by PayPal because the transaction is rejected.
PayPalWithdrawalAckCode	Transaction status of payout batch. The value will be set to PENDING.
PayPalWithdrawalPaymentStatus	The transaction_status of the payout-item is stored in this detail. Possible values on state WithdrawnByProvider are: - SUCCESS (Funds have been credited to the recipient’s account) - UNCLAIMED (The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to the merchant´s account.) If the payment is initiated with the AccountNumber (=PayPal PayerID) in specificPaymentAccountData, then this payout-item status is highly unlikely.
ProviderOrderID	PayPal´s payout item ID.

The following payment state details are passed on the notification for state WithdrawnByProvider:

PaymentDetail	Description
ProviderStatusDescription	Summary field from the webhook notification from PayPal with the following text: - "A payout item has succeeded" (for event type SUCCESS) or - "A payout item is unclaimed" (for event type UNCLAIMED).

Example handlePaymentStateChangedNotificationRequest for Paypal Withdrawal in state RefusedByProvider:

<?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:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>PaypalPayoutsShop</shopID>
    <paymentMethod>
      <key>64</key>
      <value>PayPalWithdrawal</value>
    </paymentMethod>
    <merchantTransactionID>74a03e16-19c1-427f-99f5-b318b4671177</merchantTransactionID>
    <paymentID>89cfdb62-02ec-453f-b5cf-3ebd02ca1a48</paymentID>
    <userID>91904c00-2980-4cd6-bc22-fbf662</userID>
    <paymentProvider>
      <key>56</key>
      <value>PayPal</value>
    </paymentProvider>
    <amount currencyCode="GBP">1000.0000</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>14d0578e-c266-4278-bc8b-d7b334b64ee9</id>
      <definition>
        <key>100</key>
        <value>RefusedByProvider</value>
      </definition>
      <createdOn>2022-04-01T08:54:19.543</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>RECEIVER_COUNTRY_NOT_ALLOWED</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Receiver's address is in a non-receivable country or a PayPal zero country. Test Issue 01;Test Issue 02</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderStatusDescription</key>
          <value>Test</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">1156.8700</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>40961872</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>d96ca189-7121-45ab-85c0-f2a8ad6df5ff</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>PaypalWithdrawalAckCode</key>
        <value>PENDING</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>PaypalWithdrawalPaymentStatus</key>
        <value>FAILED</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderOrderID</key>
        <value>f5690d63-3298-4087-bf88-8a756c83f367</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

The following payment details are passed on the notification for state RefusedByProvider.

PaymentDetail	Description
ProviderExternalID	PXP Financial´s transaction ID that is sent to PayPal
ProviderTransactionID	The transaction ID from PayPal, typically a value such as "0C413693MN970190K". Note: A transactionID is not returned if the receiver account is invalid. When that happens no transaction ID will be returned because the transaction is rejected. A payment with a transactionID was failed due to some valid reason such as risk, locked/restricted account, etc, which is why a transactionID was returned by PayPal.
PaypalWithdrawalAckCode	Transaction status of payout batch. The value will be set to PENDING.
PayPalWithdrawalPaymentStatus	The transaction_status of the payout-item is stored in this detail. Possible values on state RefusedByProvider are: - FAILED (This payout request has failed, so funds were not deducted from the sender’s account.) - DENIED (The payout request was refused by PayPal.) - BLOCKED (The payout request has been blocked by PayPal).
ProviderOrderID	PayPal´s payout item ID.

The following payment state details are passed on the notification for state RefusedByProvider:

PaymentDetail	Description
ProviderStatusDescription	Summary field from the webhook notification from PayPal with the following text: - "A payout item has failed" (for event type FAILED) or - "A payout item was denied" (for event type DENIED) - "A payout item was blocked" (for event type BLOCKED)
ProviderResponseCode	An error name that was returned by PayPal, e.g. "GAMER_FAILED_FUNDING_SOURCE_CHECK"
ProviderResponseMessage	A error message that was returned by PayPal, eg. "The funding source for this gamer is ineligible to make payments."

📘
PayPal error
For more information on PayPal payout errors see here, then click on "Payouts" on the left, and select "Error Messages".

State diagram

Redirect Integration

Backend2BackendIntegration

Notifications

📘PayPal error

📘
PayPal error