Summary

• Page properties (1 modified, 0 added, 0 removed)

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