## credit-account

# ../credit-account

Integrate to PayEx Credit Account API

Todo: Saknar operation för att hitta konton som tillhör en person/ett personnummer

# Changelog

2020-01-31
renamed resource "recurring-payment-consent" to "recurring-payment-setting" (not implemented in API yet)

This api is used to retrieve information and to change properties related to the customer's credit account.

## Introduction

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Route segment | Description
--- | ---
Subdomain | In this part of the API it will be credit-account
LedgerNumber | The ledger identifier/number at PayEx
resource1Id | Identifier of resource1
resource2Id | identifier of resource2, subresource to resource1
resource3Id | identifier of resource3, subresource to resource2

Routes that occurs in examples of this documentation will use the following identifiers

Resource | Identifier
--- | ---
LedgerNumber | XXX
Accounts | NNN
Bills | reminder-123 bill-456
Cards | 954c8699-b38f-47a2-b568-668b8837dad8 274c8699-b38f-47a2-b568-668b8837dat7

## Accounts

The accounts resource is located under ledger/credit-account/v1/ api. The accounts- and its sub-resources are used to create, read and modify information related to a credit-account.
The accounts resource provides an overview of the end customer's account, it contains information such as current balance, credit limit etc. The resource also contains URIs for additional sub-resources such as bills, cards, recurring payments, etc.
The following operations is supported

- Change the account credit limit
- Add extra cards
- Request cancellation of account
- Turn on/off charity donation
- Set behaviour of recurring payments

### Requesting details of a specific account

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN", "accountNo": "1234567", "startDate": "2018-05-21", "description": null, "accountProfileType": "accountType1 | accountType2 | accountType3 etc.", "accountAlias" : "accountAlias1 | accountAlias2 etc.", "customerNo" : "123789654", "status" : "open | pending-close | closed", "creditLimit": 2000.00, "totalBalance" : -1900.0, "reservedAmount": 50.0, "availableAmount": 50.0, "openBill" : "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-456", "charityDonation": true, "interestRate": { "debtInterest" : 10.00, "penaltyInterest": 15.00 }, "bankPayment": { "bankAccountNo": "123", "bankAccountType": "BGSE", "bic": "123456", "iban": "SE12345678945631", "paymentReference": "54867165675646" }, "activePaymentOrders": "/ledger/credit-account/v1/XXX/accounts/NNN/active-payment-orders", "recurringPaymentConsent": "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-setting", "cards": "/ledger/credit-account/v1/XXX/accounts/123456/cards", "transactions": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions", "currency": "sek", "bills": "/ledger/credit-account/v1/XXX/accounts/NNN/bills", "customer": "/ledger/customers/v1/XXX/customer/123456", "operation" : [ { "rel" : "add-card-info", "method" : "post", "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/cards" }, { "rel" : "request-close-account", "method" : "post", "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/request-close-account" }, { "rel" : "apply-for-raised-credit-limit", "method" : "post", "href" : "/ledger/credit-account-onboardings/v1/XXX/accounts/NNN/apply-for-raised-credit-limit" }, { "rel" : "partial-update", "method" : "patch", "href" : "/ledger/credit-account-onboardings/v1/XXX/accounts/NNN" } ] }

Resource properties

