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 introduction.

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
string
(required)

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
string
(optional)

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
(optional)

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

POST https://api.payex.com/psps/checkout/payment-sessions/ HTTP/1.1
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

HTTP/1.1 201 Created
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

GET https://api.payex.com/psp/checkout/payment-sessions/123-456-789 HTTP/1.1
Accept: application/json
Authorization: Bearer merchantToken==

Response

HTTP/1.1 200 OK
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.

Created by Asbjørn Ulsberg on 2018/07/05 12:48
   

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: