Integrate to PayEx Account transaction API

Changelog

2022-03-18
Added preAuthorizationStatus property on pre-authorization resource
Added hypermedia reference to reversal from capture response
Added hypermedia reference to split-authorization from pre-authorization response

Introduction

The account-transaction API is handle payment flows for split-payments and credit accounts for retail finance scenarios. The api contains redirect scenarios for account onboarding, upgrades and authentication.

1. Pre-authorizations

Gets already created pre authorization

1.1 Get specific Pre-authorization

Request

GET /ledger/account-transaction/v1/{ownerNo}/pre-authorizations/{preAuthorizationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Initiate new pre-authorization

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"preAuthorizationId": "8c535338-d92c-49e7-90bf-304dbf38e0bd",
"preAuthorizationStatus": "Initialized",
"customer": {
   "nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
    },
   "email": "abc@test.com",
   "msisdn": "4670123456",
   "customerNo": "456987"
  },
"sellerNo": "123456",
"sellerReferenceId": "abc-87465123",
"profileName": "configured-profile-name",
"authorizationAmount": 100.50,
"currency": "SEK",
"pointOfSale": "Test shop",
"assessment": {
   "assessmentUrl": "/score/sca/{claimantNo}/assessments/{assessmentNo}",
   "scaStatus": "Required"
  },
"operations": [
    {
     "rel": "redirect",
     "method": "POST",
     "href": "/ledger/account-transaction/v1/xxx/pre-authorizations/8c535338-d92c-49e7-90bf-304dbf38e0bd/redirect"
    }
  ]
}

1.2 Create Pre-authorization

Check if required conditions are met to begin a transaction. Creates an authentication resource that exposes operation link to redirect if user interaction is required. (Is there an existing account? Is the account's limit sufficient for the new transaction?)

Request

POST /ledger/account-transaction/v1/{ownerNo}/pre-authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"customer": {
   "nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
    },
   "email": "abc@test.com",
   "msisdn": "4670123456",
   "customerNo": "456987"
  },
"sellerNo": "123456",
"sellerReferenceId": "abc-87465123",
"profileName": "configured-profile-name",
"authorizationAmount": 100.50,
"currency": "SEK",
"pointOfSale": "Test shop",
"assessment": {
   "assessmentUrl": "/score/sca/{claimantNo}/assessments/{assessmentNo}",
   "scaStatus": "Required"
  }
}

Request object specification

Property	Data type	Format	Required	Description
customer	object		Yes
nationalConsumerIdentifier	object		Yes
value	string		No	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	No	The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	Yes	The customers Email
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	Yes	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	No	The identifier of the customer. Normally required, exception is when the configuration on the ledger is set for the provider of this API to generate customer numbers, in that case CustomerNo must not be set in request.
sellerNo	string		Yes	The seller identifier at the provider of the API
sellerReferenceId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Yes	Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries
profileName	string		Yes	The profilename of the account to authorize, use 'offers' resource in the Onboarding API to retrieve details about the account profile
authorizationAmount	number	Type: double Max: 100000000 Min: 0	Yes	The original authorized amount, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR	Yes
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
assessment	object		No
assessmentUrl	string	Pattern: ^/score/sca/v\d{1,10}/\w{0,15}[0-9aA-zZ]/assessments/\d+$	Yes
scaStatus	string	Required NotRequired	Yes

Initiate new pre-authorization. Evaluates and decides what needs to be ready for the requested authorize flow

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"preAuthorizationId": "8c535338d92c49e790bf304dbf38e0bd",
"preAuthorizationStatus": "Initialized",
"customer": {
   "nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
    },
   "email": "abc@test.com",
   "msisdn": "4670123456",
   "customerNo": "456987"
  },
"sellerNo": "123456",
"sellerReferenceId": "abc-87465123",
"profileName": "configured-profile-name",
"authorizationAmount": 100.50,
"currency": "SEK",
"pointOfSale": "Test shop",
"assessment": {
   "assessmentUrl": "/score/sca/{claimantNo}/assessments/{assessmentNo}",
   "scaStatus": "Required"
  },
"@id": "/ledger/account-transaction/v1/xxx/pre-authorizations/8c535338d92c49e790bf304dbf38e0bd",
"operations": [
    {
     "rel": "redirect",
     "method": "POST",
     "href": "/ledger/account-transaction/v1/xxx/pre-authorizations/8c535338d92c49e790bf304dbf38e0bd/redirect"
    }
  ]
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
409	conflict	May find more information in details
422	unprocessable	May find more information in details
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Format	Description
customer	object
nationalConsumerIdentifier	object
value	string		The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	The customers Email
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	The identifier of the customer. Normally required, exception is when the configuration on the ledger is set for the provider of this API to generate customer numbers, in that case CustomerNo must not be set in request.
sellerNo	string		The seller identifier at the provider of the API
sellerReferenceId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries
profileName	string		The profilename of the account to authorize, use 'offers' resource in the Onboarding API to retrieve details about the account profile
authorizationAmount	number	Type: double Max: 100000000 Min: 0	The original authorized amount, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR
pointOfSale	string		Trade name of the point of sale. Will be displayed to end customer. Only use if agreed with provider of the API
assessment	object
assessmentUrl	string	Pattern: ^/score/sca/v\d{1,10}/\w{0,15}[0-9aA-zZ]/assessments/\d+$
scaStatus	string	Required NotRequired
preAuthorizationId	string		Unique identifier of the pre-authorization, generated by the API
preAuthorizationStatus	string	Initialized Failed ReadyForAuthorization Completed
failReasonCode	string		Short descriptive code to expand on why PreAuthorizationStatus is Failed. Will be Null when PreAuthorizationStatus ain't Failed
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response
@id	string		Uri identifier of the current resource