Property | Data type | Format | Modify (patch) | Description
--- | --- | --- | --- | ---
@id | string | Maxlength: |  | Uri of the specific account
accountNo | string | Maxlength: 50 |  | The identifier of the account
startDate | date | ISO 8601 |  | Date when the account was started
description | string | Maxlength: 200 |  | A description of the type of account
accountProfileType | string | Maxlength: 50 |  | The defined code of the accounttype, Examples: kontodebet, kontokredit, kontofaktura
accountAlias | string | Maxlength: 50 |  | A descriptive name for the account type, Examples: kontokredit1, matkonto1
customerNo | string | Maxlength: 50 |  | Identifier of the customer (account owner)
status | string | Maxlength: 25 |  | Status of the account pending-close: the customer has requested the account to be closed, the account will be closed when possible. open: the account is open and active closed: the account has been closed
creditLimit | decimal |  |  | The creditlimit of the account, support patch operation but only lower
totalBalance | decimal |  |  | Total current sum of all balances (including capital / interest / fees, etc.)
reservedAmount | decimal |  |  | Sum of all outstanding reservations (which are valid and not captured)
availableAmount | decimal |  |  | Available credit (cannot be calculated from the above amounts as fees can be included there, which does not affect available credit)
openBill | string | Uri |  |
charityDonation | bool |  |  | If donations should be made from the account
interestRate.debtInterest | decimal | Percentage |  | yearly debt interestrate
interestRate.penaltyInterest | decimal | Percentage |  | yearly penalty interestrate
offer | string | Uri |  |
recurringPaymentConsent | string | Uri |  |
cards | string | Uri |  |
transactions | string | Uri |  |
currency | string | ISO 4217 |  |
bills | string | Uri |  |
customer | string | Uri |  |
activePaymentOrder.paymentMethod | string | Maxlength: 15 |  | PaymentTypes: AUTOGIRO
activePaymentOrder.executionDate | date | ISO 8601 |  | Date when the paymentorder will be executed (when end-customer will be debited)
activePaymentOrder.amount | decimal |  |  | Amount that will be charged, this amount may be adjusted when the payment order is executed, if the "amount to pay" on the bill has decreased

### Bills

The bills resources contains all the documents produced in the accounts billing cycle.

