Introduction
The technical reference section covers Invoice Service ledger API's and record descriptions for available reports and files.
Invoice Service through REST API
Access security requirements specifications
Access API resource specifications used for PayEx Invoice Service.
Reports, Accounting and Settlement
Access file reference for the bookkeeping data, settlement and leger report (available in Output-API)
REST-full pattern guidance
The resources follows REST-full patterns including hyper-media links, we use hyper-media and backend-for-frontend principles to impose business rules and reduce duplication of business logic. Errors uses HTTP friendly status codes as well as detailed "problem+json" responses.
Route segments
Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}
| Route segment | Description |
|---|---|
| Subdomain | which subdomain under "ledger" to call, (customer / invoice / account etc.) |
| LedgerNumber | The ledger identifier/number at PayEx |
| resource1Id | Identifier of resource1 |
| resource2Id | identifier of resource2, subresource to resource1 |
| resource3Id | identifier of resource3, subresource to resource2 |
Basic resources
Basic resources uses the common HTTP patterns for GET, POST, PUT, PATCH, DELETE.
Requests without specific resource identifier - f.ex. /ledger/customer/v1/XXX/customers
- HTTP GET - Returns a list of resources
- HTTP POST - Creates a new resource
Requests with specific resource identifier - f.ex. /ledger/customer/v1/XXX/customers/1234568
- HTTP GET - Returns a specific resource
- HTTP PUT - Updates a specific resource
- HTTP PATCH - Partially updates a specific resource
- HTTP DELETE - Deletes a specific resource
Operation resources
Functions that cannot be mapped directly to resources are called "Operation Resources" they only support HTTP POST.
Requests without specific resource identifier operates on the list
- HTTP POST - f.ex. /ledger/customer/v1/XXX/customers/generate-summary - Generates a summary
Requests with specific resource identifier operates on a resource
- HTTP POST - f.ex. /ledger/customer/v1/XXX/customers/1234568/initiates-termination - Starts termination of an account
Hyper-media response
The response will include a list of operations that is possible to perform. Below is an example when a HTTP-GET Request is issued to retrieve information on an account. The response includes an "operations" property with a list of possible possible operations. The list of operations returned only contains business-rule and access-control validated operations. In the sample below the only allowed way to interact with the resource is to issue "patch" requests to modify fields. Different states as well as access permissions on the resource affect which operations are returned.
"@id": "/ledger/customer/v1/501/customers/1234567", //Resource identifier
//Fields...
"operations" : [
{
"rel" : "partial-update",
"method" : "patch",
"href" : "/ledger/customer/v1/501/customers/1234567"
}
]
}
Properties used for idempotency
For operations that are idempotent, clients can make the same call multiple times while giving the same results. In other words, multiple identical requests have the same effect as making a single request.
This can be used to re-run failed requests. For requests that, for example, fail due to timeout, there is a possibility that it has been executed at PayEx. In such cases, the request can be run again without duplicates.
This is based on the same request being sent again. In some cases it is enough that certain references / identifiers are the same, in which case these are marked in the API spec
Problems
Errors uses HTTP friendly status codes as well as detailed "problem+json" responses. All errors that can be avoided by the client is in the "HTTP status 4XX" ragne, all errors that must be fixed by payex is in the "HTTP status 5XX" range. All errors contains an instance-id, the instance-id should be provided in support questions to simplify the support process.
If an error occur or any validation failed, a "problem" response will be returned.
Below is a list of problems that can occur:
HttpStatus 401 Unauthorized
- Token expired
- Token invalid
- SellerNumber does not match token
- CompanyNumber does not match token
HttpStatus 400 Error
- Validation: Argument required
- Validation: Invalid value
HttpStatus 422 Unprocessable entity
- Authorization declined
HttpStatus 409 Conflict
- Invoice already authorized
- Duplicate InvoiceNumber
- Authorization is cancelled
- Authorization already captured
- Authorization has expired
- Insufficient debited amount XXX
HttpStatus 501 NotImplemented
- CompanyNumber XXX not configured
- SellerNumber XXX not configured at PayEx
- CompanyNumber XXX missing configuration
HttpStatus 404 NotFound
- Authorization not found
Sample
Below is an example of a problem that will be returned if buyer.nationalConsumerIdentifier.value is not valid in the authorization post request.
Content-Type: application/problem+json
{
"Type": "ledger/customer/v1/problems/validation",
"Title": "A validation error occurred",
"Status": 400,
"Instance": "dd07e588-70c8-4b27-95f5-020cc2968c06",
"Detail": "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
"Problems": [
{
"customer.nationalConsumerIdentifier.value": "Not a valid SE nationalConsumerIdentifier"
}
]
}