2. Redirect

2.1 Create Redirect

Initiates redirect authentication flow, generates redirect url and accepts return url after redirect process finishes. The operation is exposed by the parent authentication if required.

Request

POST /ledger/account-transaction/v1/{ownerNo}/pre-authorizations/{preAuthorizationId}/redirect HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"returnUrl": "https://apiconsumerexample.se/transactioncallbackexample",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myapp://{ledgerNo}example",
   "autostartAction": "MhVrFOAClUaJUx6QqnLgCw",
   "languageCode": "Sv"
  }
}

Request object specification

Property	Data type	Required	Description
returnUrl	string	Yes	Url to return the end user to after process is completed
redirectOptions	object	Yes
nativeAppSwitchingUrl	string	No	Uri pointing to app, used to switch back to app from bankId
autostartAction	string	No	Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string	Yes	Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)

Setup the redirect for both the sign/identification page and where to be redirect after

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"redirectUrl": "/ledger/public-account-transaction/v1/{ledgerNo}/8c535338-d92c-49e7-90bf-304dbf38e0bd"
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
404	not-found	Resource missing, may have been created on different ledger or have expired
409	invalid-state	PreAuthorizationStatus for targeted resource is invalid for this method
409	account-limit-to-low	Occurs if the credit limit on the account is too low, raise the limit before making the call
409	account-missing	No Account found for provided profile name and customer, need to create an account before calling
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
redirectUrl	string

3. 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.

3.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": []
}

3.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	SEK NOK DKK EUR	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	SEK NOK DKK EUR
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	pending processed
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

4. Authorizations

Get an existing authorization.

4.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

4.2 Create Authorization

Create authorization to see if the account will accept the transaction. When accepted reserves the amount to on the underlying account (may include credit check) and creates the authorization instance. The reservation is time limited, captures will only be excepted until the reservation times out.

Request

POST /ledger/account-transaction/v1/{ownerNo}/authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"preAuthorizationId": "8c535338-d92c-49e7-90bf-304dbf38e0bd",
"authorizationId": 456789
}

Request object specification

Property	Data type	Format	Required	Description
preAuthorizationId	string		Yes	Identifier of the existing pre-authorization
authorizationId	number	Type: int64 Min: 1	Yes	Identifier of the authorization, must be unique for all types of authorizations within the ledger

Create authorization

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-01",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"@id": "/ledger/account-transaction/v1/xxx/authorizations/456789",
"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
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
409	credit-check-rejected	Credit check or extend of credit check was rejected
409	missing-pre-authorization	Resource missing, may have been created on different ledger or have expired
409	invalid-account-usage	Provided PreAuthorization is invalid for this kind of authorization
409	amount-exceeds-limit	Amount in PreAuthorization is no longer valid for this authorization
409	invalid-state	Provided PreAuthorization resource is in a invalid state for this method
409	identifier-already-in-use	AuthorizationId given is already used, provide a new one and try again
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	SEK NOK DKK EUR
status	string	Open Closed Cancelled
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

5. Captures

5.1 Create Capture

Captures part of (or complete) the authorization, includes options for part payment

Request

POST /ledger/account-transaction/v1/{ownerNo}/authorizations/{authorizationId}/captures HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"captureId": "123456",
"sellerTransactionId": "654789312",
"currency": "SEK",
"amount": 3600.00
}

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
sellerTransactionId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Yes	The sellers identifier of the capture/transaction, usually the receipt reference
currency	string	SEK NOK DKK EUR	Yes
amount	number	Type: double Max: 100000000 Min: 0	Yes	The total amount.

Capture created

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"captureId": "123456",
"operations": []
}

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 Capture Amount is invalid, likely larger than remaining authorized amount
409	identifier-already-in-use	Provided Identifier is already in use, probably CaptureTransactionId is not unique
409	invalid-account-usage	Provided Authorization is invalid for this kind of capture
409	authorization-expired	Provided Authorization is not open or has already expired
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
captureId	string	Identifier of the capture, must be unique for all types of captures within the ledger
operations	array	List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

6. Reversals

6.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	SEK NOK DKK EUR	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

7. Cancellations

7.1 Create Cancellation

This operation will cancel the specified authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/authorizations/{authorizationId}/cancellations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
}

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

Possible problems

Http status	Problem type	Description
404	missing-pre-authorization	Resource missing, may have been created on different ledger or have expired
409	invalid-account-usage	Provided Authorization is invalid for this kind of authorization
409	authorization-expired	Provided Authorization is not open or has already expired
500	fatal	Unexpected error, logs may give details about the problem

8. Split-authorizations

Get an existing split-authorization. The split - authorization, is used when each product has a separate part payment that should be portioned out according to instruction.

8.1 Get specific Split-authorization

Request

GET /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get Split authorization resource. Operations can vary based of state of resource

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-08",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"operations": [
    {
     "rel": "add-capture",
     "method": "POST",
     "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/captures"
    },
    {
     "rel": "add-cancellation",
     "method": "POST",
     "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/cancellations"
    }
  ]
}

Possible problems

Http status	Problem type	Description
404	not-found	Found no authorization for provided id on this ledger
500	fatal	Unexpected error, logs may give details about the problem

