Integration guidelines

Build your integration against the endpoints themselves, and against credentials and entities you created. The conventions those endpoints follow are on API conventions.

​

Build from the contract, not from generated code

Every tool that reads an OpenAPI document interprets parts of the standard in its own way, in particular composed schemas (oneOf, anyOf, allOf), nullability, additionalProperties, and enums. SDK generators and REST client importers share that behaviour, and fail the same two ways:

• The generated client or collection rejects a valid response, or refuses to serialize a valid request, because the model it derived is stricter than the contract.
• A backward-compatible minor release breaks it. Adding an attribute to a response, or returning 422 where the API used to return 400, is a minor change that the API guarantees is safe, and a strict generated model still fails on it.

Call the endpoints with your language’s HTTP client instead. Map only the fields you use and ignore the ones you do not, so your integration survives every minor release. A REST client stays the quickest way to explore an endpoint. Build the request by hand from its operation page. Use the downloadable specs for what a specification is good at: reading the contract, validating a payload against it, or diffing one version against the next.

​

Treat every sample value as fictitious

They show the shape of a payload. A request built from them fails authentication, or returns 404 Not Found on an entity that was never created. Use the credentials issued to your own Program, and entities you created yourself in the sandbox. The Try it console calls the sandbox, the only server the specification declares. Set its programRef variable to the one Paylead issued you before you run an operation; it defaults to changeme.

​

What’s next