Changes for page ../credit-account

Last modified by dap on 2022/08/11 10:52
From version 2.1
edited by dap
on 2019/12/04 09:43
To version 3.1
edited by dap
on 2019/12/04 09:48
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,0 +1,298 @@
1 +(% class="jumbotron" %)
2 +(((
3 +(% class="container" %)
4 +(((
5 +Integrate to **PayEx Credit Account API **
6 +)))
7 +)))
8 +
9 +== ChangeLog ==
10 +
11 +
12 +== Glossary ==
13 +
14 +*
15 +
16 +== Introduction ==
17 +
18 +
19 +== Accounts ==
20 +
21 +
22 +{{code language="http" title="**Request**"}}
23 +GET /ledger/credit-account/v1/XXX/accounts HTTP/1.1
24 +Host: -
25 +Authorization: Bearer <Token>
26 +Content-Type: application/json
27 +{{/code}}
28 +
29 +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:
30 +
31 +{{code language="http" title="**Response**"}}
32 +HTTP/1.1 200 OK
33 +Content-Type: application/json
34 +
35 +{
36 + "sellerNumber" : "654",
37 + "invoice" : {
38 + "amountInclVat" : 100,
39 + "currency" : "SEK",
40 + "invoiceNumber" : "852",
41 + "dueDate" : "2019-06-27",
42 + "collectionReferenceText" : "Shoes",
43 + "invoiceDate" : "2019-06-07",
44 + "distributionDate" : "2019-06-08"
45 + },
46 + "buyer" : {
47 + "emailAddress" : "test@testshop.se",
48 + "cellPhone" : "+46701234456",
49 + "nationalConsumerIdentifier" : {
50 + "value" : "19101010-1010",
51 + "countryCode" : "SE"
52 + },
53 + "nationalOrganizationIdentifier" : {
54 + "value" : null,
55 + "countryCode" : null
56 + },
57 + "invoiceAddress" : {
58 + "name" : "John Smith",
59 + "streetAddress" : "Teststreet",
60 + "city" : "Testcity",
61 + "coAddress" : "",
62 + "zipCode" : "12345",
63 + "countryCode" : "SE"
64 + }
65 + },
66 + "invoicePurchaseDetails" : {
67 + "paymentReference" : "426523791",
68 + "paymentAccount" : {
69 + "accountType" : "BGSE",
70 + "accountNumber" : "1234-45",
71 + "bic" : "SWEDSESS",
72 + "iban" : "SE4550000000058398257466"
73 + },
74 + "invoiceDenuntiationText" : "Vår fordran enligt denna faktura har pantsatts till Acquirer AB ............"
75 + },
76 + "authorizationId" : 123,
77 + "@id" : "/ledger/invoice-purchase/v1/501/authorizations/123",
78 + "parentHREF": "/",
79 + "operations" : [
80 + {
81 + "rel" : "create-capture",
82 + "method" : "post",
83 + "href" : "/ledger/invoice-purchase/v1/501/authorizations/123/captures"
84 + },
85 + {
86 + "rel" : "create-credit",
87 + "method" : "post",
88 + "href" : "/ledger/invoice-purchase/v1/501/authorizations/123/credits"
89 + },
90 + {
91 + "rel" : "create-cancellation",
92 + "method" : "post",
93 + "href" : "/ledger/invoice-purchase/v1/501/authorizations/123/cancellations"
94 + }
95 + ],
96 + "captures": "/ledger/invoice-purchase/v1/501/authorizations/123/captures",
97 + "credits" : "/ledger/invoice-purchase/v1/501/authorizations/123/credits",
98 + "cancellations" : "/ledger/invoice-purchase/v1/501/authorizations/123/cancellations"
99 +}
100 +{{/code}}
101 +
102 +**Resource properties**
103 +
104 +(% class="table-bordered table-striped" %)
105 +|=Property|=Data type|=Format|=Required in post|=Description
106 +|##sellerNumber##|##string##|Maxlength: 15|Y|The identifier of the specific seller in the acquirer system
107 +|##invoice.amountInclVat##|##decimal##|N.NN|Y|The amount including VAT, always two decimals
108 +|##invoice.currency##|##string##|[[ISO 4217>>https://sv.wikipedia.org/wiki/ISO_4217]]|Y|The currency of the invoice ("SEK" etc.)
109 +|##invoice.invoiceNumber##|##string##|Maxlength: 50
110 +[A-Za-z0-9\-]+|Y|A unique reference from the seller system. It must be unique within each seller.
111 +|##invoice.dueDate##|##string##|[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Y|Example: "2019-06-04"
112 +|##invoice.collectionReferenceText##|##string##|Maxlength: 50|Y|
113 +|##invoice.invoiceDate##|##string##|[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Y|Example: "2019-06-04"
114 +|##invoice.distributionDate##|##string##|[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Y|Example: "2019-06-04"
115 +|buyer##.emailAddress##|##string##|Maxlength: 60
116 +[^@]+@[^\.]+\..+| |
117 +|buyer##.cellPhone##|##string##|Maxlength: 20| |Example: "+46701234567"
118 +|buyer##.nationalConsumerIdentifier.value##|##string##|YYYYMMDD-NNNC|Y*|A valid swedish "personnummer"
119 +|buyer##.nationalConsumerIdentifier.countryCode##|##string##|[[ISO 3166-1 alpha-2>>https://sv.wikipedia.org/wiki/ISO_3166]]|Y*|The countrycode of the identifiers nationality, ("SE")
120 +|buyer##.nationalOrganizationIdentifier.value##|##string##|NNNNNN-NNNC|Y*|A valid swedish "organisationsnummer"
121 +|buyer##.nationalOrganizationIdentifier.countryCode##|##string##|[[ISO 3166-1 alpha-2>>https://sv.wikipedia.org/wiki/ISO_3166]]|Y*|The countrycode of the identifiers nationality, ("SE")
122 +|buyer##.invoiceAddress.name##|##string##|Maxlength: 72|Y|
123 +|buyer##.invoiceAddress.streetAddress##|##string##|Maxlength: 35|Y|
124 +|buyer##.invoiceAddress.city##|##string##|Maxlength: 30|Y|
125 +|buyer##.invoiceAddress.coAddress##|##string##|Maxlength: 35|Y|
126 +|buyer##.invoiceAddress.zipCode##|(% style="font-family:monospace" %)string|Maxlength: 9|Y|
127 +|buyer##.invoiceAddress.countryCode##|##string##|[[ISO 3166-1 alpha-2>>https://sv.wikipedia.org/wiki/ISO_3166]]|Y|Example: "SE"
128 +|##invoicePurchaseDetails.paymentReference##|##string##|Maxlength: 50|No, output only|Generated paymentreference
129 +|##invoicePurchaseDetails.paymentAccount.accountType##|##string##|Maxlength: 4|No, output only|Type of account, eg. BankGiro: "BGSE"
130 +|##invoicePurchaseDetails.paymentAccount.accountNumber##|##string##|Maxlength: 15|No, output only|
131 +|##invoicePurchaseDetails.paymentAccount.bic##|##string##|Maxlength: 11|No, output only|
132 +|##invoicePurchaseDetails.paymentAccount.iban##|##string##|Maxlength: 34|No, output only|
133 +|##invoicePurchaseDetails.invoiceDenuntiationText##|##string##|Maxlength: 800|No, output only|Legal text to print on invoice to buyer, informs about the invoice transferred to the acquirer.
134 +|##authorizationId##|##number
135 +(long)##|[[64-bit integer>>https://en.wikipedia.org/wiki/9,223,372,036,854,775,807]]|No, output only|identifier of the created authorization
136 +
137 +(% class="wikigeneratedid" %)
138 +(% class="small" %)##//* Either buyer.nationalConsumerIdentifier or buyer.nationalOrganizationIdentifier must be specified in the request//##
139 +
140 +== Captures ==
141 +
142 +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.
143 +
144 +[[image:InvoicePurchase external - Capture.svg||height="443" width="844"]]
145 +
146 +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
147 +
148 +{{code language="http" title="**Request**"}}
149 +POST /ledger/invoice-purchase/v1/XXX/authorization/123/captures HTTP/1.1
150 +Host: -
151 +Authorization: Bearer <Token>
152 +Content-Type: application/json
153 +
154 +{
155 + "invoicePdfData" : ""
156 +}
157 +{{/code}}
158 +
159 +**Request properties**
160 +
161 +(% class="table-bordered table-striped" %)
162 +|=Property|=Data type|=Required in post|=Format|=Description
163 +|##invoicePdfData##|##string##|Y|Base64 encoded byte array|data of the valid pdf document/invoice
164 +
165 +If the capture succeeds, it should respond with http status 204
166 +
167 +{{code language="http" title="**Response**"}}
168 +HTTP/1.1 201 Created
169 +Content-Type: application/json
170 +
171 +{
172 +}
173 +{{/code}}
174 +
175 +== Cancellations ==
176 +
177 +The reservation must be cancelled if the seller aborts the process (for any reason) after a successful call to ##authorizations## has been made.
178 +This is done by sending a request to the ##cancellation## URL that was provided in the response of the actual authorization call.
179 +
180 +An already captured authorization cannot be cancelled.
181 +
182 +[[image:InvoicePurchase external - Cancel.svg||height="443" width="844"]]
183 +
184 +To cancel an authorization (with authorizationId 123 in the example below), we need to perform a post request as below
185 +
186 +{{code language="http" title="**Request**"}}
187 +POST /ledger/invoice-purchase/v1/XXX/authorizations/123/cancellations HTTP/1.1
188 +Host: -
189 +Authorization: Bearer <Token>
190 +Content-Type: application/json
191 +{{/code}}
192 +
193 +If the cancellation succeeds, it should respond with http status 200
194 +
195 +{{code language="http" title="**Response**"}}
196 +HTTP/1.1 201 Created
197 +Content-Type: application/json
198 +{{/code}}
199 +
200 +== Credits ==
201 +
202 +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.
203 +
204 +[[image:InvoicePurchase external - Credit.svg||height="443" width="844"]]
205 +
206 +To credit a captured authorization (with authorizationId 123 in the example below) we need to perform a post request as below
207 +
208 +{{code language="http" title="**Request**"}}
209 +POST /ledger/invoice-purchase/v1/XXX/authorization/123/credits HTTP/1.1
210 +Host: -
211 +Authorization: Bearer <Token>
212 +Content-Type: application/json
213 +
214 +{
215 + "amountInclVat" : 100
216 +}
217 +{{/code}}
218 +
219 +If the credit succeeds, it should respond with something like the following:
220 +
221 +{{code language="http" title="**Response**"}}
222 +HTTP/1.1 201 Created
223 +Content-Type: application/json
224 +
225 +{
226 + "amountInclVat" : 100,
227 + "creditedAmount" : 100,
228 + "@id" : "/ledger/invoice-purchase/v1/501/authorizations/credits/456",
229 + "parentHREF": "/ledger/invoice-purchase/v1/501/authorizations/123"
230 +}
231 +{{/code}}
232 +
233 +**Resource properties**
234 +
235 +(% class="table-bordered table-striped" %)
236 +|=Property|=Data type|=Format|=Required in post|=Description
237 +|##amountInclVat##|##decimal##|N.NN|Y|Amount (including VAT) to credit, always two decimals
238 +|##creditedAmount##|##decimal##|N.NN| |The actual amount that was credited, always two decimals
239 +
240 +== Problems ==
241 +
242 +If an error occur or any validation failed, a "problem" response will be returned.
243 +Below is a list of problems that can occur:
244 +
245 +**HttpStatus 401 Unauthorized**
246 +
247 +* Token expired
248 +* Token invalid
249 +* SellerNumber does not match token
250 +* CompanyNumber does not match token
251 +
252 +**HttpStatus 400 Error**
253 +
254 +* Validation: Argument required
255 +* Validation: Invalid value
256 +
257 +**HttpStatus 422 Unprocessable entity**
258 +
259 +* Authorization declined
260 +
261 +**HttpStatus 409 Conflict**
262 +
263 +* Invoice already authorized
264 +* Duplicate InvoiceNumber
265 +* Authorization is cancelled
266 +* Authorization already captured
267 +* Authorization has expired
268 +* Insufficient debited amount XXX
269 +
270 +**HttpStatus 501 NotImplemented**
271 +
272 +* CompanyNumber XXX not configured
273 +* SellerNumber XXX not configured at PayEx
274 +* CompanyNumber XXX missing configuration
275 +
276 +**HttpStatus 404 NotFound**
277 +
278 +* Authorization not found
279 +
280 +Below is an example of a problem that will be returned if buyer##.nationalConsumerIdentifier.value## is not valid in the authorization post request.
281 +
282 +{{code language="http" title="**Response**"}}
283 +HTTP/1.1 400 Error
284 +Content-Type: application/problem+json
285 +
286 +{
287 + "Type": "http://[DNS]/ledger/invoice-purchase/problems/validation",
288 + "Title": "A validation error occurred",
289 + "Status": 400,
290 + "Instance": null,
291 + "Detail": "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
292 + "Problems": [
293 + {
294 + "buyer.nationalConsumerIdentifier.value": "Not a valid SE nationalConsumerIdentifier"
295 + }
296 + ]
297 +}
298 +{{/code}}