API Essentials

The Papaya Global Workforce Payments API is organized around REST. The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

HTTP Methods

The Workforce Payments API uses HTTP methods to perform operations on resources. The most commonly used methods are:

Data Types

The Workforce Payments API consistently utilizes data types and formats.

Data Types	Description	Sample Use Cases	Sample Values
Dates	Dates are represented in the YYYY-MM-DD format without any time or timezone information	date_of_birth	1970-01-01
Time Stamps	The format for representing date and time with timezone information is YYYY-MM-DDTHH:mm:ssZ.	start_date end_date date	2024-03-02T09:09:51.508859936Z
Country Codes	Country codes in the ISO 3166-2 standard consist of two letters.	address_country account_country	AU
Currency Codes	Currency code in ISO 4217 with three letters.	currency	AUD

Response Codes

The Papaya Global Workforce Payments API utilizes standard HTTP response codes to communicate the outcome of an API request. A status code falling within the 2xx range signifies success, while codes in the 4xx range point to errors caused by the input data (e.g., invalid parameters or missing information). Conversely, status codes in the 5xx range signal a server-related error.

HTTP Status Codes	Response Indication	Description
200	OK	The request has been successfully handled.
201	Created	The request has been successfully processed, resulting in the creation of a new resource.
202	Accepted	The request has been approved for processing, however, the processing is still ongoing. The request's completion is uncertain until the processing is finalized.
400	Bad Request	The request lacks essential parameters, is in an improper format, or did not pass another validation test.
401	Unauthorized	The authentication token has been provided and is in a valid state.
402	Request Failed	Financial transaction was declined. Parameters were valid but request failed.
403	Forbidden	The web server acknowledges the request but declines to authorize it due to permission issues.
404	Not Found	The specified endpoint is not available.
405	Method Not Allowed	The HTTP request sent by your browser is not permitted for the specified resource or URL.
429	Too Many Requests	Indicates the user has sent too many requests in a given amount of time ("rate limiting").
500	Internal Server Error	The server has encountered an unforeseen circumstance that has hindered its ability to fulfill the request.

Errors Response

The body of the Global Workforce Payments API error response typically includes the following fields:

Attribute	Type	Description
Error	String	Represents the high-level error message.
Description	String	Provides a detailed description of the error.
Error Code	String	Specifies the HTTP error code or any custom error code associated with the error.
Sub Code	String	Optionally provides additional sub-codes for categorizing specific types of errors under the same high-level error.

Response Examples with Sub Code

{
  "error": "Error Message",
  "description": "Failed calling service",
  "error_code": "Error Code",
  "sub_code": "Sub Code",
  "error_info": { // Example for HTTP error
    "timestamp": "Timestamp",
    "status": "HTTP Status Code",
    "error": "Error Message",
    "path": "Request Path"
  }
}

{
  "error": "not_found",
  "description": "Wallet not found",
  "error_code": 404,
  "sub_code": 1000,
  "error_info": {
    "timestamp": "2024-03-04T07:55:43.543Z",
    "status": 404,
    "error": "The specified wallet ID does not exist.",
    "path": "/v1/wallet"
  }
}

Response Examples without Sub Code

{
  "error": "Error Message",
  "description": "Failed calling service",
  "error_code": "Error Code"

{
  "error_code": 401, 
  "error": "Unauthorized", 
  "description": "Authorization failed. The server could not verify your credentials. Please check your configuration and try again."
}

Rate Limits

To ensure a responsive and fair usage environment for all our users, we enforce rate limits on our REST API. Each endpoint has an assigned request limit carefully calibrated to balance frequent access with system integrity and equitable resource distribution.

• Standard Rate Limit: Our standard rate limit is 500 requests per minute per authenticated user. This applies to most endpoints unless otherwise specified.

The rate limit is determined by the number of calls made, not the number of actions taken. Therefore, calling the bulk endpoints enables more actions to be performed within the rate limit.

• Extended Limits: Higher rate limits may be available depending on your subscription tier or upon request for specific use cases that require more frequent access.

• Headers and Feedback: Every API response includes HTTP headers that provide your current rate limit status:

  • X-RateLimit-Limit: The maximum number of requests permitted within the window.

  • X-RateLimit-Remaining: The remaining number of requests within the current rate limit window.

  • X-Ratelimit-Used: The total amount of requests you have made during the current rate limit interval.

  • X-RateLimit-Reset: When the current rate limit window resets in UTC epoch seconds.

  • X-Ratelimit-Resource: The resource against which the request was counted for rate-limiting purposes.

• Best Practices: We recommend implementing retry logic with exponential backoff and respecting the Retry-After header where applicable. This approach aids in efficiently utilizing rate limits and reduces the likelihood of encountering limits.

• Exceeding Limits: Attempts to exceed rate limits will result in a 429 Too Many Requests response. Continuous overage may lead to temporary or permanent suspension of API access. We urge all users to architect their applications to handle such responses gracefully.

• Changes and Notifications: Rate limits are subject to change based on system performance and user demand. All changes will be communicated through our developer channels and API change log.