8.2 Create Split-authorization

Create split-authorization to see if the account will accept the transaction. When accepted reserves the amount to on the underlying account (may include credit check) and creates the authorization instance. The reservation is time limited, captures will only be excepted until the reservation times out. The 'split' authorization, is used when each product has a separate part payment that should be portioned out according to instruction.

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"preAuthorizationId": "8c535338-d92c-49e7-90bf-304dbf38e0bd",
"authorizationId": 456789
}

Request object specification

Property	Data type	Format	Required	Description
preAuthorizationId	string		Yes	Identifier of the existing pre-authorization
authorizationId	number	Type: int64	Yes	Identifier of the authorization, must be unique for all types of authorizations within the ledger

Create Split authorization

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-08",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"@id": "/ledger/account-transaction/v1/xxx/split-authorizations/456789",
"operations": [
    {
     "rel": "add-capture",
     "method": "POST",
     "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/captures"
    },
    {
     "rel": "add-cancellation",
     "method": "POST",
     "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/cancellations"
    }
  ]
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
409	credit-check-rejected	Credit check or extend of credit check was rejected
409	missing-pre-authorization	Resource missing, may have been created on different ledger or have expired
409	invalid-account-usage	Provided PreAuthorization is invalid for this kind of authorization
409	invalid-state	Provided PreAuthorization resource is in a invalid state for this method
409	identifier-already-in-use	AuthorizationId given is already used, provide a new one and try again
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 Min: 1	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 split-authorization is valid for captures until this date. Format 'YYYY-MM-DD'
authorizationAmount	number	Type: double	The original authorized amount
remainingAmount	number	Type: double	The remaining amount on the split-authorization available for capture
currency	string	SEK NOK DKK EUR
status	string	Open Closed Cancelled
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

9. Captures

9.1 Create Capture

Captures part of (or complete) the split-authorization, includes options for part payment

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId}/captures HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"captureId": "123456",
"sellerTransactionId": "654789312",
"currency": "SEK",
"monthlyBillingAmount": 300,
"months": 12,
"totalAmount": 3600.00,
"productName": "Purchase ref: 233445"
}

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
sellerTransactionId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Yes	The sellers identifier of the capture/transaction, usually the receipt reference
currency	string	SEK NOK DKK EUR	Yes
monthlyBillingAmount	number	Type: double Max: 100000000 Min: 10	Yes	The amount the customer should be billed each month for this product, [MonthlyBilledAmount] x [Months] must be equal to or greater than [TotalAmount]. [TotalAmount] divided by [MonthlyBilledAmount] must be in the range between [Months]-1 and [Months]
months	number	Type: int32 Pattern: ^(6\|12\|24\|36)$	Yes	Number of monthly payments the [TotalAmount] should be split into
totalAmount	number	Type: double Max: 100000000 Min: 10	Yes	The total amount/cost of the product, must be evenly dividable with part payment terms in the account offer
productName	string		Yes	To the consumer meaningful reference to the purchase/delivery receipt. Part of what is presented to the consumer on the bills

Capture created

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"captureId": "123456",
"operations": []
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
404	not-found	Found no authorization for provided id on this ledger
409	authorization-expired	ValidToDate on this authorize has expired, see details for more information
409	invalid-amount	See details to get more information about the error
409	currency-not-supported	Currency not valid for this Capture, see details for more information
409	identifier-already-in-use	CaptureId given is already used, provide a new one and try again
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
captureId	string	Identifier of the capture, must be unique for all types of captures within the ledger
operations	array	List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

10. Cancellations

10.1 Create Cancellation

This operation will cancel the specified split-authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId}/cancellations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
}

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

Possible problems

Http status	Problem type	Description
404	not-found	Found no authorization for provided id on this ledger
500	fatal	Unexpected error, logs may give details about the problem

11. Reversals

11.1 Create Reversal

For reversing a specific capture

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId}/captures/{captureId}/reversals HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"reversalId": "abcdefg123",
"currency": "SEK",
"amount": 512.00,
"sellerTransactionId": "123456"
}

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	SEK NOK DKK EUR	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
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
404	not-found	Found no authorization for provided id on this ledger
409	invalid-amount	See details to get more information about the error
409	currency-not-supported	Currency not valid for this Reversal, see details for more information
409	identifier-already-in-use	ReversalId given is already used, provide a new one and try again
500	fatal	Unexpected error, logs may give details about the problem

12. Account-applications

Get an existing account-application. The account - application, is used when applying for new account.

12.1 Get specific Account-application

Request

GET /ledger/account-transaction/v1/{ownerNo}/account-applications/{accountApplicationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"customer": {
   "nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
    },
   "email": "a@b.c",
   "msisdn": "46123456",
   "customerNo": "1234"
  },
"profileName": "myProfileName",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myApp",
   "languageCode": "sv"
  },
"operations": []
}

12.2 Create Account-application

Create account-application is used when applying for new account. the application process may include signing and credit check

Request

POST /ledger/account-transaction/v1/{ownerNo}/account-applications HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"customer": {
   "nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
    },
   "email": "a@b.c",
   "msisdn": "46123456",
   "customerNo": "1234"
  },
"profileName": "myProfileName",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myApp",
   "languageCode": "sv"
  }
}

Request object specification

