Wiki source code of Payment Session

Last modified by Asbjørn Ulsberg on 2018/07/05 12:48
Show last authors
1 An implementer must first perform a {{code}}POST{{/code}} to this resource to initate the payment with an HTTP POST from your backend with payment info and your access token. The response from the POST will contain a payment session URL. Persist the {{code}}paymentSessionUrl{{/code}} alongside the data representing the initial POST, be it a shopping cart, an order, or similar.
2
3 The {{code}}paymentSessionUrl{{/code}} returned from the {{code}}POST{{/code}} is the base URL to request all other resources related to the [[Payment>>Sandbox.payex-checkout-v1.Introduction.Payment.WebHome]].
4
5
6 == Create Payment Session ==
7
8 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.
9
10 This resource requires authentication as mentioned in the [[introduction>>Sandbox.payex-checkout-v1.Introduction.WebHome||anchor="HAuthentication"]].
11
12 === Properties ===
13
14 |(% style="text-align:right" %)**Property** |=Description
15 |(% style="text-align:right" %){{code}}amount{{/code}}
16 (% style="color:LightGrey" %)number
17 (required)|(((
18 The total amount of the payment (included vat and shipping).
19
20 The amount will be verified against the amount sent in from your frontend.
21 )))
22 |(% style="text-align:right" %){{code}}vatAmount{{/code}}
23 (% style="color:LightGrey" %)number
24 (optional to vatRate)|(((
25 The vat amount of the the payment.
26
27 The vat amount will be verified against the vat amount sent in from your frontend
28 )))
29 |(% style="text-align:right" %){{code}}vatRate{{/code}}
30 (% style="color:LightGrey" %)number
31 (optional to vatAmount)|(((
32 The vat rate of the the payment.
33
34 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.
35 )))
36 |(% style="text-align:right" %)(((
37 {{code}}currency{{/code}}
38 (% style="color:LightGrey" %)string
39 (required)
40 )))|(((
41 The currency of the payment.
42
43 The following currencies is supported by PayEx Checkout as of now: "NOK" & "SEK".
44 )))
45 |(% style="text-align:right" %){{code}}hosts{{/code}}
46 (% style="color:LightGrey" %)string[]
47 (optional)|(((
48 The host name(s) of the web site that includes the PayEx Checkout JavaScript and holds the button that PayEx Checkout will be initialized from. The host name(s) will be used by PayEx Checkout to verify the host it is initialized from, so unauthorized hosts won’t be able to open PayEx Checkout on behalf of other web sites.
49 )))
50 |(% style="text-align:right" %){{code}}callbackUrl{{/code}}
51 (% style="color:LightGrey" %)string
52 (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.
53 |(% style="text-align:right" %){{code}}reference{{/code}}
54 (% style="color:LightGrey" %)string
55 (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.
56 |(% style="text-align:right" %)(((
57 {{code}}culture{{/code}}
58 (% style="color:LightGrey" %)string
59 (optional)
60 )))|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.
61 |(% style="text-align:right" %){{code}}acquire{{/code}}
62 (% style="color:LightGrey" %)array
63 (optional) |(((
64 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.
65
66 The following parameters are valid: {{code language="JavaScript"}}["email", "mobilePhoneNumber", "shippingAddress"]{{/code}}.
67 )))
68 |(% style="text-align:right" %){{code}}payer{{/code}}
69 (% style="color:LightGrey" %)object
70 (optional) |(((
71 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.
72
73 {{code language="json"}}
74 {
75 "email": "<emailAddress>",
76 "mobilePhoneNumber": "<mobilePhoneNumber>"
77 }
78 {{/code}}
79 )))
80 |(% style="text-align:right" %){{code}}fees{{/code}}(((
81 (% style="color:LightGrey" %)object
82 (optional)
83 )))|(((
84 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.
85
86 {{code language="json"}}
87 {
88 "invoice": {
89 "amount": 19.50,
90 "vatAmount": 3.90,
91 "description": "Invoice fee"
92 }
93 }
94 {{/code}}
95 )))
96
97 == Example ==
98
99 === Request ===
100
101 {{code language="JavaScript"}}
102 POST https://api.payex.com/psps/checkout/payment-sessions/ HTTP/1.1
103 Content-Type: application/json
104 Authorization: Bearer merchantToken==
105
106 {
107 "amount": 199.50,
108 "vatAmount": 39.90,
109 "vatRate": 25,
110 "currency": "NOK",
111 "callbackUrl": "https://merchant.api/callback",
112 "reference": "merchant-order-123",
113 "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
114 "culture": "nb-NO",
115 "hosts": ["https://merchant.com/"],
116 "payer": {
117 "email": "payer@example.com",
118 "mobilePhoneNumber": "+4712345678"
119 },
120 "fees" : {
121 "invoice": {
122 "amount": 19.50,
123 "vatAmount": 3.90,
124 "description": "Invoice fee"
125 }
126 }
127 }
128
129 {{/code}}
130
131 === Response ===
132
133 {{code language="JavaScript"}}
134 HTTP/1.1 201 Created
135 Content-Type: application/json
136 Location: https://api.payex.com/psp/checkout/payment-sessions/123-456-789
137
138 {
139 "id": "https://api.payex.com/psp/checkout/payment-sessions/123-456-789",
140 "amount": 199.50,
141 "vatAmount": 39.90,
142 "currency": "NOK",
143 "callbackUrl": "https://merchant.api/callback",
144 "reference": "merchant-order-123",
145 "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
146 "culture": "nb-NO",
147 "fees" : {
148 "invoice": {
149 "amount": 19.50,
150 "vatAmount": 3.90,
151 "description": "Invoice fee"
152 }
153 }
154 }
155
156 {{/code}}
157
158 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]].
159
160 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.
161
162 = Retrieve Payment Session =
163
164 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]].
165
166 == Example ==
167
168 === Request ===
169
170 {{code language="JavaScript"}}
171 GET https://api.payex.com/psp/checkout/payment-sessions/123-456-789 HTTP/1.1
172 Accept: application/json
173 Authorization: Bearer merchantToken==
174 {{/code}}
175
176 === Response ===
177
178 {{code language="JavaScript"}}
179 HTTP/1.1 200 OK
180 Content-Type: application/json
181
182 {
183 "id": "https://api.payex.com/psp/checkout/payment-sessions/123-456-789",
184 "amount": 199.50,
185 "vatAmount": 39.90,
186 "currency": "NOK",
187 "callbackUrl": "https://merchant.api/callback",
188 "reference": "merchant-order-123",
189 "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
190 "culture": "nb-NO",
191 "fees": {
192 "invoice": {
193 "amount": 19.50,
194 "vatAmount": 3.90,
195 "description": "Invoice fee"
196 }
197 },
198 "addressee": {
199 "name": "Olivia Nyhuus",
200 "email": "olivia.nyhuus@example.com",
201 "mobilePhoneNumber": "004791234567",
202 "shippingAddress": {
203 "city": "Oslo",
204 "countryCode": "NO",
205 "streetAddress": "Stålverkskroken, 4",
206 "zipCode": "0661"
207 }
208 },
209 "payment": "https://api.payex.com/psp/payment/credit-card/984-223-836"
210 }
211 {{/code}}
212
213 = Problems =
214
215 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 problems here>>doc:Sandbox.payex-checkout-v1.Introduction.Problems.WebHome]].

Tips

Did you know that you can improve XWiki? Take 5 minutes to fill this survey and help this open source project!

Need help?

If you need help with XWiki you can contact: