Test and go live

Use the PayPal sandbox environment to ensure your integration works as expected and meets all business and technical requirements before you go live.

To test your integration:

1. Test API calls with test values to simulate positive and negative responses
2. Test large-batch file transfer
3. Test AAC

Test API calls: use test values and simulate responses

To simulate Payouts API responses, inject the test values in the request payload or as a path parameter in the request URL. These methods allow you to trigger specific error responses without creating actual payouts.

Sample to inject test value in the request payload

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

Request

curl -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "sender_batch_header": 
    {
      "sender_batch_id": "1524086406556",
      "email_subject": "This email is related to simulation"
    },
    "items": [
      {
        "recipient_type": "EMAIL",
        "receiver": "[email protected]",
        "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/v1/#errors"
}

Sample to specify test value as path parameter

Path parameter	Test value	Simulated error response
/v1/payments/payouts/	ERRPYO015	CLOSED_MARKET

Request

curl -X GET https://api-m.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_batch_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",
      "errors": {
        "name": "CLOSED_MARKET",
        "message": "Payouts to this market are not supported.",
        "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch/v1/#errors",
        "details": []
      },
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/RWD4Y3H9VV8BA",
          "rel": "item",
          "method": "GET",
          "encType": "application/json"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/DQCP2UAJCBMNY",
      "rel": "self",
      "method": "GET",
      "encType": "application/json"
    }
  ]
}

Test values

Use predefined test values to simulate a variety of positive and negative payout responses. This section provides the test values and their respective simulated responses for each API endpoint.

Note: Test values are case sensitive.

Create payout

Use the provided test values in the request payload to simulate both positive and negative responses.

Endpoint: POST v1/payments/payouts/

Positive response test values

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

Negative response test values

Trigger	Test value	Simulated error 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	VALIDATION_ERROR
items[0]/note	ERRPYO011	REQUIRED_SCOPE_MISSING
items[0]/note	ERRPYO012	SENDER_LOCKED
items[0]/sender_batch_id	ERRPYO013	VALIDATION_ERROR FOR VENMO NOTE MISSING
items[0]/note	ERRPYO014	USER_BUSINESS_ERROR
items[0]/note	ERRPYO035	RATE_LIMIT_VALIDATION
items[0]/note	ERRPYO036	REQUEST_TIMEOUT_EXCEEDED
items[0]/note	ERRPYO037	SYNC_MODE_NOT_APPLICABLE
items[0]/note	ERRPYO038	NON_HOLDING_CURRENCY
items[0]/note	ERRPYO039	PREVIOUS_REQUEST_IN_PROGRESS
items[0]/note	ERRPYO040	CIP_NOT_VERIFIED

Show payout details

Use the provided test values as path parameters in the request URL to simulate both positive and negative responses.

Endpoint: GET v1/payments/payouts/

Positive response test values

Path parameter	Simulated response
/v1/payments/payouts/POSPYO002	PAYLOAD WITH 200 RESPONSE CODE

Negative response test values

Path parameter	Simulated error response
/v1/payments/payouts/ERRPYOB005	ACCOUNT_RESTRICTED
/v1/payments/payouts/ERRPYOB006	ACCOUNT_UNCONFIRMED_EMAIL
/v1/payments/payouts/ERRPYOB007	APPROVER_DENIED
/v1/payments/payouts/ERRPYOB008	GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK
/v1/payments/payouts/ERRPYOB009	GAMER_FAILED_FUNDING_SOURCE_CHECK
/v1/payments/payouts/ERRPYOB010	GAMING_INVALID_PAYMENT_FLOW
/v1/payments/payouts/ERRPYOB011	NON_HOLDING_CURRENCY
/v1/payments/payouts/ERRPYOB012	PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE
/v1/payments/payouts/ERRPYOB013	SENDER_STATE_RESTRICTED
/v1/payments/payouts/ERRPYOB014	SPENDING_LIMIT_EXCEEDED
/v1/payments/payouts/ERRPYOB015	TRANSACTION_DECLINED_BY_TRAVEL_RULE
/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
/v1/payments/payouts/ERRPYO032	INVALID_RESOURCE_ID
/v1/payments/payouts/ERRPYO033	INTERNAL_ERROR
/v1/payments/payouts/ERRPYO034	INVALID_EMAIL
/v1/payments/payouts/ERRPYO060	RECEIVER_ACCOUNT_LIMITATION

Cancel payout item

Use the provided test values as path parameters in the request URL to simulate both positive and negative responses.

Endpoint: POST v1/payments/payouts-item/payouts_item_id/cancel

Positive response test values

Path parameter	Simulated response
/v1/payments/payouts-item/POSPOI002/cancel	PAYLOAD WITH 200 RESPONSE

Negative response test values

Path parameter	Simulated error response
/v1/payments/payouts-item/ERRPOI001/cancel	INVALID_RESOURCE_ID
/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

Use the provided test values as path parameters in the request URL to simulate both positive and negative responses.

Endpoint: GET v1/payments/payouts-item/payouts_item_id

Positive response test values

Path parameter	Simulated response
/v1/payments/payouts-item/POSPOI001	PAYLOAD WITH 200 RESPONSE

Negative response test values