Property	Data type	Format	Required	Description
customer	object		Yes
nationalConsumerIdentifier	object		Yes
value	string		Yes	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	No	The country code for the identifier value property, value 'None' is not allowed, ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	No	The customers Email. Only used for creating new customer
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	No	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'. Only used for creating new customer
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	No	Provide the customer identifier. If customer does not yet exist in our ledger and ledger is configured to generate new customers CustomerNo then don't set this property. Ledger generated CustomerNo will be set after customer is created
profileName	string		Yes	The profilename of the account to create
creditLimit	number	Type: double Max: 100000000 Min: 0	Yes	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR	Yes
returnUrl	string		Yes	Url to return the end user to after process is completed
redirectOptions	object		Yes
nativeAppSwitchingUrl	string		No	Uri pointing to app, used to switch back to app from bankId
autostartAction	string		No	Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Yes	Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"customer": {
   "nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
    },
   "email": "a@b.c",
   "msisdn": "46123456",
   "customerNo": "1234"
  },
"profileName": "myProfileName",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myApp",
   "languageCode": "sv"
  },
"operations": []
}

Possible problems

Http status	Problem type	Description
409	account-already-exist	Occurs if a account already exists.

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
customer	object
nationalConsumerIdentifier	object
value	string		The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	The country code for the identifier value property, value 'None' is not allowed, ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	The customers Email. Only used for creating new customer
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'. Only used for creating new customer
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	Provide the customer identifier. If customer does not yet exist in our ledger and ledger is configured to generate new customers CustomerNo then don't set this property. Ledger generated CustomerNo will be set after customer is created
profileName	string		The profilename of the account to create
creditLimit	number	Type: double Max: 100000000 Min: 0	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR
returnUrl	string		Url to return the end user to after process is completed
redirectOptions	object
nativeAppSwitchingUrl	string		Uri pointing to app, used to switch back to app from bankId
autostartAction	string		Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)
accountApplicationId	string		Unique identifier of the account-application.
redirectUrl	string		Web uri pointing to the application flow that the user should be redirected to.
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

13. Limit-upgrade-applications

Get an existing limit-upgrade-application. The limit - upgrade - application, is used for upgrading limit on existing credit account.

13.1 Get specific Limit-upgrade-application

Request

GET /ledger/account-transaction/v1/{ownerNo}/limit-upgrade-applications/{limitUpgradeApplicationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"accountNo": "12345",
"customerNo": "54321",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myApp",
   "languageCode": "sv"
  },
"operations": []
}

13.2 Create Limit-upgrade-application

Create limit-upgrade-application is used when applying for upgrading limit on existing credit account. The application process may include signing and credit check

Request

POST /ledger/account-transaction/v1/{ownerNo}/limit-upgrade-applications HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"accountNo": "12345",
"customerNo": "54321",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myApp",
   "languageCode": "sv"
  }
}

Request object specification

Property	Data type	Format	Required	Description
accountNo	string		Yes	The identifier of the account
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	Yes	The identifier of the customer.
creditLimit	number	Type: double Max: 100000000 Min: 0	Yes	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR	Yes
returnUrl	string		Yes	Url to return the end user to after process is completed
redirectOptions	object		Yes
nativeAppSwitchingUrl	string		No	Uri pointing to app, used to switch back to app from bankId
autostartAction	string		No	Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Yes	Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"accountNo": "12345",
"customerNo": "54321",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
   "nativeAppSwitchingUrl": "myApp",
   "languageCode": "sv"
  },
"operations": []
}

Possible problems

Http status	Problem type	Description
404	account-not-found	Occurs if the account is not found.

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
accountNo	string		The identifier of the account
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	The identifier of the customer.
creditLimit	number	Type: double Max: 100000000 Min: 0	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR
returnUrl	string		Url to return the end user to after process is completed
redirectOptions	object
nativeAppSwitchingUrl	string		Uri pointing to app, used to switch back to app from bankId
autostartAction	string		Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)
limitUpgradeApplicationId	string		Unique identifier of the account-application.
redirectUrl	string		Web uri pointing to the application flow that the user should be redirected to.
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

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]"
         ]
      }
}

1. Pre-authorizations

Gets already created pre authorization

1.1 Get specific Pre-authorization

Request

GET /ledger/account-transaction/v1/{ownerNo}/pre-authorizations/{preAuthorizationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Initiate new pre-authorization

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"preAuthorizationId": "8c535338-d92c-49e7-90bf-304dbf38e0bd",
"preAuthorizationStatus": "Initialized",
"customer": {
  "nationalConsumerIdentifier": {
    "value": "19101010-1010",
    "countryCode": "SE"
    },
  "email": "abc@test.com",
  "msisdn": "4670123456",
  "customerNo": "456987"
  },
"sellerNo": "123456",
"sellerReferenceId": "abc-87465123",
"profileName": "configured-profile-name",
"authorizationAmount": 100.50,
"currency": "SEK",
"pointOfSale": "Test shop",
"assessment": {
  "assessmentUrl": "/score/sca/{claimantNo}/assessments/{assessmentNo}",
  "scaStatus": "Required"
  },
"operations": [
    {
    "rel": "redirect",
    "method": "POST",
    "href": "/ledger/account-transaction/v1/xxx/pre-authorizations/8c535338-d92c-49e7-90bf-304dbf38e0bd/redirect"
    }
  ]
}

1.2 Create Pre-authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/pre-authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"customer": {
  "nationalConsumerIdentifier": {
    "value": "19101010-1010",
    "countryCode": "SE"
    },
  "email": "abc@test.com",
  "msisdn": "4670123456",
  "customerNo": "456987"
  },