#### Requesting list of bills belonging to a specific account

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/bills HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "@id": "/ledger/credit-account/v1/501/accounts/NNN/bills?status=open", "items" : [ { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-123645", "dueDate": "2018-12-05", "billDate": "2018-11-15", "billNo": "124645", "billAmount": 240.00, "billType" : "reminder", "status": "open", "activePaymentDetails": { "minimumAmountToBePayed": 240.00, "bankAccountNo": "123", "bankAccountType": "BGSE", "bic": "123456", "iban": "SE12345678945631", "paymentReference": "5465164654663", "paymentOrdersExists": true, }, "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document" }, { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-123645", "dueDate": "2018-12-05", "billDate": "2018-11-15", "billNo": "124645", "billAmount": 240.00, "billType" : "bill", "status": "closed", "activePaymentDetails": null, "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document" }, { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/bill-123645", "dueDate": "2018-12-05", "billDate": "2018-11-15", "billNo": "124645", "billAmount": 240.00, "billType" : "bill", "status": "closed", "activePaymentDetails": null, "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document" } ] }

####

#### Requesting details of a specific bill

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/bills/456 HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-123645", "dueDate": "2018-12-05", "billDate": "2018-11-15", "billNo": "124645", "billAmount": 240.00, "billType" : "reminder", "status": "open", "activePaymentDetails": { "minimumAmountToBePayed": 240.00, "bankAccountNo": "123", "bankAccountType": "BGSE", "bic": "123456", "iban": "SE12345678945631", "paymentReference": "5465164654663", "paymentOrdersExists": true, }, "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document" }

##

Property | Data type | Format | Description
--- | --- | --- | ---
@id | string | Uri |
dueDate | date | ISO 8601 |
billDate | date |  | Date when bill was created
billNo | string | Maxlength: 50 | The identifier of the bill
billAmount | decimal |  | the amount that is stated on the actual bill/document
billType | string | Maxlength: 25 | BillTypes: Bill Reminder1 Reminder2 Collection
status | string |  | "open" / "closed"
activePaymentDetails | object |  | only set if status of bill is "open"
activePaymentDetails.minimumAmountToBePayed | decimal |  | The least amount to pay on the bill
activePaymentDetails.bankAccountNo | string | Maxlength: 15 | bankaccount for payment
activePaymentDetails.bankAccountType | string | Maxlength: 10 | BankAccountTypes: BKSE (swedish bankaccount) PKSE (swedish plusgiro) BGSE (swedish bankgiro) PGSE (swedish plusgiro OCR)
activePaymentDetails.bic | string | Maxlength: 11 | Bank Identifier Code (BIC)
activePaymentDetails.iban | string | Maxlength: 34 | International Bank Account Number (IBAN)
activePaymentDetails.paymentReference | string | Maxlength: 50 | reference to specify on the payment
activePaymentDetails.paymentOrdersExists | bool |  | if there is an active payment order to be executed related to this bill for "recurring payments". More detailed information about the payment order can be found on the accounts resource
document | string | Url | Url to download pdf document

###

### recurring-payment-setting

This resource contain information/settings related to how recurring payments should behave on this account.

#####
Requesting the resource

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-setting/ HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "@id" : "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-setting", "recurringPaymentMethod" : "autogiro", "recurringPaymentScope" : "fixedRecurring", "fixedRecurringAmount" : 1500.00, "parentHREF": "/ledger/credit-account/v1/XXX/accounts/NNN", "operation" : [ { "rel" : "partially-update-recurring-payment-consent", "method" : "patch", "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-consent" } ] }

##### Update settings

Execute http patch towards this resource to change how recurring payments should behave on the specified account

Request
PATCH /ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-setting HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json { "recurringPaymentScope" : "billedAmount", "fixedRecurringAmount" : 0.00 }

Property | Data type | Format | Modify (patch) | Description
--- | --- | --- | --- | ---
recurringPaymentMethod | string |  |  | recurringPaymentMethods: autogiro
recurringPaymentScope | string |  |  | recurringPaymentScopes: fixedRecurring (Fixed amount to debit monthly) totalDebt (Total credit-account debt will be debited) billedAmount (Only the minimum amount to pay will be debited)
fixedRecurringAmount | decimal |  |  | amount to monthly debit end-customers bankaccount (Only valid if recurringPaymentScope is set to "fixedRecurring")

### Cards

#### Post

Execute http post towards this resource to add a new card to the specified account

Request
POST /ledger/credit-account/v1/XXX/accounts/NNN/cards HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json { "token": "954c8699-b38f-47a2-b568-668b8837dad8", "PanTrunc": "85479*********648", "deleted" : false, "mainCard": true, "cardHolder" : { "number" : "123465", "name": "test testsson", "nationalConsumerIdentifier": { "value": "19101010-1010", "countryCode": "SE" } } }

#### List cards

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/cards HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "operations": null, "items": [ { "token": "954c8699-b38f-47a2-b568-668b8837dad8", "PanTrunc": "85479*********648", "deleted" : false, "mainCard": true, "cardHolder" : { "number" : "123465", "name": "test testsson", "nationalConsumerIdentifier": { "value": "19101010-1010", "countryCode": "SE" } }, "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards/741" }, { "token": "274c8699-b38f-47a2-b568-668b8837dat7", "PanTrunc": "78979*********321", "deleted" : false, "mainCard": false, "cardHolder" : { "number" : "987654", "name": "test testsson", "nationalConsumerIdentifier": { "value": "19101010-1010", "countryCode": "SE" } }, "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards/274c8699-b38f-47a2-b568-668b8837dat7" } ], "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards", "view": { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards?$top=2&$skip=0", "next": "/ledger/credit-account/v1/XXX/accounts/NNN/cards?$top=2&$skip=2" } }

#### Get

Response
HTTP/1.1 200 OK Content-Type: application/json { "token": "954c8699-b38f-47a2-b568-668b8837dad8", "PanTrunc": "85479*********648", "deleted" : false, "mainCard": true, "cardHolder" : { "number" : "123465", "name": "test testsson", "nationalConsumerIdentifier": { "value": "19101010-1010", "countryCode": "SE" } }, "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8", "parentHREF": "/ledger/credit-account/v1/XXX/accounts/NNN", "operation" : [ { "rel" : "partial-update", "method" : "patch", "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8" } ] }

Property | Data type | Format | Modify (patch) | Description
--- | --- | --- | --- | ---
token | string |  |  | token identifier of the card
panTrunc | string |  |  | truncated PAN
deleted | bool |  |  | indicates wheter the card has been deleted
mainCard | bool |  |  | indicated whether this card is the main card of the account (cardholder is always owner of account)
cardHolder.number | string |  |  | Cardholder customernumber
cardHolder.name | string |  |  | Cardholder fullname
cardHolder.nationalConsumerIdentifier.value | string | YYYYMMDD-NNNC |  |
cardHolder.nationalConsumerIdentifier.countryCode | string | ISO 3166-1 alpha-2 |  |

### Transactions

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/transactions HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "operations": null, "items": [ { "type": "payment", "description": "", "amount": 200.00, "billed": false|true, "date": "2019-10-09", "reserveDate": null }, { "type": "purchase", "description": "testbutiken, köpref. 12345689", "amount": 200.00, "billed": false|true, "date": "2019-10-09", "reserveDate": "2019-10-05", }, { "type": "credit", "description": "", "amount": 200.00, "billed": false|true, "date": "2019-10-09", "reserveDate": "2019-10-05" } ], "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions?fromDate=2019-10-01", "view": { "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions?fromDate=2019-10-01&$top=2&$skip=0", "next": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions?fromDate=2019-10-01&$top=2&$skip=2" } }

Property | Data type | Format | Description
--- | --- | --- | ---
type | string |  | Type of transaction Payment Purchase Credit
description | string |  | Description of the transaction, for purchases it usually includes "point of sale" and "receipt reference"
amount | decimal |  |
billed | bool |  | Indicates wheter a bill has been created after the transaction (ie. if the transaction is included in any bill or not)
date | date |  | Valuedate

### Reservations

Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/reservations HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json
Response
HTTP/1.1 201 Created Content-Type: application/json { "operations": null, "items": [ { "amount": 200.00, "description" : "", "date": "2019-10-05", }, { "amount": 450.00, "description" : "", "date": "2019-10-02", }, ], "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/reservations", }

Property | Data type | Format | Description
--- | --- | --- | ---
amount | decimal |  |
description | string |  | Description of the reservation, normally "point of sale".
date | date |  | Date when the reservation occured Problems If an error occur or any validation failed, a "problem" response will be returned. Below is a list of problems that can occur: HttpStatus 401 Unauthorized

- Token expired
- Token invalid
- SellerNumber does not match token
- CompanyNumber does not match token
  HttpStatus 400 Error
- Validation: Argument required
- Validation: Invalid value
  HttpStatus 422 Unprocessable entity
- Authorization declined
  HttpStatus 409 Conflict
- Invoice already authorized
- Duplicate InvoiceNumber
- Authorization is cancelled
- Authorization already captured
- Authorization has expired
- Insufficient debited amount XXX
  HttpStatus 501 NotImplemented
- CompanyNumber XXX not configured
- SellerNumber XXX not configured at PayEx
- CompanyNumber XXX missing configuration
  HttpStatus 404 NotFound
- Authorization not found
  Below is an example of a problem that will be returned if buyer.nationalConsumerIdentifier.value is not valid in the authorization post request.
  Response
  HTTP/1.1 400 Error Content-Type: application/problem+json { "Type": "http://[DNS]/ledger/invoice-purchase/problems/validation", "Title": "A validation error occurred", "Status": 400, "Instance": null, "Detail": "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.", "Problems": [ { "buyer.nationalConsumerIdentifier.value": "Not a valid SE nationalConsumerIdentifier" } ] }

Tags: px-custom-page-content
Created by Helge Dahl on 2020/02/06 17:55

- Comments (0)
- Attachments (4)
- Information

# Applications

# Tips

Did you know that you can improve XWiki? Take 5 minutes to fill this survey and help this open source project!

# Need help?

If you need help with XWiki you can contact:

- Community Support
- Professional Support