Wiki source code of Payment Session
Last modified by Asbjørn Ulsberg on 2018/07/05 12:48
 |
82.1 | 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. |
| |
63.1 | 2 | |
| |
87.1 | 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]]. |
| |
63.1 | 4 | |
| 5 | |||
| |
82.1 | 6 | == Create Payment Session == |
| 7 | |||
| |
63.1 | 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 | |||
| |
89.1 | 10 | This resource requires authentication as mentioned in the [[introduction>>Sandbox.payex-checkout-v1.Introduction.WebHome||anchor="HAuthentication"]]. |
| |
63.1 | 11 | |
| |
82.1 | 12 | === Properties === |
| |
63.1 | 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 | ))) | ||
| |
81.1 | 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 | ))) | ||
| |
63.1 | 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 | |||
| |
82.1 | 73 | {{code language="json"}} |
| |
63.1 | 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 | |||
| |
82.1 | 86 | {{code language="json"}} |
| |
63.1 | 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", | ||
| |
81.1 | 115 | "hosts": ["https://merchant.com/"], |
| |
63.1 | 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 | |||
| |
81.1 | 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]]. |
| |
63.1 | 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 | |||
| |
81.1 | 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]]. |
| |
63.1 | 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 | |||
| |
88.1 | 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]]. |