"sellerNo": "123456",
"sellerReferenceId": "abc-87465123",
"profileName": "configured-profile-name",
"authorizationAmount": 100.50,
"currency": "SEK",
"pointOfSale": "Test shop",
"assessment": {
  "assessmentUrl": "/score/sca/{claimantNo}/assessments/{assessmentNo}",
  "scaStatus": "Required"
  }
}

Request object specification

Property	Data type	Format	Required	Description
customer	object		Yes
nationalConsumerIdentifier	object		Yes
value	string		No	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	No	The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	Yes	The customers Email
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	Yes	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	No	The identifier of the customer. Normally required, exception is when the configuration on the ledger is set for the provider of this API to generate customer numbers, in that case CustomerNo must not be set in request.
sellerNo	string		Yes	The seller identifier at the provider of the API
sellerReferenceId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Yes	Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries
profileName	string		Yes	The profilename of the account to authorize, use 'offers' resource in the Onboarding API to retrieve details about the account profile
authorizationAmount	number	Type: double Max: 100000000 Min: 0	Yes	The original authorized amount, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR	Yes
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
assessment	object		No
assessmentUrl	string	Pattern: ^/score/sca/v\d{1,10}/\w{0,15}[0-9aA-zZ]/assessments/\d+$	Yes
scaStatus	string	Required NotRequired	Yes

Initiate new pre-authorization. Evaluates and decides what needs to be ready for the requested authorize flow

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"preAuthorizationId": "8c535338d92c49e790bf304dbf38e0bd",
"preAuthorizationStatus": "Initialized",
"customer": {
  "nationalConsumerIdentifier": {
    "value": "19101010-1010",
    "countryCode": "SE"
    },
  "email": "abc@test.com",
  "msisdn": "4670123456",
  "customerNo": "456987"
  },
"sellerNo": "123456",
"sellerReferenceId": "abc-87465123",
"profileName": "configured-profile-name",
"authorizationAmount": 100.50,
"currency": "SEK",
"pointOfSale": "Test shop",
"assessment": {
  "assessmentUrl": "/score/sca/{claimantNo}/assessments/{assessmentNo}",
  "scaStatus": "Required"
  },
"@id": "/ledger/account-transaction/v1/xxx/pre-authorizations/8c535338d92c49e790bf304dbf38e0bd",
"operations": [
    {
    "rel": "redirect",
    "method": "POST",
    "href": "/ledger/account-transaction/v1/xxx/pre-authorizations/8c535338d92c49e790bf304dbf38e0bd/redirect"
    }
  ]
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
409	conflict	May find more information in details
422	unprocessable	May find more information in details
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Format	Description
customer	object
nationalConsumerIdentifier	object
value	string		The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	The customers Email
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	The identifier of the customer. Normally required, exception is when the configuration on the ledger is set for the provider of this API to generate customer numbers, in that case CustomerNo must not be set in request.
sellerNo	string		The seller identifier at the provider of the API
sellerReferenceId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Sellers reference id, usually the order id of the purchase / consistent for all captures/deliveries
profileName	string		The profilename of the account to authorize, use 'offers' resource in the Onboarding API to retrieve details about the account profile
authorizationAmount	number	Type: double Max: 100000000 Min: 0	The original authorized amount, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR
pointOfSale	string		Trade name of the point of sale. Will be displayed to end customer. Only use if agreed with provider of the API
assessment	object
assessmentUrl	string	Pattern: ^/score/sca/v\d{1,10}/\w{0,15}[0-9aA-zZ]/assessments/\d+$
scaStatus	string	Required NotRequired
preAuthorizationId	string		Unique identifier of the pre-authorization, generated by the API
preAuthorizationStatus	string	Initialized Failed ReadyForAuthorization Completed
failReasonCode	string		Short descriptive code to expand on why PreAuthorizationStatus is Failed. Will be Null when PreAuthorizationStatus ain't Failed
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response
@id	string		Uri identifier of the current resource

2. Redirect

2.1 Create Redirect

Initiates redirect authentication flow, generates redirect url and accepts return url after redirect process finishes. The operation is exposed by the parent authentication if required.

Request

POST /ledger/account-transaction/v1/{ownerNo}/pre-authorizations/{preAuthorizationId}/redirect HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"returnUrl": "https://apiconsumerexample.se/transactioncallbackexample",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myapp://{ledgerNo}example",
  "autostartAction": "MhVrFOAClUaJUx6QqnLgCw",
  "languageCode": "Sv"
  }
}

Request object specification

Property	Data type	Required	Description
returnUrl	string	Yes	Url to return the end user to after process is completed
redirectOptions	object	Yes
nativeAppSwitchingUrl	string	No	Uri pointing to app, used to switch back to app from bankId
autostartAction	string	No	Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string	Yes	Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)

Setup the redirect for both the sign/identification page and where to be redirect after

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"redirectUrl": "/ledger/public-account-transaction/v1/{ledgerNo}/8c535338-d92c-49e7-90bf-304dbf38e0bd"
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
404	not-found	Resource missing, may have been created on different ledger or have expired
409	invalid-state	PreAuthorizationStatus for targeted resource is invalid for this method
409	account-limit-to-low	Occurs if the credit limit on the account is too low, raise the limit before making the call
409	account-missing	No Account found for provided profile name and customer, need to create an account before calling
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
redirectUrl	string

3. 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.

3.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": []
}

