API Response Format
Understand the structure of Notch Pay API responses
Understanding the structure of Notch Pay API responses is essential for properly integrating with our API. This guide explains the standard response format, common fields, and how to interpret different types of responses.
Standard Response Format
All Notch Pay API responses follow a consistent JSON format:
Response Properties
Property | Type | Description |
---|---|---|
code | number | HTTP status code indicating the result of the request |
status | string | Text representation of the HTTP status code |
message | string | Human-readable description of the response |
data | object/array | The main response data (varies by endpoint) |
Success Responses
Single Resource Response
When retrieving a single resource (like a payment or customer), the response typically looks like this:
Collection Response
When retrieving a collection of resources (like a list of payments), the response includes pagination information:
Pagination Properties
Property | Type | Description |
---|---|---|
totals | number | Total number of items across all pages |
last_page | number | Number of the last page |
current_page | number | Number of the current page |
selected | number | Number of items on the current page |
items | array | Array of items on the current page |
Creation Response
When creating a new resource, the response typically includes the created resource and a 201 status code:
Update Response
When updating a resource, the response typically includes the updated resource:
Deletion Response
When deleting a resource, the response typically confirms the deletion:
Error Responses
When an error occurs, the response includes information about what went wrong:
For more information about error responses, see the Error Handling guide.
Response Formats for Specific Endpoints
Payments API
Create Payment
Retrieve Payment
Transfers API
Create Transfer
Customers API
Create Customer
Response Fields
Common Fields
These fields appear in most resource objects:
Field | Type | Description |
---|---|---|
id | string | Unique identifier for the resource |
created_at | string | ISO 8601 timestamp when the resource was created |
updated_at | string | ISO 8601 timestamp when the resource was last updated |
Timestamps
All timestamps in Notch Pay API responses are in ISO 8601 format with UTC timezone:
Example: 2023-01-01T12:00:00Z
Handling Responses in Different Programming Languages
JavaScript
PHP
Python
Best Practices
-
Check the Status Code: Always check the
code
field to determine if the request was successful. -
Handle Pagination: When working with collection endpoints, implement pagination to retrieve all results.
- Parse Timestamps: Convert timestamp strings to Date objects for easier manipulation.
- Handle Empty Collections: When retrieving collections, check if the
items
array is empty.
- Extract Relevant Data: Only extract the data you need from the response to simplify your code.
Next Steps
- API Reference - Explore the complete API documentation
- Authentication - Learn about authentication methods
- Error Handling - Understand how to handle API errors