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