3.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	SEK NOK DKK EUR	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	SEK NOK DKK EUR
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	pending processed
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

4. Authorizations

Get an existing authorization.

4.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

4.2 Create Authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"preAuthorizationId": "8c535338-d92c-49e7-90bf-304dbf38e0bd",
"authorizationId": 456789
}

Request object specification

Property	Data type	Format	Required	Description
preAuthorizationId	string		Yes	Identifier of the existing pre-authorization
authorizationId	number	Type: int64 Min: 1	Yes	Identifier of the authorization, must be unique for all types of authorizations within the ledger

Create authorization

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-01",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"@id": "/ledger/account-transaction/v1/xxx/authorizations/456789",
"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
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
409	credit-check-rejected	Credit check or extend of credit check was rejected
409	missing-pre-authorization	Resource missing, may have been created on different ledger or have expired
409	invalid-account-usage	Provided PreAuthorization is invalid for this kind of authorization
409	amount-exceeds-limit	Amount in PreAuthorization is no longer valid for this authorization
409	invalid-state	Provided PreAuthorization resource is in a invalid state for this method
409	identifier-already-in-use	AuthorizationId given is already used, provide a new one and try again
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	SEK NOK DKK EUR
status	string	Open Closed Cancelled
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

5. Captures

5.1 Create Capture

Captures part of (or complete) the authorization, includes options for part payment

Request

POST /ledger/account-transaction/v1/{ownerNo}/authorizations/{authorizationId}/captures HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"captureId": "123456",
"sellerTransactionId": "654789312",
"currency": "SEK",
"amount": 3600.00
}

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
sellerTransactionId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Yes	The sellers identifier of the capture/transaction, usually the receipt reference
currency	string	SEK NOK DKK EUR	Yes
amount	number	Type: double Max: 100000000 Min: 0	Yes	The total amount.

Capture created

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"captureId": "123456",
"operations": []
}

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 Capture Amount is invalid, likely larger than remaining authorized amount
409	identifier-already-in-use	Provided Identifier is already in use, probably CaptureTransactionId is not unique
409	invalid-account-usage	Provided Authorization is invalid for this kind of capture
409	authorization-expired	Provided Authorization is not open or has already expired
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
captureId	string	Identifier of the capture, must be unique for all types of captures within the ledger
operations	array	List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

6. Reversals

6.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	SEK NOK DKK EUR	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

7. Cancellations

7.1 Create Cancellation

This operation will cancel the specified authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/authorizations/{authorizationId}/cancellations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
}

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

Possible problems

Http status	Problem type	Description
404	missing-pre-authorization	Resource missing, may have been created on different ledger or have expired
409	invalid-account-usage	Provided Authorization is invalid for this kind of authorization
409	authorization-expired	Provided Authorization is not open or has already expired
500	fatal	Unexpected error, logs may give details about the problem

8. Split-authorizations

Get an existing split-authorization. The split - authorization, is used when each product has a separate part payment that should be portioned out according to instruction.

8.1 Get specific Split-authorization

Request

GET /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get Split authorization resource. Operations can vary based of state of resource

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-08",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"operations": [
    {
    "rel": "add-capture",
    "method": "POST",
    "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/captures"
    },
    {
    "rel": "add-cancellation",
    "method": "POST",
    "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/cancellations"
    }
  ]
}

Possible problems

Http status	Problem type	Description
404	not-found	Found no authorization for provided id on this ledger
500	fatal	Unexpected error, logs may give details about the problem

8.2 Create Split-authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"preAuthorizationId": "8c535338-d92c-49e7-90bf-304dbf38e0bd",
"authorizationId": 456789
}

Request object specification

Property	Data type	Format	Required	Description
preAuthorizationId	string		Yes	Identifier of the existing pre-authorization
authorizationId	number	Type: int64	Yes	Identifier of the authorization, must be unique for all types of authorizations within the ledger

Create Split authorization

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"authorizationId": 456789,
"sellerNo": "654321",
"validToDate": "2023-03-08",
"authorizationAmount": 3600.00,
"remainingAmount": 3600.00,
"currency": "SEK",
"status": "Open",
"@id": "/ledger/account-transaction/v1/xxx/split-authorizations/456789",
"operations": [
    {
    "rel": "add-capture",
    "method": "POST",
    "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/captures"
    },
    {
    "rel": "add-cancellation",
    "method": "POST",
    "href": "/ledger/account-transaction/v1/xxx/split-authorizations/456789/cancellations"
    }
  ]
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
409	credit-check-rejected	Credit check or extend of credit check was rejected
409	missing-pre-authorization	Resource missing, may have been created on different ledger or have expired
409	invalid-account-usage	Provided PreAuthorization is invalid for this kind of authorization
409	invalid-state	Provided PreAuthorization resource is in a invalid state for this method
409	identifier-already-in-use	AuthorizationId given is already used, provide a new one and try again
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 Min: 1	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 split-authorization is valid for captures until this date. Format 'YYYY-MM-DD'
authorizationAmount	number	Type: double	The original authorized amount
remainingAmount	number	Type: double	The remaining amount on the split-authorization available for capture
currency	string	SEK NOK DKK EUR
status	string	Open Closed Cancelled
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

9. Captures

9.1 Create Capture

