Payment Session
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 access token. 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.
The paymentSessionUrl returned from the POST is the base URL to request all other resources related to the Payment.
Create Payment Session
To create a Payment Session, you simply perform an HTTP POST request with a Payment Session JSON payload as documented below to the Payment Session URL as discovered in the Home Resource.
This resource requires authentication as mentioned in the Intro.
Properties
| Property | Description |
|---|---|
| amount number (required) | The total amount of the payment (included vat and shipping). The amount will be verified against the amount sent in from your frontend. |
| vatAmount number (optional to vatRate) | The vat amount of the the payment. The vat amount will be verified against the vat amount sent in from your frontend |
| vatRate number (optional to vatAmount) | The vat rate of the the payment. 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. |
currency | The currency of the payment. The following currencies is supported by PayEx Checkout as of now: "NOK" & "SEK". |
| hosts string[] (optional) | 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. |
| callbackUrl string (required) | The URL you want PayEx to perform HTTP POST 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. |
| reference string (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 ^\w*$ and be no longer than 40 characters. |
culture | The culture you want PayEx Checkout to be presented in. Valid cultures as of now: "nb-NO", "sv-SE" and "en-US". If no culture is specified, the culture will default to "en-US". 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. |
| acquire array (optional) | 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. The following parameters are valid: ["email", "mobilePhoneNumber", "shippingAddress"]. |
| payer object (optional) | 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. { "email": "<emailAddress>", "mobilePhoneNumber": "<mobilePhoneNumber>" } |
| fees object | 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. { "invoice": { "amount": 19.50, "vatAmount": 3.90, "description": "Invoice fee" } } |
Example
Request
Content-Type: application/json
Authorization: Bearer merchantToken==
{
"amount": 199.50,
"vatAmount": 39.90,
"vatRate": 25,
"currency": "NOK",
"callbackUrl": "https://merchant.api/callback",
"reference": "merchant-order-123",
"acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
"culture": "nb-NO",
"hosts": ["https://merchant.com/"],
"payer": {
"email": "payer@example.com",
"mobilePhoneNumber": "+4712345678"
},
"fees" : {
"invoice": {
"amount": 19.50,
"vatAmount": 3.90,
"description": "Invoice fee"
}
}
}
Response
Content-Type: application/json
Location: https://api.payex.com/psp/checkout/payment-sessions/123-456-789
{
"id": "https://api.payex.com/psp/checkout/payment-sessions/123-456-789",
"amount": 199.50,
"vatAmount": 39.90,
"currency": "NOK",
"callbackUrl": "https://merchant.api/callback",
"reference": "merchant-order-123",
"acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
"culture": "nb-NO",
"fees" : {
"invoice": {
"amount": 19.50,
"vatAmount": 3.90,
"description": "Invoice fee"
}
}
}
A successful request will respond with the HTTP status code 201 Created. 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.
Remember to persist the Location header or value of the id property in the response alongside the order, shopping cart or similar for which the Payment Session was created.
Retrieve Payment Session
To retrieve a Payment Session, just perform an HTTP GET request to the URL as returned in the response documented above. Within the Payment Session resource, you can discover the URL of the Payment or Payer.
Example
Request
Accept: application/json
Authorization: Bearer merchantToken==
Response
Content-Type: application/json
{
"id": "https://api.payex.com/psp/checkout/payment-sessions/123-456-789",
"amount": 199.50,
"vatAmount": 39.90,
"currency": "NOK",
"callbackUrl": "https://merchant.api/callback",
"reference": "merchant-order-123",
"acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
"culture": "nb-NO",
"fees": {
"invoice": {
"amount": 19.50,
"vatAmount": 3.90,
"description": "Invoice fee"
}
},
"addressee": {
"name": "Olivia Nyhuus",
"email": "olivia.nyhuus@example.com",
"mobilePhoneNumber": "004791234567",
"shippingAddress": {
"city": "Oslo",
"countryCode": "NO",
"streetAddress": "Stålverkskroken, 4",
"zipCode": "0661"
}
},
"payment": "https://api.payex.com/psp/payment/credit-card/984-223-836"
}
Problems
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 application/problem+json (RFC 7807), 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.