PayEx Developer Portal - ../credit-account

Integrate to PayEx Credit Account API

ChangeLog

Glossary

Introduction

Accounts

Request

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

If the authorization post succeeds, or if a get method is performed to retrieve an existing authorization, it should respond with something like the following:

Response

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

{
   "@id": "/ledger/credit-account/v1/501/accounts/123456",
   "accountNo": "1234567",
   "startDate": "2016-05-21",
   "description": null,
   "accountProfileType": "strex | kontodebet | kontokredit | kontofaktura", //Nytt begrepp
   "accountAlias" : "Coop kontokredit | Coop matkonto",
   "customerNo" : "123789654",
   "status" : "open | pending-close | closed",
   "creditLimit": 2000.00, // Kontots kreditlimit
   "unpaidBilledAmount" : 200.0, //total aktuell summa av alla balanser på BillingAcc (endast om negativ/skuld, annars 0)
   "debt": 2050.0, // total aktuell summa av alla balanser (kapital/ränta/avgifter osv.) på BillingAcc + underliggande CredAccs, OM NEGATIV (skuld)
   "surplus": 0.0, // total aktuell summa av alla balanser (kapital/ränta/avgifter osv.) på BillingAcc + underliggande CredAccs, OM POSITIV (tillgodo)
   "reservedAmount": 50.0, // Summerat belopp på alla utestående reservationer mot kontot (som är giltiga och ej captured)
   "availableAmount": 100.0, // Tillgänglig kredit (kan ej räknas fram utifrån ovan belopp då avgifter kan ingå där, som inte påverkar tillgänglig kredit)
   "openBill" : {
       "amount" : 250.0,
       "bill" : "/ledger/credit-account/v1/501/accounts/123456/bills/963",
       "dueDate" : "2019-10-10",
       "billType" : "Bill"
    },
   "charityDonation": true,
   "interestRate": {
       "debtInterest" : 10.00,
       "penaltyInterest": 15.00
    },
   "offer" : "", //nödvändig??
   "directDebit": "/ledger/credit-account/v1/501/accounts/123456/direct-debit",
   "cards": "/ledger/credit-account/v1/501/accounts/123456/cards",
   "transactions": "/ledger/credit-account/v1/501/accounts/123456/transactions",
   "currency": "sek",
   "bills": "/ledger/credit-account/v1/501/accounts/123456/bills",
   "customer": "/ledger/customers/v1/501/customer/123456",
   "operation" : [
        {
           "rel" : "add-card-info",
           "method" : "post",
           "href" : "/ledger/credit-account/v1/501/accounts/123456/cards"
        },
        {
           "rel" : "request-close-account", // -> pending-close status (workitem för stängning)
           "method" : "post",
           "href" : "/ledger/credit-account/v1/501/accounts/123456/request-close-account"
        },
        {
           "rel" : "apply-for-raised-credit-limit",
           "method" : "post",
           "href" : "/ledger/credit-account-onboardings/v1/501/accounts/123456/apply-for-raised-credit-limit"
        },
        {
           "rel" : "lower-credit-limit",
           "method" : "patch",
           "href" : "/ledger/credit-account-onboardings/v1/501/accounts/123456"
        },
        {
           "rel" : "change-charity-donation",
           "method" : "patch",
           "href" : "/ledger/credit-account-onboardings/v1/501/accounts/123456"
        }
    ]
}

Resource properties