Captures part of (or complete) the split-authorization, includes options for part payment

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId}/captures HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"captureId": "123456",
"sellerTransactionId": "654789312",
"currency": "SEK",
"monthlyBillingAmount": 300,
"months": 12,
"totalAmount": 3600.00,
"productName": "Purchase ref: 233445"
}

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
sellerTransactionId	string	Pattern: ^[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$	Yes	The sellers identifier of the capture/transaction, usually the receipt reference
currency	string	SEK NOK DKK EUR	Yes
monthlyBillingAmount	number	Type: double Max: 100000000 Min: 10	Yes	The amount the customer should be billed each month for this product, [MonthlyBilledAmount] x [Months] must be equal to or greater than [TotalAmount]. [TotalAmount] divided by [MonthlyBilledAmount] must be in the range between [Months]-1 and [Months]
months	number	Type: int32 Pattern: ^(6\|12\|24\|36)$	Yes	Number of monthly payments the [TotalAmount] should be split into
totalAmount	number	Type: double Max: 100000000 Min: 10	Yes	The total amount/cost of the product, must be evenly dividable with part payment terms in the account offer
productName	string		Yes	To the consumer meaningful reference to the purchase/delivery receipt. Part of what is presented to the consumer on the bills

Capture created

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"captureId": "123456",
"operations": []
}

Possible problems

Http status	Problem type	Description
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
404	not-found	Found no authorization for provided id on this ledger
409	authorization-expired	ValidToDate on this authorize has expired, see details for more information
409	invalid-amount	See details to get more information about the error
409	currency-not-supported	Currency not valid for this Capture, see details for more information
409	identifier-already-in-use	CaptureId given is already used, provide a new one and try again
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
captureId	string	Identifier of the capture, must be unique for all types of captures within the ledger
operations	array	List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

10. Cancellations

10.1 Create Cancellation

This operation will cancel the specified split-authorization

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId}/cancellations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
}

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

Possible problems

Http status	Problem type	Description
404	not-found	Found no authorization for provided id on this ledger
500	fatal	Unexpected error, logs may give details about the problem

11. Reversals

11.1 Create Reversal

For reversing a specific capture

Request

POST /ledger/account-transaction/v1/{ownerNo}/split-authorizations/{authorizationId}/captures/{captureId}/reversals HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"reversalId": "abcdefg123",
"currency": "SEK",
"amount": 512.00,
"sellerTransactionId": "123456"
}

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	SEK NOK DKK EUR	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
400	validation	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
404	not-found	Found no authorization for provided id on this ledger
409	invalid-amount	See details to get more information about the error
409	currency-not-supported	Currency not valid for this Reversal, see details for more information
409	identifier-already-in-use	ReversalId given is already used, provide a new one and try again
500	fatal	Unexpected error, logs may give details about the problem

12. Account-applications

Get an existing account-application. The account - application, is used when applying for new account.

12.1 Get specific Account-application

Request

GET /ledger/account-transaction/v1/{ownerNo}/account-applications/{accountApplicationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"customer": {
  "nationalConsumerIdentifier": {
    "value": "19101010-1010",
    "countryCode": "SE"
    },
  "email": "a@b.c",
  "msisdn": "46123456",
  "customerNo": "1234"
  },
"profileName": "myProfileName",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myApp",
  "languageCode": "sv"
  },
"operations": []
}

12.2 Create Account-application

Create account-application is used when applying for new account. the application process may include signing and credit check

Request

POST /ledger/account-transaction/v1/{ownerNo}/account-applications HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"customer": {
  "nationalConsumerIdentifier": {
    "value": "19101010-1010",
    "countryCode": "SE"
    },
  "email": "a@b.c",
  "msisdn": "46123456",
  "customerNo": "1234"
  },
"profileName": "myProfileName",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myApp",
  "languageCode": "sv"
  }
}

Request object specification

Property	Data type	Format	Required	Description
customer	object		Yes
nationalConsumerIdentifier	object		Yes
value	string		Yes	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	No	The country code for the identifier value property, value 'None' is not allowed, ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	No	The customers Email. Only used for creating new customer
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	No	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'. Only used for creating new customer
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	No	Provide the customer identifier. If customer does not yet exist in our ledger and ledger is configured to generate new customers CustomerNo then don't set this property. Ledger generated CustomerNo will be set after customer is created
profileName	string		Yes	The profilename of the account to create
creditLimit	number	Type: double Max: 100000000 Min: 0	Yes	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR	Yes
returnUrl	string		Yes	Url to return the end user to after process is completed
redirectOptions	object		Yes
nativeAppSwitchingUrl	string		No	Uri pointing to app, used to switch back to app from bankId
autostartAction	string		No	Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Yes	Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"customer": {
  "nationalConsumerIdentifier": {
    "value": "19101010-1010",
    "countryCode": "SE"
    },
  "email": "a@b.c",
  "msisdn": "46123456",
  "customerNo": "1234"
  },
"profileName": "myProfileName",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myApp",
  "languageCode": "sv"
  },
"operations": []
}

Possible problems

