Summary

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

Details

Page properties

Title

...	...	@@ -1,0 +1,1 @@
	1	+Payment Session

Parent

...	...	@@ -1,0 +1,1 @@
	1	+ecommerce.PayEx Checkout.Introduction.WebHome

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.XWikiGuest
	1	+xwiki:XWiki.hde

Default language

...	...	@@ -1,0 +1,1 @@
	1	+en

Content

...	...	@@ -1,0 +1,212 @@
	1	+**Table of contents**
	2	+
	3	+{{toc/}}
	4	+
	5	+An implementer must first perform a POST to this resource to initate the payment with an HTTP POST from your backend with payment info and your accessToken. The response from the POST will contain a payment session URL. Persist the paymentSessionUrl alongside the data representing the initial POST, be it a shopping cart, an order, or similar.
	6	+
	7	+The paymentSessionUrl returned from the POST is the base URL to request all other resources related to the [[Payment>>ecommerce.PayEx Checkout.Payment]].
	8	+
	9	+= Create Payment Session =
	10	+
	11	+To create a Payment Session, you simply perform an HTTP {{code}}POST{{/code}} request with a Payment Session JSON payload as documented below to the Payment Session URL as discovered in the Home Resource.
	12	+
	13	+This resource requires authentication as mentioned in the [[Intro>>ecommerce.PayEx Checkout.Introduction||anchor="HAuthentication"]].
	14	+
	15	+== Properties ==
	16	+
	17	+|(% style="text-align:right" %)**Property** |=Description
	18	+|(% style="text-align:right" %){{code}}amount{{/code}}
	19	+(% style="color:LightGrey" %)number
	20	+(required)|(((
	21	+The total amount of the payment (included vat and shipping).
	22	+
	23	+The amount will be verified against the amount sent in from your frontend.
	24	+)))
	25	+|(% style="text-align:right" %){{code}}vatAmount{{/code}}
	26	+(% style="color:LightGrey" %)number
	27	+(optional to vatRate)|(((
	28	+The vat amount of the the payment.
	29	+
	30	+The vat amount will be verified against the vat amount sent in from your frontend
	31	+)))
	32	+|(% style="text-align:right" %){{code}}vatRate{{/code}}
	33	+(% style="color:LightGrey" %)number
	34	+(optional to vatAmount)|(((
	35	+The vat rate of the the payment.
	36	+
	37	+The vat rate will be verified against the vat amounts sent in from your frontend. The rate supports mixed vat rates in the price list, where the final vatRate is calculated rather than a fixed/exact rate. If both vatAmount and vatRate is given, the price is calucated on the vatRate instead of using the vatAmount. The vatRate is a input variable only, where response returns a calculated vatAmount.
	38	+)))
	39	+|(% style="text-align:right" %)(((
	40	+{{code}}currency{{/code}}
	41	+(% style="color:LightGrey" %)string
	42	+(required)
	43	+)))|(((
	44	+The currency of the payment.
	45	+
	46	+The following currencies is supported by PayEx Checkout as of now: "NOK" & "SEK".
	47	+)))
	48	+|(% style="text-align:right" %){{code}}callbackUrl{{/code}}
	49	+(% style="color:LightGrey" %)string
	50	+(required)|The URL you want PayEx to perform HTTP {{code}}POST{{/code}} requests against (called callbacks) to when a Payment changes status. This URL **should** be unique per Payment Session and coupled to the order, shopping cart, or similar that you want to collect money for with PayEx Checkout.
	51	+|(% style="text-align:right" %){{code}}reference{{/code}}
	52	+(% style="color:LightGrey" %)string
	53	+(required)|The reference is a string that identifies the order, shopping cart or similar that you want to collect money for with PayEx Checkout. Must match the regular expression {{code}}^\w*${{/code}} and be no longer than 40 characters.
	54	+|(% style="text-align:right" %)(((
	55	+{{code}}culture{{/code}}
	56	+(% style="color:LightGrey" %)string
	57	+(optional)
	58	+)))|The culture you want PayEx Checkout to be presented in. Valid cultures as of now: {{code language="JavaScript"}}"nb-NO"{{/code}}, {{code language="JavaScript"}}"sv-SE"{{/code}} and {{code language="JavaScript"}}"en-US"{{/code}}. If no culture is specified, the culture will default to {{code language="JavaScript"}}"en-US"{{/code}}. It is usually best to set this to the same culture as that which the user has in the web page (web shop or similar) that initiates the PayEx Checkout user flow.
	59	+|(% style="text-align:right" %){{code}}acquire{{/code}}
	60	+(% style="color:LightGrey" %)array
	61	+(optional) |(((
	62	+This property can be set to an array of fields that you want us to acquire for you during the PayEx Checkout user flow. This information is returned to the merchant after the Payment has been authorised.
	63	+
	64	+The following parameters are valid: {{code language="JavaScript"}}["email", "mobilePhoneNumber", "shippingAddress"]{{/code}}.
	65	+)))
	66	+|(% style="text-align:right" %){{code}}payer{{/code}}
	67	+(% style="color:LightGrey" %)object
	68	+(optional) |(((
	69	+This property can be set so that PayEx Checkout in the future can pre-populate the email address and mobile phone number if the identity of the payer is known. As of now the data is not pre-populated in the frontend.
	70	+
	71	+{{code language="JavaScript"}}
	72	+{
	73	+ "email": "<emailAddress>",
	74	+ "mobilePhoneNumber": "<mobilePhoneNumber>"
	75	+}
	76	+{{/code}}
	77	+)))
	78	+|(% style="text-align:right" %){{code}}fees{{/code}}(((
	79	+(% style="color:LightGrey" %)object
	80	+(optional)
	81	+)))|(((
	82	+This property can be set so that PayEx Checkout can add a fee depending on which payment method the user chooses during the PayEx Checkout user flow.
	83	+
	84	+{{code language="JavaScript"}}
	85	+{
	86	+ "invoice": {
	87	+ "amount": 19.50,
	88	+ "vatAmount": 3.90,
	89	+ "description": "Invoice fee"
	90	+ }
	91	+}
	92	+{{/code}}
	93	+)))
	94	+
	95	+== Example ==
	96	+
	97	+=== Request ===
	98	+
	99	+{{code language="JavaScript"}}
	100	+POST https://api.payex.com/psps/checkout/payment-sessions/ HTTP/1.1
	101	+Content-Type: application/json
	102	+Authorization: Bearer merchantToken==
	103	+
	104	+{
	105	+ "amount": 199.50,
	106	+ "vatAmount": 39.90,
	107	+ "vatRate": 25,
	108	+ "currency": "NOK",
	109	+ "callbackUrl": "https://merchant.api/callback",
	110	+ "reference": "merchant-order-123",
	111	+ "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
	112	+ "culture": "nb-NO",
	113	+ "payer": {
	114	+ "email": "payer@example.com",
	115	+ "mobilePhoneNumber": "+4712345678"
	116	+ },
	117	+ "fees" : {
	118	+ "invoice": {
	119	+ "amount": 19.50,
	120	+ "vatAmount": 3.90,
	121	+ "description": "Invoice fee"
	122	+ }
	123	+ }
	124	+}
	125	+
	126	+{{/code}}
	127	+
	128	+=== Response ===
	129	+
	130	+{{code language="JavaScript"}}
	131	+HTTP/1.1 201 Created
	132	+Content-Type: application/json
	133	+Location: https://api.payex.com/psp/checkout/payment-sessions/123-456-789
	134	+
	135	+{
	136	+ "id": "https://api.payex.com/psp/checkout/payment-sessions/123-456-789",
	137	+ "amount": 199.50,
	138	+ "vatAmount": 39.90,
	139	+ "currency": "NOK",
	140	+ "callbackUrl": "https://merchant.api/callback",
	141	+ "reference": "merchant-order-123",
	142	+ "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
	143	+ "culture": "nb-NO",
	144	+ "fees" : {
	145	+ "invoice": {
	146	+ "amount": 19.50,
	147	+ "vatAmount": 3.90,
	148	+ "description": "Invoice fee"
	149	+ }
	150	+ }
	151	+}
	152	+
	153	+{{/code}}
	154	+
	155	+A successful request will respond with the HTTP status code {{code}}201 Created{{/code}}. Any other status code can be seen as a failure and a description of how to handle it can be found in the [[Problems section>>doc:ecommerce.PayEx Checkout.Problems.WebHome]].
	156	+
	157	+Remember to persist the {{code}}Location{{/code}} header or value of the {{code}}id{{/code}} property in the response alongside the order, shopping cart or similar for which the Payment Session was created.
	158	+
	159	+= Retrieve Payment Session =
	160	+
	161	+To retrieve a Payment Session, just perform an HTTP {{code}}GET{{/code}} request to the URL as returned in the response documented above. Within the Payment Session resource, you can discover the URL of the [[Payment>>ecommerce.PayEx Checkout.Payment]] or [[Payer>>ecommerce.PayEx Checkout.Payer]].
	162	+
	163	+== Example ==
	164	+
	165	+=== Request ===
	166	+
	167	+{{code language="JavaScript"}}
	168	+GET https://api.payex.com/psp/checkout/payment-sessions/123-456-789 HTTP/1.1
	169	+Accept: application/json
	170	+Authorization: Bearer merchantToken==
	171	+{{/code}}
	172	+
	173	+=== Response ===
	174	+
	175	+{{code language="JavaScript"}}
	176	+HTTP/1.1 200 OK
	177	+Content-Type: application/json
	178	+
	179	+{
	180	+ "id": "https://api.payex.com/psp/checkout/payment-sessions/123-456-789",
	181	+ "amount": 199.50,
	182	+ "vatAmount": 39.90,
	183	+ "currency": "NOK",
	184	+ "callbackUrl": "https://merchant.api/callback",
	185	+ "reference": "merchant-order-123",
	186	+ "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
	187	+ "culture": "nb-NO",
	188	+ "fees": {
	189	+ "invoice": {
	190	+ "amount": 19.50,
	191	+ "vatAmount": 3.90,
	192	+ "description": "Invoice fee"
	193	+ }
	194	+ },
	195	+ "addressee": {
	196	+ "name": "Olivia Nyhuus",
	197	+ "email": "olivia.nyhuus@example.com",
	198	+ "mobilePhoneNumber": "004791234567",
	199	+ "shippingAddress": {
	200	+ "city": "Oslo",
	201	+ "countryCode": "NO",
	202	+ "streetAddress": "Stålverkskroken, 4",
	203	+ "zipCode": "0661"
	204	+ }
	205	+ },
	206	+ "payment": "https://api.payex.com/psp/payment/credit-card/984-223-836"
	207	+}
	208	+{{/code}}
	209	+
	210	+= Problems =
	211	+
	212	+If a request fails, its response will have a status code between 400 and 599. The HTTP body of the response will also be in the form of an {{code}}application/problem+json{{/code}} ([[RFC 7807>>https://tools.ietf.org/html/rfc7807]]), explaining in detail why the request failed and which, if any, actions you can take to remedy the problem. You can read more about this [[here>>doc:ecommerce.PayEx Checkout.Problems.WebHome]].