Path parameter	Simulated error response
/v1/payments/payouts-item/ERRPYO041	CLOSED_MARKET
/v1/payments/payouts-item/ERRPYO042	CURRENCY_COMPLIANCE
/v1/payments/payouts-item/ERRPYO043	CURRENCY_NOT_SUPPORTED_FOR_RECEIVER
/v1/payments/payouts-item/ERRPYO044	RECEIVER_ACCOUNT_LOCKED
/v1/payments/payouts-item/ERRPYO045	RECEIVER_COUNTRY_NOT_ALLOWED
/v1/payments/payouts-item/ERRPYO046	RECEIVER_UNCONFIRMED
/v1/payments/payouts-item/ERRPYO047	RECEIVER_UNREGISTERED
/v1/payments/payouts-item/ERRPYO048	RECEIVER_YOUTH_ACCOUNT
/v1/payments/payouts-item/ERRPYO049	RECEIVING_LIMIT_EXCEEDED
/v1/payments/payouts-item/ERRPYO050	REGULATORY_BLOCKED
/v1/payments/payouts-item/ERRPYO051	REGULATORY_PENDING
/v1/payments/payouts-item/ERRPYO052	RISK_DECLINE
/v1/payments/payouts-item/ERRPYO053	SELF_PAY_NOT_ALLOWED
/v1/payments/payouts-item/ERRPYO054	TRANSACTION_LIMIT_EXCEEDED
/v1/payments/payouts-item/ERRPYO055	UNDEFINED
/v1/payments/payouts-item/ERRPYO056	ZERO_AMOUNT
/v1/payments/payouts-item/ERRPYO057	INVALID_RESOURCE_ID
/v1/payments/payouts-item/ERRPYO058	INTERNAL_ERROR
/v1/payments/payouts-item/ERRPYO059	INVALID_EMAIL
/v1/payments/payouts-item/ERRPYO061	RECEIVER_ACCOUNT_LIMITATION
/v1/payments/payouts-items/ERRPYOB016	ACCOUNT_RESTRICTED
/v1/payments/payouts-items/ERRPYOB017	ACCOUNT_UNCONFIRMED_EMAIL
/v1/payments/payouts-items/ERRPYOB018	APPROVER_DENIED
/v1/payments/payouts-items/ERRPYOB019	GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK
/v1/payments/payouts-items/ERRPYOB020	GAMER_FAILED_FUNDING_SOURCE_CHECK
/v1/payments/payouts-items/ERRPYOB021	GAMING_INVALID_PAYMENT_FLOW
/v1/payments/payouts-items/ERRPYOB022	NON_HOLDING_CURRENCY
/v1/payments/payouts-items/ERRPYOB023	PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE
/v1/payments/payouts-items/ERRPYOB024	SENDER_STATE_RESTRICTED
/v1/payments/payouts-items/ERRPYOB025	SPENDING_LIMIT_EXCEEDED
/v1/payments/payouts-items/ERRPYOB026	TRANSACTION_DECLINED_BY_TRAVEL_RULE

Batch payout status

Use the provided test values as path parameters in the request URL to simulate both positive and negative responses.

Endpoint: GET v1/payments/payouts/payout_batch_id

Positive response test values

Path parameter	Simulated response
/v1/payments/payouts/ERRPYOB001	SUCCESS
/v1/payments/payouts/ERRPYOB002	PENDING
/v1/payments/payouts/ERRPYOB003	PROCESSING

Negative response test values

Path parameter	Simulated response
/v1/payments/payouts/ERRPYOB004	DENIED

Rate limit

The PayPal Payouts API enforces a maximum of 400 requests per minute per client (access token). If your integration exceeds this threshold, the API responds with an HTTP 429 Too Many Requests error, identified by the error name RATE_LIMIT_REACHED. This error is returned to your application (the merchant), not to payout recipients.

To test the rate limit in sandbox:

• Rapidly send multiple requests to the same endpoint in the sandbox environment.
• When the limit is exceeded, you will receive a response such as:

  {
    "name": "RATE_LIMIT_REACHED",
    "message": "Too many requests. Blocked due to rate limiting.",
    "debug_id": "xxxxxx",
    "information_link": "https://developer.paypal.com/docs/api/overview/#rate-limiting"
  }

• The HTTP status code for this response is 429.

If you encounter rate limit that disrupts your integration, contact Merchant Technical Support.

Best practices

• Use webhooks or Instant Payment Notification (IPN) to get real-time updates instead of checking the API repeatedly for status changes. For more information, see Webhook reference and Instant Payment Notification (IPN).
• Reuse OAuth 2.0 access tokens instead of generating a new token for each request. For details, see OAuth 2.0 authorization protocol.

Test large-batch file transfer

To test the large-batch file transfer in sandbox:

• Simulate file transfer to your Incoming folder on PayPal’s DropZone server via SFTP.
• Validate file name, file format, encoding, checksum, and file integrity.
• Test acknowledgment and result reports (ACK, NACK, DUPS, Part file, Out/interim, Final) in the Outgoing folder.
• Reconcile reports and correct any errors before you go live.

Test AAC

To test the Assisted Account Creation (AAC) integration in sandbox:

1. Select Log in with PayPal on your application.
2. Log in with your sandbox personal account credentials.
3. Approve the consent to share the customer details.
4. Use your sandbox business account to:
   • Verify that your application receives the authorization code.
   • Exchange the authorization code for an access token.
   • Use the access token to retrieve the customer details.
   • If it is a new customer, use the retrieved customer details to create a new customer account in your application.
   • Use the access token to make a payout request.
5. Confirm the movement of money into your sandbox personal account.

Go live

1. Before you go live, make sure your business account is approved for Payouts. If not, contact PayPal or work with your account manager to enable Payouts for your account.
2. Move your app to production.

References

• PayPal Payouts API Docs
• PayPal API Executor
• Rate limiting guidelines