PayEx Developer Portal

* [[Onboarding>>doc:.credit-account-onboardings.WebHome]] - Functions to list possible account types, onboard/create new accounts including the signing process

22

* [[Account >>doc:.credit-account.WebHome]]- Functions to view details and interact with a specific account

23

24

=== API resources overview ===

25

26

27

=== REST-full pattern guidance ===

28

29

(% class="lead" %)

30

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 ====

(% class="box" %)

(((

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

39

)))

40

41

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.

42

//api.payex.com/ledger/**{Subdomain}**/v1/(% data-stringify-type="bold" %)**{LedgerNumber}**(%%)/resource1/(% data-stringify-type="bold" %)**{resource1Id}**(%%)/resource2/(% data-stringify-type="bold" %)**{resource2Id}**(%%)/resource3/(% data-stringify-type="bold" %)**{resource3Id}**//

43

44

|=(% style="width: 182px;" %)Route segment|=(% style="width: 3212px;" %)Description

45

|(% style="width:182px" %)Subdomain|(% style="width:3212px" %)which subdomain under "ledger" to call, (credit-account / credit-account-acquiring etc.)

46

|(% style="width:182px" %)LedgerNumber|(% style="width:3212px" %)The ledger identifier/number at PayEx

47

|(% style="width:182px" %)resource1Id|(% style="width:3212px" %)Identifier of resource1

48

|(% style="width:182px" %)resource2Id|(% style="width:3212px" %)identifier of resource2, subresource to resource1

49

|(% style="width:182px" %)resource3Id|(% style="width:3212px" %)identifier of resource3, subresource to resource2

50

51

==== Basic resources ====

(% class="box" %)

(((

//Basic resources uses the common HTTP patterns for GET, POST, PUT, PATCH, DELETE.//

56

)))

57

58

Requests __**without**__ specific resource identifier - f.ex. /ledger/credit-account/v1/XXX/accounts

59

60

* HTTP GET - Returns a list of resources

61

* HTTP POST - Creates a new resource

62

63

Requests __**with**__ specific //__resource identifier__// - f.ex. /ledger/credit-account/v1/XXX/accounts///__1234568__//

64

65

* HTTP GET - Returns a specific resource

66

* HTTP PUT - Updates a specific resource

67

* HTTP PATCH - Partially updates a specific resource

68

* HTTP DELETE - Deletes a specific resource

69

70

==== Operation resources ====

(% class="box" %)

(((

//Functions that cannot be mapped directly to resources are called "Operation Resources" they only support HTTP POST//.

75

)))

76

77

Requests __**without**__ specific resource identifier operates on the list

78

79

* HTTP POST - f.ex. /ledger/credit-account/v1/XXX/accounts/generate-summary - Generates a summary

80

81

Requests __**with**__ specific resource identifier operates on a resource

82

83

* HTTP POST - f.ex. /ledger/credit-account/v1/XXX/accounts/1234568/initiates-termination - Starts termination of an account

84

85

==== Hyper-media response ====

86

87

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.

88

89

90

{{code language="javascript" title="**Hyper-media response sample**"}}

91

{

92

"@id": "/ledger/credit-account/v1/501/accounts/1234567", //Resource identifier

//Fields...

"operations" : [

{

"rel" : "partial-update",

97

"method" : "patch",

98

"href" : "/ledger/credit-account-onboardings/v1/501/accounts/123456"

}

]

}

(% class="box successmessage" %)

106

(((

107

**Tip:** As an implementing consumer of the api **operations** should be taken into consideration rather than trying to determine possible operation based on other basic resource properties. By following this tip we: minimize duplication of business logic, simplify maintenance when business rules change, have a clear separation of concerns.

108

)))

109

110

==== Properties used for idempotency ====

111

112

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.

113

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.

114

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 ===

(% class="box" %)

(((

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.

127

Below is a list of problems that can occur:

128

129

**HttpStatus 401 Unauthorized**

130