payouts

Test Payouts

The PayPal sandbox environment enables you to pass specific information in a request to trigger simulated positive and negative test scenarios. The simulated responses mimic actual API responses without calling downstream services. You can handle these responses in your code to manage your buyer’s experience.

Note: For easy API development and testing, download the latest version of Postman. Then download the Payouts Postman collection.

Permissions

Before you can trigger a simulation, you need to create a PayPal app and generate a valid access token.

Simulation methods

To trigger a simulation for the Payouts API, you can use a JSON pointer in the request payload or use a path parameter in the request URI.

Use a JSON pointer in the request payload

Trigger Test value Simulated error response
items[0]/note ERRPYO002 SENDER_EMAIL_UNCONFIRMED

Request

curl -X POST https://api.sandbox.paypal.com/v1/payments/payouts \
  -H "content-type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "sender_payout_header":
  {
    "sender_batch_id": "1524086406556",
    "email_subject": "This email is related to simulation"
  },
  "items": [
  {
    "recipient_type": "EMAIL",
    "receiver": "payouts-simulator-receiver@paypal.com",
    "note": "ERRPYO002",
    "sender_item_id": "15240864065560",
    "amount":
    {
      "currency": "USD",
      "value": "1.00"
    }
  }]
}'

Response

{
  "name": "SENDER_EMAIL_UNCONFIRMED",
  "message": "Authorization error occurred",
  "debug_id": "ca787bdf80d7a",
  "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/#errors"
}

Use a path parameter in the request URI

Trigger Test value Simulated error response
/v1/payments/payouts ERRPYO015 CLOSED_MARKET

Request

curl -X GET https://api.sandbox.paypal.com/v1/payments/payouts/ERRPYO015 \
  -H "content-type: application/json" \
  -H "Authorization: Bearer Access-Token"

Response

{
  "batch_header":
  {
    "payout_batch_id": "DQCP2UAJCBMNY",
    "batch_status": "SUCCESS",
    "time_created": "2017-08-21T11:22:33Z",
    "time_completed": "2017-08-21T11:22:54Z",
    "sender_payout_header":
    {
      "email_subject": "user test case"
    },
    "amount":
    {
      "currency": "USD",
      "value": "190.0"
    },
    "fees":
    {
      "currency": "USD",
      "value": "0.0"
    }
  },
  "items": [
  {
    "payout_item_id": "RWD4Y3H9VV8BA",
    "transaction_status": "FAILED",
    "payout_item_fee":
    {
      "currency": "USD",
      "value": "0.0"
    },
    "payout_batch_id": "DQCP2UAJCBMNY",
    "payout_item":
    {
      "recipient_type": "EMAIL",
      "amount":
      {
        "currency": "USD",
        "value": "190.0"
      },
      "note": "payout to  receiver",
      "receiver": "receiver@example.com",
      "sender_item_id": "MSI-2727"
    },
    "time_processed": "2017-08-21T11:22:44Z",
    "errors":
    {
      "name": "CLOSED_MARKET",
      "message": "Market closed and transaction is between 2 different countries",
      "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/#errors",
      "details": []
    },
    "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/RWD4Y3H9VV8BA",
      "rel": "item",
      "method": "GET",
      "encType": "application/json"
    }]
  }],
  "links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/payouts/DQCP2UAJCBMNY",
    "rel": "self",
    "method": "GET",
    "encType": "application/json"
  }]
}

Test values

Use the following test values to trigger positive and negative responses for these Payouts actions:

Note: Test values are case sensitive.

Create payout

Positive response test values

