Draft:
Integrate to PayEx Account transaction API
Changelog
Introduction
The account-transaction API is handle payment flows for credit accounts for retail finance scenarios. The api contains redirect scenarios for account onboarding and upgrades.
1. Authorization-capture-orders
Get an existing authorization-capture-orders. The authorization-capture-orders, is used when adding transactions to users account when user is pre identified.
1.1 Get specific Authorization-capture-order
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Success Example
Response for a successful authorization and capture
Content-Type: application/json
{
"status": "processed",
"callbackBody": {
"success": {
"authorization": "/ledger/account-transaction/v1/XXX/authorizations/{authorizationId}"
}
},
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerReferenceId": "abc-87465123",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.00,
"pointOfSale": "Test shop",
"operations": []
}
Error Example
Response for a unsuccessful authorization or capture
Content-Type: application/json
{
"status": "processed",
"callbackBody": {
"fail": {
"type": "ledger/account-transaction/v1/problems/validation",
"title": "Not found",
"status": 404,
"detail": "A validation error occurred. Please fix the problems mentioned in the problems property below.",
"instance": "215d4206-ca35-4f43-85ad-169c8f6d4ec1"
}
},
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerReferenceId": "abc-87465123",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.000,
"pointOfSale": "Test shop",
"operations": []
}
1.2 Create Authorization-capture-order
Create authorization-capture-orders is used to add transaction when user is pre identified.
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
{
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.00,
"pointOfSale": "Test shop"
}
Request object specification
| Property | Data type | Format | Required | Description |
|---|---|---|---|---|
| captureId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | Identifier of the capture, must be unique for all types of captures within the ledger |
| authorizationId | number | Type: int64 | Yes | Identifier of the authorization, must be unique for all types of authorizations within the ledger |
| accountNo | string | Yes | The identifier of the account | |
| callbackUrl | string | No | If callback should be done on status change, it is done to the callback url. If empty no callback is done. | |
| sellerNo | string | Yes | The seller identifier at payex | |
| sellerReferenceId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries. |
| sellerTransactionId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | The sellers identifier of the capture/transaction, usually the receipt reference |
| authenticationMethod | string | Yes | Authentication method used to identify the user. Possible values 1FA (one factor),2FA (two factor) ,3FA (three factor) | |
| currency | string |
| Yes | |
| amount | number | Type: double Max: 100000000 Min: 0 | Yes | The amount of the authorization capture order, can't have more than 2 decimal places. |
| pointOfSale | string | No | Trade name of the point of sale. Will be displayed to end customer. Only use if agreed with provider of the API. |
Content-Type: application/json
{
"status": "pending",
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.00,
"pointOfSale": "Test shop",
"@id": "/ledger/account-transaction/v1/xxx/authorization-capture-orders/123456",
"operations": []
}
Response object specification
| Property | Data type | Format | Description |
|---|---|---|---|
| @id | string | Uri identifier of the current resource | |
| captureId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Identifier of the capture, must be unique for all types of captures within the ledger |
| authorizationId | number | Type: int64 | Identifier of the authorization, must be unique for all types of authorizations within the ledger |
| accountNo | string | The identifier of the account | |
| callbackUrl | string | If callback should be done on status change, it is done to the callback url. If empty no callback is done. | |
| sellerNo | string | The seller identifier at payex | |
| sellerReferenceId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries. |
| sellerTransactionId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | The sellers identifier of the capture/transaction, usually the receipt reference |
| authenticationMethod | string | Authentication method used to identify the user. Possible values 1FA (one factor),2FA (two factor) ,3FA (three factor) | |
| currency | string |
| |
| amount | number | Type: double Max: 100000000 Min: 0 | The amount of the authorization capture order, can't have more than 2 decimal places. |
| pointOfSale | string | Trade name of the point of sale. Will be displayed to end customer. Only use if agreed with provider of the API. | |
| status | string |
| |
| callbackBody | object | ||
| success | object | ||
| authorization | string | Uri to the created authorizarion. | |
| fail | dynamic | Problem definition of the authorization capture transaction. See problem section. | |
| operations | array | List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response |
2. Authorizations
Get an existing authorization.
2.1 Get specific Authorization
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Get authorization
Content-Type: application/json
{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-01",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"operations": [
{
"rel": "add-reversal",
"method": "POST",
"href": "/ledger/account-transaction/v1/xxx/authorizations/456789/reversals"
},
{
"rel": "add-capture",
"method": "POST",
"href": "/ledger/account-transaction/v1/xxx/authorizations/456789/captures"
},
{
"rel": "add-cancellation",
"method": "POST",
"href": "/ledger/account-transaction/v1/xxx/authorizations/456789/cancellations"
}
]
}
Possible problems
| Http status | Problem type | Description |
|---|---|---|
| 404 | not-found | Found no authorization for provided id on this ledger |
| 409 | invalid-account-usage | Provided PreAuthorization is invalid for this kind of authorization |
| 500 | fatal | Unexpected error, logs may give details about the problem |
Response object specification
| Property | Data type | Format | Description |
|---|---|---|---|
| @id | string | Uri identifier of the current resource | |
| authorizationId | number | Type: int64 | Identifier of the authorization, must be unique for all types of authorizations within the ledger |
| sellerNo | string | The seller identifier at payex | |
| validToDate | string | The authorization is valid for captures until this date. Format 'YYYY-MM-DD' | |
| authorizationAmount | number | Type: double Max: 100000000 Min: 0 | The original authorized amount |
| remainingAmount | number | Type: double | The remaining amount on the authorization available for capture |
| currency | string |
| |
| status | string |
| |
| operations | array | List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response |
3. Reversals
3.1 Create Reversal
For reversing a specific capture
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
{
"reversalId": "654321",
"currency": "SEK",
"amount": 512.00,
"sellerTransactionId": "753159"
}
Request object specification
| Property | Data type | Format | Required | Description |
|---|---|---|---|---|
| reversalId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | Identifier of the reversal, must be unique for all types of captures within the ledger |
| currency | string |
| Yes | |
| amount | number | Type: double Max: 100000000 Min: 0 | Yes | Amount to reverse |
| sellerTransactionId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | The sellers identifier of the reversal transaction, usually the receipt reference |
Content-Type: application/json
{
}
Possible problems
| Http status | Problem type | Description |
|---|---|---|
| 404 | not-found | Resource missing, may have been created on different ledger or have expired |
| 400 | validation | Validation error, response should describe the problem/s |
| 409 | currency-not-supported | Provided Currency does not match the authorization currency |
| 409 | invalid-amount | Provided Reversal Amount is invalid, likely larger than remaining captured amount |
| 409 | identifier-already-in-use | Provided Identifier is already in use, probably ReversalTransactionId is not unique |
| 409 | invalid-account-usage | Provided Authorization is invalid for this kind of reversal |
| 500 | fatal | Unexpected error, logs may give details about the problem |
Problems
All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.
Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
Example
Content-Type: application/problem+json
{
"Type" : "ledger/{domain}/v1/problems/validation",
"Title" : "A validation error occurred",
"Status" : 400,
"Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
"Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
"Problems" :
{
"amount" : [
"Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
]
}
}
1. Authorization-capture-orders
Get an existing authorization-capture-orders. The authorization-capture-orders, is used when adding transactions to users account when user is pre identified.
1.1 Get specific Authorization-capture-order
Request
GET /ledger/account-transaction/v1/{ownerNo}/authorization-capture-orders/{captureId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Success Example
Response for a successful authorization and capture
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "processed",
"callbackBody": {
"success": {
"authorization": "/ledger/account-transaction/v1/XXX/authorizations/{authorizationId}"
}
},
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerReferenceId": "abc-87465123",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.00,
"pointOfSale": "Test shop",
"operations": []
}
Error Example
Response for a unsuccessful authorization or capture
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "processed",
"callbackBody": {
"fail": {
"type": "ledger/account-transaction/v1/problems/validation",
"title": "Not found",
"status": 404,
"detail": "A validation error occurred. Please fix the problems mentioned in the problems property below.",
"instance": "215d4206-ca35-4f43-85ad-169c8f6d4ec1"
}
},
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerReferenceId": "abc-87465123",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.000,
"pointOfSale": "Test shop",
"operations": []
}
1.2 Create Authorization-capture-order
Create authorization-capture-orders is used to add transaction when user is pre identified.
Request
POST /ledger/account-transaction/v1/{ownerNo}/authorization-capture-orders HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
{
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.00,
"pointOfSale": "Test shop"
}
Request object specification
| Property | Data type | Format | Required | Description |
|---|---|---|---|---|
| captureId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | Identifier of the capture, must be unique for all types of captures within the ledger |
| authorizationId | number | Type: int64 | Yes | Identifier of the authorization, must be unique for all types of authorizations within the ledger |
| accountNo | string | Yes | The identifier of the account | |
| callbackUrl | string | No | If callback should be done on status change, it is done to the callback url. If empty no callback is done. | |
| sellerNo | string | Yes | The seller identifier at payex | |
| sellerReferenceId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries. |
| sellerTransactionId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | The sellers identifier of the capture/transaction, usually the receipt reference |
| authenticationMethod | string | Yes | Authentication method used to identify the user. Possible values 1FA (one factor),2FA (two factor) ,3FA (three factor) | |
| currency | string |
| Yes | |
| amount | number | Type: double Max: 100000000 Min: 0 | Yes | The amount of the authorization capture order, can't have more than 2 decimal places. |
| pointOfSale | string | No | Trade name of the point of sale. Will be displayed to end customer. Only use if agreed with provider of the API. |
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"status": "pending",
"captureId": "123456",
"authorizationId": 123456789,
"accountNo": "1234",
"callbackUrl": "https://my.com/callback?543245892u59",
"sellerTransactionId": "654789312",
"authenticationMethod": "2FA",
"currency": "SEK",
"amount": 50.00,
"pointOfSale": "Test shop",
"@id": "/ledger/account-transaction/v1/xxx/authorization-capture-orders/123456",
"operations": []
}
Response object specification
| Property | Data type | Format | Description |
|---|---|---|---|
| @id | string | Uri identifier of the current resource | |
| captureId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Identifier of the capture, must be unique for all types of captures within the ledger |
| authorizationId | number | Type: int64 | Identifier of the authorization, must be unique for all types of authorizations within the ledger |
| accountNo | string | The identifier of the account | |
| callbackUrl | string | If callback should be done on status change, it is done to the callback url. If empty no callback is done. | |
| sellerNo | string | The seller identifier at payex | |
| sellerReferenceId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries. |
| sellerTransactionId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | The sellers identifier of the capture/transaction, usually the receipt reference |
| authenticationMethod | string | Authentication method used to identify the user. Possible values 1FA (one factor),2FA (two factor) ,3FA (three factor) | |
| currency | string |
| |
| amount | number | Type: double Max: 100000000 Min: 0 | The amount of the authorization capture order, can't have more than 2 decimal places. |
| pointOfSale | string | Trade name of the point of sale. Will be displayed to end customer. Only use if agreed with provider of the API. | |
| status | string |
| |
| callbackBody | object | ||
| success | object | ||
| authorization | string | Uri to the created authorizarion. | |
| fail | dynamic | Problem definition of the authorization capture transaction. See problem section. | |
| operations | array | List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response |
2. Authorizations
Get an existing authorization.
2.1 Get specific Authorization
Request
GET /ledger/account-transaction/v1/{ownerNo}/authorizations/{authorizationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Get authorization
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-01",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"operations": [
{
"rel": "add-reversal",
"method": "POST",
"href": "/ledger/account-transaction/v1/xxx/authorizations/456789/reversals"
},
{
"rel": "add-capture",
"method": "POST",
"href": "/ledger/account-transaction/v1/xxx/authorizations/456789/captures"
},
{
"rel": "add-cancellation",
"method": "POST",
"href": "/ledger/account-transaction/v1/xxx/authorizations/456789/cancellations"
}
]
}
Possible problems
| Http status | Problem type | Description |
|---|---|---|
| 404 | not-found | Found no authorization for provided id on this ledger |
| 409 | invalid-account-usage | Provided PreAuthorization is invalid for this kind of authorization |
| 500 | fatal | Unexpected error, logs may give details about the problem |
Response object specification
| Property | Data type | Format | Description |
|---|---|---|---|
| @id | string | Uri identifier of the current resource | |
| authorizationId | number | Type: int64 | Identifier of the authorization, must be unique for all types of authorizations within the ledger |
| sellerNo | string | The seller identifier at payex | |
| validToDate | string | The authorization is valid for captures until this date. Format 'YYYY-MM-DD' | |
| authorizationAmount | number | Type: double Max: 100000000 Min: 0 | The original authorized amount |
| remainingAmount | number | Type: double | The remaining amount on the authorization available for capture |
| currency | string |
| |
| status | string |
| |
| operations | array | List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response |
3. Reversals
3.1 Create Reversal
For reversing a specific capture
Request
POST /ledger/account-transaction/v1/{ownerNo}/authorizations/{authorizationId}/reversals HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
{
"reversalId": "654321",
"currency": "SEK",
"amount": 512.00,
"sellerTransactionId": "753159"
}
Request object specification
| Property | Data type | Format | Required | Description |
|---|---|---|---|---|
| reversalId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | Identifier of the reversal, must be unique for all types of captures within the ledger |
| currency | string |
| Yes | |
| amount | number | Type: double Max: 100000000 Min: 0 | Yes | Amount to reverse |
| sellerTransactionId | string | Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ | Yes | The sellers identifier of the reversal transaction, usually the receipt reference |
Response
HTTP/1.1 201 CREATED
Content-Type: application/json
{
}
Possible problems
| Http status | Problem type | Description |
|---|---|---|
| 404 | not-found | Resource missing, may have been created on different ledger or have expired |
| 400 | validation | Validation error, response should describe the problem/s |
| 409 | currency-not-supported | Provided Currency does not match the authorization currency |
| 409 | invalid-amount | Provided Reversal Amount is invalid, likely larger than remaining captured amount |
| 409 | identifier-already-in-use | Provided Identifier is already in use, probably ReversalTransactionId is not unique |
| 409 | invalid-account-usage | Provided Authorization is invalid for this kind of reversal |
| 500 | fatal | Unexpected error, logs may give details about the problem |
Problems
All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.
Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
Example
Response
HTTP/1.1 400 Error
Content-Type: application/problem+json
{
"Type" : "ledger/{domain}/v1/problems/validation",
"Title" : "A validation error occurred",
"Status" : 400,
"Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
"Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
"Problems" : [
{
"amount" : "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
}
]
}