credit-account

../account-transaction (orders)

Draft:
Integrate to PayEx Account transaction API 

Changelog

Introduction

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

PayEx - Ledger API's - ForDeveloper (2).png

1. Authorization-capture-orders

Get an existing authorization-capture-orders. The authorization-capture-orders, is used when adding transactions to users account when user is pre identified.

1.1 Get specific Authorization-capture-order

Request
GET /ledger/account-transaction/v1/{ownerNo}/authorization-capture-orders/{captureId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json
Success Example

Response for a successful authorization and capture

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

{
 "status": "processed",
 "callbackBody": {
   "success": {
     "authorization": "/ledger/account-transaction/v1/XXX/authorizations/{authorizationId}"
    }
  },
 "captureId": "123456",
 "authorizationId": 123456789,
 "accountNo": "1234",
 "callbackUrl": "https://my.com/callback?543245892u59",
 "sellerReferenceId": "abc-87465123",
 "sellerTransactionId": "654789312",
 "authenticationMethod": "2FA",
 "currency": "SEK",
 "amount": 50.00,
 "pointOfSale": "Test shop",
 "operations": []
}
Error Example

Response for a unsuccessful authorization or capture

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

{
 "status": "processed",
 "callbackBody": {
   "fail": {
     "type": "ledger/account-transaction/v1/problems/validation",
     "title": "Not found",
     "status": 404,
     "detail": "A validation error occurred. Please fix the problems mentioned in the problems property below.",
     "instance": "215d4206-ca35-4f43-85ad-169c8f6d4ec1"
    }
  },
 "captureId": "123456",
 "authorizationId": 123456789,
 "accountNo": "1234",
 "callbackUrl": "https://my.com/callback?543245892u59",
 "sellerReferenceId": "abc-87465123",
 "sellerTransactionId": "654789312",
 "authenticationMethod": "2FA",
 "currency": "SEK",
 "amount": 50.000,
 "pointOfSale": "Test shop",
 "operations": []
}

1.2 Create Authorization-capture-order

Create authorization-capture-orders is used to add transaction when user is pre identified.

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

{
 "captureId": "123456",
 "authorizationId": 123456789,
 "accountNo": "1234",
 "callbackUrl": "https://my.com/callback?543245892u59",
 "sellerTransactionId": "654789312",
 "authenticationMethod": "2FA",
 "currency": "SEK",
 "amount": 50.00,
 "pointOfSale": "Test shop"
}

Request object specification

Property Data typeFormatRequiredDescription
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 typeFormatDescription
@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

2. Authorizations

Get an existing authorization.

2.1 Get specific Authorization

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

Get authorization

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

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

Possible problems

Http status Problem type Description
404 not-found Found no authorization for provided id on this ledger 
409 invalid-account-usage Provided PreAuthorization is invalid for this kind of authorization 
500 fatal Unexpected error, logs may give details about the problem 

Response object specification

Property Data typeFormatDescription
@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

3. Reversals

3.1 Create Reversal

For reversing a specific capture

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

{
 "reversalId": "654321",
 "currency": "SEK",
 "amount": 512.00,
 "sellerTransactionId": "753159"
}

Request object specification

Property Data typeFormatRequiredDescription
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 

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. Account-applications

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

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

1.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 typeFormatRequiredDescription
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 typeFormatDescription
@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

2. Limit-upgrade-applications

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

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

2.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 typeFormatRequiredDescription
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 typeFormatDescription
@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]"
         ]
      }
}

 

Created by David Persson on 2022/12/05 10:24