credit-account

account-transactions [obsolete]

Integrate to PayEx Account transaction API 

Changelog

Introduction

The account transaction API is used to create accounts and transactions for retail finance scenarios. The api contains re-direct scenarios for SCA-authentication when the consumer is present.

Pre-authorizations

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? Does the transaction requires strong customer authentication SCA?) Can be used in with TRA assesment to reduce authentication friction.

Request
POST /ledger/account-transaction/v1/{ledgerNo}/authentications/{authenticationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "@id": "string",
 "customer": {
   "nationalConsumerIdentifier": {
     "value": "string",
     "countryCode": "None"
    },
   "email": "string",
   "msisdn": "string",
   "customerNo": "string"
  },
 "sellerNo": "string",
 "sellerReferenceId": "string",
 "profileName": "string",
 "authorizationAmount": 99999999,
 "currency": "None",
 "externalReference": "string",
 "assesment": {
   "assessmentUrl": "string",
   "scaStatus": "None"
  }
}

Request properties requirements

Property Required
@id Yes 
customer Yes 
  nationalConsumerIdentifier Yes 
    value Yes 
    countryCode Yes 
  email Yes 
  msisdn Yes 
  customerNo Yes 
sellerNo Yes 
sellerReferenceId Yes 
profileName Yes 
authorizationAmount Yes 
currency Yes 
externalReference Yes 
assesment Yes 
  assessmentUrl Yes 
  scaStatus Yes 
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

 

pre-authorizations properties

Property Data typeFormatDescription
@id String   
customer object   
  nationalConsumerIdentifier object   
    value String   
    countryCode String   
  email String   
  msisdn String   
  customerNo String   
sellerNo String   
sellerReferenceId String   
profileName String   
authorizationAmount Integer   
currency String   
externalReference String   
assesment object   
  assessmentUrl String   
  scaStatus String   

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/{ledgerNo}/authentications/{authenticationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "returnUrl": "string",
 "redirectOptions": {
   "nativeAppSwitchingUrl": "string",
   "autostartAction": "string",
   "languageCode": "string"
  }
}

Request properties requirements

Property Required
returnUrl Yes 
redirectOptions Yes 
  nativeAppSwitchingUrl Yes 
  autostartAction Yes 
  languageCode Yes 
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

{
 "@id": "string",
 "redirectUrl": "string"
}
 

Redirect properties

Property Data typeFormatDescription
returnUrl String   
redirectOptions object   
  nativeAppSwitchingUrl String   
  autostartAction String   
  languageCode String   

Split-authorizations

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 exepted 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/{ledgerNo}/authentications/{authenticationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "@id": "string",
 "splitAuthorizationId": "string",
 "preAuthorizationId": "string"
}

Request properties requirements

Property Required
@id Yes 
splitAuthorizationId Yes 
preAuthorizationId Yes 
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

{
 "@id": "string",
 "splitAuthorizationId": "string",
 "preAuthorizationId": "string",
 "sellerNumber": "string",
 "validToDate": "2022-02-24T01:00:49.139Z",
 "authorizationAmount": 0,
 "remainingAmount": 0,
 "currency": "string",
 "status": "string",
 "operations": [
    {
     "rel": "string",
     "method": "string",
     "href": "string"
    }
  ]
}
 

Split-authorizations properties

Property Data typeFormatDescription
@id String   
splitAuthorizationId String   
preAuthorizationId String   

captures

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

Request
POST /ledger/account-transaction/v1/{ledgerNo}/authentications/{authenticationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "captureId": "string",
 "sellerTransactionId": "string",
 "currency": "string",
 "monthlyBillingAmount": 0,
 "months": 0,
 "totalAmount": 0,
 "productName": "string"
}

Request properties requirements

Property Required
captureId Yes 
sellerTransactionId Yes 
currency Yes 
monthlyBillingAmount Yes 
months Yes 
totalAmount Yes 
productName Yes 
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

{
 "captureId": "string",
 "accountNo": "string",
 "account": "string"
}
 

captures properties

Property Data typeFormatDescription
captureId String   
sellerTransactionId String   
currency String   
monthlyBillingAmount Integer   
months Integer   
totalAmount Integer   
productName String   

Reversal

For reversing a specific capture

