../credit-account
Integrate to PayEx Credit Account API
ChangeLog
Glossary
Introduction
Accounts
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:
Content-Type: application/json
{
"sellerNumber" : "654",
"invoice" : {
"amountInclVat" : 100,
"currency" : "SEK",
"invoiceNumber" : "852",
"dueDate" : "2019-06-27",
"collectionReferenceText" : "Shoes",
"invoiceDate" : "2019-06-07",
"distributionDate" : "2019-06-08"
},
"buyer" : {
"emailAddress" : "test@testshop.se",
"cellPhone" : "+46701234456",
"nationalConsumerIdentifier" : {
"value" : "19101010-1010",
"countryCode" : "SE"
},
"nationalOrganizationIdentifier" : {
"value" : null,
"countryCode" : null
},
"invoiceAddress" : {
"name" : "John Smith",
"streetAddress" : "Teststreet",
"city" : "Testcity",
"coAddress" : "",
"zipCode" : "12345",
"countryCode" : "SE"
}
},
"invoicePurchaseDetails" : {
"paymentReference" : "426523791",
"paymentAccount" : {
"accountType" : "BGSE",
"accountNumber" : "1234-45",
"bic" : "SWEDSESS",
"iban" : "SE4550000000058398257466"
},
"invoiceDenuntiationText" : "Vår fordran enligt denna faktura har pantsatts till Acquirer AB ............"
},
"authorizationId" : 123,
"@id" : "/ledger/invoice-purchase/v1/501/authorizations/123",
"parentHREF": "/",
"operations" : [
{
"rel" : "create-capture",
"method" : "post",
"href" : "/ledger/invoice-purchase/v1/501/authorizations/123/captures"
},
{
"rel" : "create-credit",
"method" : "post",
"href" : "/ledger/invoice-purchase/v1/501/authorizations/123/credits"
},
{
"rel" : "create-cancellation",
"method" : "post",
"href" : "/ledger/invoice-purchase/v1/501/authorizations/123/cancellations"
}
],
"captures": "/ledger/invoice-purchase/v1/501/authorizations/123/captures",
"credits" : "/ledger/invoice-purchase/v1/501/authorizations/123/credits",
"cancellations" : "/ledger/invoice-purchase/v1/501/authorizations/123/cancellations"
}
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
Captures
If the seller decides to proceed with the process and let the acquirer purchase the invoice, a call to captures must be made. A post request is sent to the specific capture URL (that was provided in the authorization resource response), the request must contain the actual PDF of the invoice that is to be distributed to the buyer.
To capture the authorization (with authorizationId 123 in the example below) and complete the invoice purchase, we need to perform a post request as below
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"invoicePdfData" : ""
}
Request properties
| Property | Data type | Required in post | Format | Description |
|---|---|---|---|---|
| invoicePdfData | string | Y | Base64 encoded byte array | data of the valid pdf document/invoice |
If the capture succeeds, it should respond with http status 204
Content-Type: application/json
{
}
Cancellations
The reservation must be cancelled if the seller aborts the process (for any reason) after a successful call to authorizations has been made.
This is done by sending a request to the cancellation URL that was provided in the response of the actual authorization call.
An already captured authorization cannot be cancelled.
To cancel an authorization (with authorizationId 123 in the example below), we need to perform a post request as below
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
If the cancellation succeeds, it should respond with http status 200
Content-Type: application/json
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.
To credit a captured authorization (with authorizationId 123 in the example below) we need to perform a post request as below
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"amountInclVat" : 100
}
If the credit succeeds, it should respond with something like the following:
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.
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"
}
]
}