Integrate to PayEx Credit Account Onboarding API

Changelog

2020-03-02

Added statuses on applicationresource: "InitializedSigning" and "SigningFailed"

2020-02-28

minor changes in kyc object structure

2020-02-14

changed KYC object in ApplicationResource

This API is used to list currently available credit account offers as well as the associated onboarding process

Offers

List all offers

Response

GET /ledger/credit-account-onboarding/v1/XXX/offers HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "operations": null,
   "items": [
        {
           "accountProfile" : "kontotyp-1",
           "title" : "kontotyp 1",
           "currency" : "SEK",
           "maxCreditLimit" : 50000.00,
           "interestFreePurchaseMonth" : true|false,
           "monthlyAdminFee" : 35.00,
           "reminderFee" : 35.00,
           "interest" : 35.00,
           "termsAndConditions" :
            {
               "standardEuropeeanAgreements" : "https://www.payex.com/term-and-conditions/no/-----.pdf",
               "accountTerms" : "https://www.payex.com/term-and-conditions/no/-----.pdf"
            },
           "@id" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-1",
        },
        {
           "accountProfile" : "kontotyp-2",
           "title" : "kontotyp 2",
           "currency" : "SEK",
           "maxCreditLimit" : 0.00,
           "interestFreePurchaseMonth" : true|false,
           "monthlyAdminFee" : 35.00,
           "reminderFee" : 35.00,
           "interest" : 35.00,
           "termsAndConditions" :
            {
               "standardEuropeeanAgreements" : "https://www.payex.com/term-and-conditions/no/-----.pdf",
               "accountTerms" : "https://www.payex.com/term-and-conditions/no/-----.pdf"
            },
           "@id" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-2",
        }
    ],
   "@id": "/ledger/credit-account-onboarding/v1/XXX/offers",
   "view": {
       "@id": "/ledger/credit-account-onboarding/v1/XXX/offers?$top=2&$skip=0",
       "next": "/ledger/credit-account-onboarding/v1/XXX/offers?$top=2&$skip=2"
    }
}

Offers Resource

Response

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

{
   "accountProfile" : "kontotyp-1000",
   "title" : "kontotyp 1,000",
   "currency" : "NOK",
   "maxCreditLimit" : 50000.00,
   "interestFreePurchaseMonth" : true|false,
   "monthlyAdminFee" : 35.00,
   "reminderFee" : 35.00,
   "interest" : 35.00,
   "termsAndConditions" :
    {
       "standardEuropeeanAgreements" : "https://www.payex.com/term-and-conditions/no/-----.pdf",
       "accountTerms" : "https://www.payex.com/term-and-conditions/no/-----.pdf"
    },
   "@id" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-1000",
   "operations" :
        [
            {
               "rel" : "apply-for-account",
               "href" : "/ledger/credit-account-onboarding/v1/XXX/offers/kontotyp-1000/applications",
               "method" : "POST"
            }
        ]
}

Resource properties

Property	Data type	Format
@id	string	Uri
accountProfile	string	Maxlength: 50
title	string	Maxlength: 50
currency	string	ISO 4217
maxCreditLimit	decimal
interestFreePurchaseMonth	bool	ISO 8601
monthlyAdminFee	decimal
reminderFee	decimal
termsAndConditions.standardEuropeeanAgreements	string	Uri
termsAndConditions.accountTerms	string	Uri

Applications

Add application to offer

Request

POST /ledger/credit-account-onboarding/v1/XXX/offers/YYY/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/credit-account-onboarding/v1/XXX/offers/YYY/applications HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Get a single application

Request

GET /ledger/credit-account-onboarding/v1/XXX/offers/YYY/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

Property	Data type	Required in post	Format	Description
@id	string	-	Maxlength:
nationalConsumerIdentifier.value	string	Yes	YYYYMMDD-NNNC	A valid swedish "personnummer"
nationalConsumerIdentifier.countryCode	string	Yes	ISO 3166-1 alpha-2
status	string	-	Maxlength: 25	AwaitingSign InitializedSigning Approved Rejected SigningFailed
customerNo	string	Yes	Maxlength: 15
creditLimit	decimal	Yes
emailAddress	string	Yes	Maxlength: 254 Regex pattern: [^@]+@[^\.]+\..+
cellPhone	string	Yes	Maxlength: 15
ipAddress	string	No	Maxlength: 43 Regex pattern: [a-z0-9.:/]*
legalAddress.name	string	Yes	Maxlength: 72	end-customer fullname
legalAddress.streetAddress	string	No	Maxlength: 35
legalAddress.city	string	Yes	Maxlength: 30
legalAddress.coAddress	string	No	Maxlength: 35
legalAddress.zipCode	string	Yes	Maxlength: 15	ZipCode without whitespaces
legalAddress.countryCode	string	Yes	ISO 3166-1 alpha-2
account	string	-	Uri	Reference to created account
kyc	object	Yes		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.questions	list of objects	Yes
kyc.questions.code	string	Yes		The code definition of the question
kyc.questions.text	string	Yes		The actual question text that was presented to the end-customer
kyc.questions.aswer.code	string	Yes		The answered code definition from the end-customer
kyc.questions.aswer.text	string	Yes		The actual displayed answertext that was presented to the customer

Sign-agreement (Operation)

Request

Request

POST /ledger/credit-account-onboarding/v1/XXX/offers/YYY/applications/NNN/sign-agreement HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

Request

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

{
"createdAccount" : "https://api.payex.com/ledger/credit-account/v1/XXX/accounts/123456",
}

Resource properties

Property	Data type	Format	Description
createdAccount	string	Uri

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.credit-account-onboarding.validation",
  "Title" : "A validation error occurred",
  "Status" : 400,
  "Instance" : "f1f431d7-d2b2-49ca-93e0-ffe15753610a",
  "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
  "Problems" : [
      {
        "CellPhone" : "The CellPhone field is required."
      },
      {
        "EmailAddress" : "The EmailAddress field is required."
      },
      {
        "LegalAddress.Name" : "The Name field is required."
      }
   ]
}

Problem types

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

Problem type (code)	Httpstatus	Description
validation	400	occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
account-profile-exists	409	occurs if the customer already has an account with the requested account profile

credit-account

../credit-account-onboarding

Changelog

Offers

List all offers

Offers Resource

Applications

Add application to offer

List all applications

Get a single application

Applications Resource

Sign-agreement (Operation)

Request

Response

Problems

Example

Problem types