Use the JSON pointer method to simulate the following response at `POST v1/payments/payouts/.

Trigger Test value Simulated error response
items[0]/note POSPYO001 PAYLOAD WITH 201 RESPONSE CODE

Negative response test values

Use the JSON pointer method to simulate the following error responses at POST v1/payments/payouts.

Trigger Test value Simulated positive response
items[0]/note ERRPYO001 SENDER_RESTRICTED
items[0]/note ERRPYO002 SENDER_EMAIL_UNCONFIRMED
items[0]/note ERRPYO003 AUTHORIZATION_ERROR
items[0]/note ERRPYO005 INSUFFICIENT_FUNDS
items[0]/note ERRPYO006 INTERNAL_ERROR
items[0]/note ERRPYO010 MALFORMED_REQUEST_ERROR
items[0]/note ERRPYO011 REQUIRED_SCOPE_MISSING
items[0]/note ERRPYO012 SENDER_LOCKED
items[0]/note ERRPYO013 THIRD_PARTY_CALLS_FORBIDDEN
items[0]/note ERRPYO014 USER_BUSINESS_ERROR

Show payout

Positive response test values

Use the path parameter in the request URI method to simulate this response at GET v1/payments/payouts.

Trigger or test value Simulated positive response
/v1/payments/payouts/POSPYO002 PAYLOAD WITH 201 RESPONSE CODE

Negative response test values

Use the path parameter in the request URI method to simulate the following error responses at GET v1/payments/payouts.

Trigger or test value Simulated error response
/v1/payments/payouts/ERRPYO015 CLOSED_MARKET
/v1/payments/payouts/ERRPYO016 CURRENCY_COMPLIANCE
/v1/payments/payouts/ERRPYO017 CURRENCY_NOT_SUPPORTED_FOR_RECEIVER
/v1/payments/payouts/ERRPYO018 DUPLICATE_ITEM
/v1/payments/payouts/ERRPYO019 RECEIVER_ACCOUNT_LOCKED
/v1/payments/payouts/ERRPYO020 RECEIVER_COUNTRY_NOT_ALLOWED
/v1/payments/payouts/ERRPYO021 RECEIVER_UNCONFIRMED
/v1/payments/payouts/ERRPYO022 RECEIVER_UNREGISTERED
/v1/payments/payouts/ERRPYO023 RECEIVER_YOUTH_ACCOUNT
/v1/payments/payouts/ERRPYO024 RECEIVING_LIMIT_EXCEEDED
/v1/payments/payouts/ERRPYO025 REGULATORY_BLOCKED
/v1/payments/payouts/ERRPYO026 REGULATORY_PENDING
/v1/payments/payouts/ERRPYO027 RISK_DECLINE
/v1/payments/payouts/ERRPYO028 SELF_PAY_NOT_ALLOWED
/v1/payments/payouts/ERRPYO029 TRANSACTION_LIMIT_EXCEEDED
/v1/payments/payouts/ERRPYO030 UNDEFINED
/v1/payments/payouts/ERRPYO031 ZERO_AMOUNT

Cancel payout item

Positive response test values

Use the path parameter in the request URI method to simulate the following response at POST v1/payments/payouts-item/payouts_item_id/cancel.

Trigger or test value Simulated positive response
v1/payments/payouts-item/POSPOI002/cancel PAYLOAD WITH 200 RESPONSE CODE

Negative response test values

Use the path parameter in the request URI method to simulate the following error responses at POST v1/payments/payouts-item/payouts_item_id/cancel.

Trigger or test value Simulated positive response
v1/payments/payouts-item/ERRPOI001/cancel INVALID_RESOURCE_ID
v1/payments/payouts-item/ERRPOI002/cancel ITEM_INCORRECT_STATUS
/v1/payments/payouts-item/ERRPYO004/cancel BATCH_NOT_COMPLETED
/v1/payments/payouts-item/ERRPYO007/cancel ITEM_ALREADY_CANCELLED
/v1/payments/payouts-item/ERRPYO008/cancel ITEM_CANCELLATION_FAILED
/v1/payments/payouts-item/ERRPYO009/cancel ITEM_INCORRECT_STATUS

Show payout item details

Positive response test values

Use the path parameter in the request URI method to simulate the following response at GET v1/payments/payouts-item/payouts_item_id.

Trigger or test value Simulated positive response
v1/payments/payouts-item/POSPOI001 PAYLOAD WITH 200 RESPONSE CODE

Negative response test values

Use the path parameter in the request URI method to simulate the following error responses at GET v1/payments/payouts-item/payouts_item_id.

Trigger or test value Simulated error response
v1/payments/payouts-item/ERRPOI003 INVALID_RESOURCE_ID

Batch Processing

Positive response test values

Use the path parameter in the request URI method to simulate the following response at GET v1/payments/payouts/payout_batch_id.

Trigger or test value Simulated positive response
v1/payments/payouts/POSPYOB001 PAYLOAD WITH 200 RESPONSE CODE

Negative response test values

Use the path parameter in the request URI method to simulate the following error responses at GET v1/payments/payouts/payout_batch_id.

Trigger or test value Simulated error response
v1/payments/payouts/ERRPYOB001 SUCCESS
v1/payments/payouts/ERRPYOB002 PENDING
v1/payments/payouts/ERRPYOB003 DENIED
v1/payments/payouts/ERRPYOB004 PROCESSED

Use the JSON pointer method to simulate the following error responses at POST v1/payments/payouts.

Trigger Test value Simulated error response
items[0]/note ERRPYOB005 PENDING
Feedback