Request
POST /ledger/account-transaction/v1/{ledgerNo}/authentications/{authenticationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
 "@id": "string",
 "reversalId": "string",
 "currency": "string",
 "amount": 0,
 "sellerTransactionId": "string"
}

Request properties requirements

Property Required
@id Yes 
reversalId Yes 
currency Yes 
amount Yes 
sellerTransactionId Yes 
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

 

Reversal properties

Property Data typeFormatDescription
@id String   
reversalId String   
currency String   
amount Integer   
sellerTransactionId String   

Canellations

This operation will cancel the specified split-authorization

Request
POST /ledger/account-transaction/v1/{ledgerNo}/authentications/{authenticationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{}

Request properties requirements

Property Required
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

 

Canellations properties

Property Data typeFormatDescription

Public-account-transaction

Authentications

Reqest
GET /ledger/public-account-transaction/v1/authentications HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Properties requirements

PropertyRequired
AssessmentUrlYes
ExternalReferenceNo
Response
HTTP/1.1 201 Created
Content-Type: application/json

{
   "accountOffer" : "/ledger/public-account-transaction/offers/Pay123",
   "operations" : [
        {
           "rel" : "onboard-upgrade-account",
           "href" : "/ledger/public-account-transaction/v1/authentications/onboard-upgrade-account",
           "method" : "POST"
        },
        {
           "rel" : "begin-bankid-se-authentication",
           "href" : "/ledger/public-account-transaction/v1/authentications/begin-bankid-se-authentication",
           "method" : "POST"
        }
 ],
"@id" : "/ledger/public-account-transaction/v1/authentications",
}

Account-applications

Add application to offer

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

{    
   "nationalConsumerIdentifier" : {
       "value" : "19101010-1010",
       "countryCode" : "SE"                
    },
   "creditLimit": 5000.00,
   "customerNo" : "951753456",
   "emailAddress" : "test@testshop.se",
   "cellPhone" : "+46701234456",  
   "ipAddress": "1.1.1.1",     
   "legalAddress" : {
       "name" : "John Smith",
       "streetAddress" : "Teststreet",
       "city" : "Testcity",
       "coAddress" : "",
       "zipCode" : "12345",
       "countryCode" : "SE"
    },
   "kyc": {
       "questions":[
            {
               "code": "employment",                
               "text": "Vad är din sysselsättning?",
               "answer" : {
                   "code": "self-employed",
                   "text": "Egen företagare"
                }                
            },
            {
               "code": "employment-since",                 
               "text": "Hur länge har du haft denna sysselsättning?",
               "answer" : {
                   "code": "2016-09",
                   "text": "2016-09"
                }
            },
            {
               "code": "monthlyIncome",                 
               "text": "Månadsinkomst före skatt",
               "answer" : {
                   "code": "10000.00",
                   "text": "10000"
                }
            },
            {
               "code": "monthlyPurchaseAmount",                 
               "text": "Hur mycket kommer du genomsnitt att handla på ditt kort?",
               "answer" : {
                   "code": "3000.00",               
                   "text": "3000"
                }
            },
            {
               "code": "monthlyNumberOfDeposits",                 
               "text": "Hur många inbetalningar kommer du att göra per månad?",
               "answer" : {
                   "code": "1-2",
                   "text": "1-2"
                }
            },
            {
               "code": "IsPep",                 
               "text": "Är du en person i politiskt utsatt ställning (PEP), det vill säga.....",
               "answer" : {
                   "code" : "true",
                   "text" : "Ja"
                }
            }
        ]
    }
}

List all applications

Request
GET /ledger/public-account-transaction/v1/account-applications HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Get a single application

Request
GET /ledger/public-account-transaction/v1/account-applications/NNN  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Applications Resource

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

{    
   "nationalConsumerIdentifier" : {
       "value" : "19101010-1010",
       "countryCode" : "SE"                
    },
   "status" : "awaiting-sign",
   "customerNo" : "951753456",
   "creditLimit": 5000.00,
   "emailAddress" : "test@testshop.se",
   "cellPhone" : "+46701234456",  
   "ipAddress": "1.1.1.1",     
   "legalAddress" : {
       "name" : "John Smith",
       "streetAddress" : "Teststreet",
       "city" : "Testcity",
       "coAddress" : "",
       "zipCode" : "12345",
       "countryCode" : "SE"
    },
   "kyc": {
       "questions":[
            {
               "code": "employment",                
               "text": "Vad är din sysselsättning?",
               "answer" : {
                   "code": "self-employed",
                   "text": "Egen företagare"
                }                
            },
            {
               "code": "employment-since",                 
               "text": "Hur länge har du haft denna sysselsättning?",
               "answer" : {
                   "code": "2016-09",
                   "text": "2016-09"
                }
            },
            {
               "code": "monthlyIncome",                 
               "text": "Månadsinkomst före skatt",
               "answer" : {
                   "code": "10000.00",
                   "text": "10000"
                }
            },
            {
               "code": "monthlyPurchaseAmount",                 
               "text": "Hur mycket kommer du genomsnitt att handla på ditt kort?",
               "answer" : {
                   "code": "3000.00",               
                   "text": "3000"
                }
            },
            {
               "code": "monthlyNumberOfDeposits",                 
               "text": "Hur många inbetalningar kommer du att göra per månad?",
               "answer" : {
                   "code": "1-2",
                   "text": "1-2"
                }
            },
            {
               "code": "IsPep",                 
               "text": "Är du en person i politiskt utsatt ställning (PEP), det vill säga.....",
               "answer" : {
                   "code" : "true",
                   "text" : "Ja"
                }
            }
        ]
    },
   "account" : null,
   "@id" : "/ledger/credit-account-onboardings/v1/501/offers/kontotyp-10000/applications/1561561-54641515-56456",
   "parentHREF" : "/ledger/credit-account-onboardings/v1/XXX/offers/kontotyp-10000",
   "operations" : [
        {
           "rel" : "sign-agreement",
           "href" : "/ledger/credit-account-onboardings/v1/XXX/offers/kontotyp-10000/applications/1561561-54641515-56456/sign-agreement",
           "method" : "POST"
        }
    ]
}

Resource properties

PropertyData typeRequired in postFormatDescription
@id string-Maxlength:  
nationalConsumerIdentifier.valuestringYesYYYYMMDD-NNNCA valid swedish "personnummer"
nationalConsumerIdentifier.countryCodestringYesISO 3166-1 alpha-2 
statusstring-Maxlength: 25
  • AwaitingSign
  • InitializedSigning
  • Approved
  • Rejected
  • SigningFailed
customerNostringYesMaxlength: 15 
creditLimitdecimalYes  
emailAddressstringYesMaxlength: 254
Regex pattern: [^@]+@[^\.]+\..+		 
cellPhonestringYesMaxlength: 15 
ipAddressstringNoMaxlength: 43
Regex pattern: [a-z0-9.:/]*		 
legalAddress.namestringYesMaxlength: 72end-customer fullname
legalAddress.streetAddressstringNoMaxlength: 35 
legalAddress.citystringYesMaxlength: 30 
legalAddress.coAddressstringNoMaxlength: 35 
legalAddress.zipCodestringYesMaxlength: 15ZipCode without whitespaces
legalAddress.countryCodestringYesISO 3166-1 alpha-2 
accountstring-UriReference to created account
kycobjectYes kyc (know your customer). The questions and answers in the above example are just examples of what it might look like. This API does not validate that "correct" questions are asked
kyc.questionslist of objectsYes  
kyc.questions.codestringYes The code definition of the question
kyc.questions.textstringYes The actual question text that was presented to the end-customer
kyc.questions.aswer.codestringYes The answered code definition from the end-customer
kyc.questions.aswer.textstringYes The actual displayed answertext that was presented to the customer

Limit-upgrade-application

Problem types

Note, each problem typecode is preceded by "ledger.account-transaction." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.account-transaction.validation".

Problem type (code)HttpstatusDescription
validation400occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
not-found404requested resource not found
conflict409state of resource is un valid for any further progress
claimant-mismatch409mismatch between claimant (in url) used in new request vs. when authenticaiton resource was made, 
invalid-authentication-state422un valid authentication status for requested method
authentication-is-no-longer-valid422the limited time of the authentication has passed
credit-check-rejected422credit check or extend of credit check was rejected
fatal500Unexpected error, logs maybe can tell more in detail what the problem is
not-implemented501the requested method is not implemented fully by code or not configured for the resource, body will tell which.
Created by David Persson on 2021/11/19 13:29