Http status	Problem type	Description
409	account-already-exist	Occurs if a account already exists.

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
customer	object
nationalConsumerIdentifier	object
value	string		The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string	Pattern: SE\|NO\|DK\|FI	The country code for the identifier value property, value 'None' is not allowed, ISO 3166-1 alpha-2
email	string	Pattern: [^@]+@[^\.]+\..+	The customers Email. Only used for creating new customer
msisdn	string	Pattern: [0-9, +, (, ), -]{5,15}	'Mobile Subscriber Integrated Services Digital Network Number', ie. Cellphone number. Countrycode is always required as the example '46720000000'. Only used for creating new customer
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	Provide the customer identifier. If customer does not yet exist in our ledger and ledger is configured to generate new customers CustomerNo then don't set this property. Ledger generated CustomerNo will be set after customer is created
profileName	string		The profilename of the account to create
creditLimit	number	Type: double Max: 100000000 Min: 0	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR
returnUrl	string		Url to return the end user to after process is completed
redirectOptions	object
nativeAppSwitchingUrl	string		Uri pointing to app, used to switch back to app from bankId
autostartAction	string		Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)
accountApplicationId	string		Unique identifier of the account-application.
redirectUrl	string		Web uri pointing to the application flow that the user should be redirected to.
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

13. Limit-upgrade-applications

Get an existing limit-upgrade-application. The limit - upgrade - application, is used for upgrading limit on existing credit account.

13.1 Get specific Limit-upgrade-application

Request

GET /ledger/account-transaction/v1/{ownerNo}/limit-upgrade-applications/{limitUpgradeApplicationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"accountNo": "12345",
"customerNo": "54321",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myApp",
  "languageCode": "sv"
  },
"operations": []
}

13.2 Create Limit-upgrade-application

Create limit-upgrade-application is used when applying for upgrading limit on existing credit account. The application process may include signing and credit check

Request

POST /ledger/account-transaction/v1/{ownerNo}/limit-upgrade-applications HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"accountNo": "12345",
"customerNo": "54321",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myApp",
  "languageCode": "sv"
  }
}

Request object specification

Property	Data type	Format	Required	Description
accountNo	string		Yes	The identifier of the account
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	Yes	The identifier of the customer.
creditLimit	number	Type: double Max: 100000000 Min: 0	Yes	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR	Yes
returnUrl	string		Yes	Url to return the end user to after process is completed
redirectOptions	object		Yes
nativeAppSwitchingUrl	string		No	Uri pointing to app, used to switch back to app from bankId
autostartAction	string		No	Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Yes	Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"redirectUrl": "https://ledger-apps.payex.com/ledger/public-account-transaction/v1/XXX/pre-authorization/8c535338-d92c-49e7-90bf-304dbf38e0bd",
"accountNo": "12345",
"customerNo": "54321",
"creditLimit": 5000.00,
"currency": "SEK",
"returnUrl": "https://webconsumerexample.se/consumerweb",
"redirectOptions": {
  "nativeAppSwitchingUrl": "myApp",
  "languageCode": "sv"
  },
"operations": []
}

Possible problems

Http status	Problem type	Description
404	account-not-found	Occurs if the account is not found.

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
accountNo	string		The identifier of the account
customerNo	string	Pattern: ^[a-zA-Z0-9\-]{1,}$	The identifier of the customer.
creditLimit	number	Type: double Max: 100000000 Min: 0	The amount of the credit limit on the account applied for, can't have more than 2 decimal places
currency	string	SEK NOK DKK EUR
returnUrl	string		Url to return the end user to after process is completed
redirectOptions	object
nativeAppSwitchingUrl	string		Uri pointing to app, used to switch back to app from bankId
autostartAction	string		Used to automatically start bankId application. Possible actions (null\|se-bankid-this-device)
languageCode	string		Used to set desired language in the authenticate/onboarding web. Possible languageCodes (SV\|EN)
limitUpgradeApplicationId	string		Unique identifier of the account-application.
redirectUrl	string		Web uri pointing to the application flow that the user should be redirected to.
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

Problems

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]"
         ]
      }
}

credit-account

accounttransaction

Changelog

Introduction

1. Pre-authorizations

1.1 Get specific Pre-authorization

1.2 Create Pre-authorization

2. Redirect

2.1 Create Redirect

3. Authorization-capture-orders

3.1 Get specific Authorization-capture-order

Success Example

Error Example

3.2 Create Authorization-capture-order

4. Authorizations

4.1 Get specific Authorization

4.2 Create Authorization

5. Captures

5.1 Create Capture

6. Reversals

6.1 Create Reversal

7. Cancellations

7.1 Create Cancellation

8. Split-authorizations

8.1 Get specific Split-authorization

8.2 Create Split-authorization

9. Captures

9.1 Create Capture

10. Cancellations

10.1 Create Cancellation

11. Reversals

11.1 Create Reversal

12. Account-applications

12.1 Get specific Account-application

12.2 Create Account-application

13. Limit-upgrade-applications

13.1 Get specific Limit-upgrade-application

13.2 Create Limit-upgrade-application

Problems

Example

1. Pre-authorizations

1.1 Get specific Pre-authorization

1.2 Create Pre-authorization

2. Redirect

2.1 Create Redirect

3. Authorization-capture-orders

3.1 Get specific Authorization-capture-order

Success Example

Error Example

3.2 Create Authorization-capture-order

4. Authorizations

4.1 Get specific Authorization

4.2 Create Authorization

5. Captures

5.1 Create Capture

6. Reversals

6.1 Create Reversal

7. Cancellations

7.1 Create Cancellation

8. Split-authorizations

8.1 Get specific Split-authorization

8.2 Create Split-authorization

9. Captures

9.1 Create Capture

10. Cancellations

10.1 Create Cancellation

11. Reversals

11.1 Create Reversal

12. Account-applications

12.1 Get specific Account-application

12.2 Create Account-application

13. Limit-upgrade-applications

13.1 Get specific Limit-upgrade-application

13.2 Create Limit-upgrade-application

Problems

Example