Property	Data type	Format	Required in post	Description
sellerNumber	string	Maxlength: 15	Y	The identifier of the specific seller in the acquirer system
invoice.amountInclVat	decimal	N.NN	Y	The amount including VAT, always two decimals
invoice.currency	string	ISO 4217	Y	The currency of the invoice ("SEK" etc.)
invoice.invoiceNumber	string	Maxlength: 50 [A-Za-z0-9\-]+	Y	A unique reference from the seller system. It must be unique within each seller.
invoice.dueDate	string	ISO 8601	Y	Example: "2019-06-04"
invoice.collectionReferenceText	string	Maxlength: 50	Y
invoice.invoiceDate	string	ISO 8601	Y	Example: "2019-06-04"
invoice.distributionDate	string	ISO 8601	Y	Example: "2019-06-04"
buyer.emailAddress	string	Maxlength: 60 [^@]+@[^\.]+\..+
buyer.cellPhone	string	Maxlength: 20		Example: "+46701234567"
buyer.nationalConsumerIdentifier.value	string	YYYYMMDD-NNNC	Y*	A valid swedish "personnummer"
buyer.nationalConsumerIdentifier.countryCode	string	ISO 3166-1 alpha-2	Y*	The countrycode of the identifiers nationality, ("SE")
buyer.nationalOrganizationIdentifier.value	string	NNNNNN-NNNC	Y*	A valid swedish "organisationsnummer"
buyer.nationalOrganizationIdentifier.countryCode	string	ISO 3166-1 alpha-2	Y*	The countrycode of the identifiers nationality, ("SE")
buyer.invoiceAddress.name	string	Maxlength: 72	Y
buyer.invoiceAddress.streetAddress	string	Maxlength: 35	Y
buyer.invoiceAddress.city	string	Maxlength: 30	Y
buyer.invoiceAddress.coAddress	string	Maxlength: 35	Y
buyer.invoiceAddress.zipCode	string	Maxlength: 9	Y
buyer.invoiceAddress.countryCode	string	ISO 3166-1 alpha-2	Y	Example: "SE"
invoicePurchaseDetails.paymentReference	string	Maxlength: 50	No, output only	Generated paymentreference
invoicePurchaseDetails.paymentAccount.accountType	string	Maxlength: 4	No, output only	Type of account, eg. BankGiro: "BGSE"
invoicePurchaseDetails.paymentAccount.accountNumber	string	Maxlength: 15	No, output only
invoicePurchaseDetails.paymentAccount.bic	string	Maxlength: 11	No, output only
invoicePurchaseDetails.paymentAccount.iban	string	Maxlength: 34	No, output only
invoicePurchaseDetails.invoiceDenuntiationText	string	Maxlength: 800	No, output only	Legal text to print on invoice to buyer, informs about the invoice transferred to the acquirer.
authorizationId	number (long)	64-bit integer	No, output only	identifier of the created authorization

* Either buyer.nationalConsumerIdentifier or buyer.nationalOrganizationIdentifier must be specified in the request

Bills

List bills

Request

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

Response

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

{
   "bills" : [
        { "billDate" : "2018-09-01", "status" : "open", "billAmount" : 374.10, "@id" : "/ledger/credit-account/v1/501/accounts/123456/bills/963" },
        { "billDate" : "2018-08-01", "status" : "closed", "billAmount" : 374.10, "@id" : "/ledger/credit-account/v1/501/accounts/123456/bills/852" },
        { "billDate" : "2018-07-01", "status" : "closed", "billAmount" : 374.10, "@id" : "/ledger/credit-account/v1/501/accounts/123456/bills/741" }
    ]
}

Bill resource

Request

GET /ledger/credit-account/v1/XXX/accounts/123/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/501/accounts/123456/bills/963",
   "externalReference": "123456",
   "dueDate": "2018-12-05",
   "billNo": "124645",
   "amountToBePayed": 240.00, //kan inte denna heta bara "amount" egentligen?
   "billType" : "Bill",
   "bankPayment": {
       "bankAccountNo": "123",
       "bankAccountType": "BGSE",
       "bic": "123456",
       "iban": "SE12345678945631",
       "paymentReference": "1246fdsdf4687613"
    },
   "activePaymentOrder": {
       "paymentType": "BGAGSE",
       "executionDate": "2019-01-01",
       "amount" : 200.0 //beroende på directdebittype så kan denna vara beräknad vid varje hämtning (utifrån ev. delbet)
    },
   "pdf": "/ledger/credit-account/v1/501/accounts/123456/bills/963/pdf" //visar senaste ev. childbill?
}

direct-debit

Request

POST /ledger/credit-account/v1/XXX/accounts/123/direct-debit 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/123456/direct-debit",
   "directDebitType" : "fixedRecurring | totalDebt | billedAmount | onDemand",
   "fixedRecurringAmount" : 1500.00,
   "parentHREF": "/ledger/credit-account/v1/501/accounts/123456"
}

Credits

To credit an existing invoice you first need retreive the specific authorization resource (get request). If the authorization has been captured and is valid for crediting the response will contain an URL to the credits resource. To complete the credit you need to call this URL with a post request containing the credit details.

InvoicePurchase external - Credit.svg

To credit a captured authorization (with authorizationId 123 in the example below) we need to perform a post request as below

Request

POST /ledger/invoice-purchase/v1/XXX/authorization/123/credits HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"amountInclVat" : 100
}

If the credit succeeds, it should respond with something like the following:

Response

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

{
   "amountInclVat" : 100,
   "creditedAmount" : 100,
   "@id" : "/ledger/invoice-purchase/v1/501/authorizations/credits/456",
   "parentHREF": "/ledger/invoice-purchase/v1/501/authorizations/123"
}

Resource properties

Property	Data type	Format	Required in post	Description
amountInclVat	decimal	N.NN	Y	Amount (including VAT) to credit, always two decimals
creditedAmount	decimal	N.NN		The actual amount that was credited, always two decimals

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

credit-account

../credit-account

ChangeLog

Glossary

Introduction

Accounts

Bills

List bills

Bill resource

direct-debit

Credits

Problems

Applications

Navigation

Tips

Need help?