PayEx Developer Portal - PayEx Checkout v1

Introduction

PayEx Checkout v1 is an easy way for customers to complete payments. We provide a two-phase payment method which means that an amount is initially reserved (authorized), then deducted (captured) and described in more detail when you are ready to send out the goods.

What you need before you get started

HTTPS enabled web server
Agreement that includes PayEx Checkout
Obtained credentials (access token) from PayEx

To get a grasp of what we expect of your implementation when you are finished, we recommend that you take a peek at the following sequence diagram before you get started.

What you should do, step by step

Below is an example implementation provided in C# 6, .NET 4.5.1+ and Newtonsoft.Json for the backend code. The frontend naturally uses HTML5 and JavaScript. To view backend examples of the raw HTTP request and response messages, please have a look at the Backend API documentation.

Note that the examples are written for a "happy path" implementation and thus contain no error handling of any kind. The examples are therefore not production ready code to be used in an actual application, they are just provided to help understanding the API and give the implementation a head start.

Test data is located in the Test Data section. If you encounter any problem with the implementation, please visit the troubleshooting section or send us an e-mail.

Step 1: Create payment session

Create a payment session by doing a HTTP POST from your webserver with payment info and your merchant token. The response from the POST will contain a Payment Session URL that you will need later. Save this value for future use (frontend config and operations on the payment) related to the order/shoppingcart in your database.

HTTP
C#

Retrieve the Home resource and locate the Payment Session base URL

Request

GET https://api.payex.com/psp/checkout/ HTTP/1.1
Accept: application/json
Authorization: Bearer merchantToken==

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"paymentSession": "<payment_session_url>"
}

Perform the POST request to the Payment Session base URL to create a Payment Session

Request

POST https://api.payex.com/psp/checkout/payment-sessions/ HTTP/1.1
Content-Type: application/json
Authorization: Bearer merchantToken==

{
   "amount": 199.50,
   "vatAmount": 39.90,
   "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",
   "hosts": ["https://merchant.com/"],
   "payer": {
       "email": "payer@example.com",
       "mobilePhoneNumber": "+4712345678"
    },
   "fees" : {
       "invoice": {
           "amount": 19.50,
           "vatAmount": 3.90,
           "description": "Invoice fee"
        }
    }
}

Find the URL of the created Payment Session in the HTTP 'Location' header and store it alongside the order, shopping cart, or similar

var merchantToken = "<secret merchant token>";
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("Authorization", "Bearer " + merchantToken);

// 1. Retrieve the Home resource and locate the Payment Session base URL.
var homeResponse = await httpClient.GetAsync("https://api.payex.com/psp/checkout");
var homeContent = await homeResponse.Content.ReadAsStringAsync();
var home = Newtonsoft.Json.Linq.JObject.Parse(homeContent);
var paymentSessionBaseUrl = home["paymentSession"].ToString();

// 2. Perform the POST request to the Payment Session base URL to create a Payment Session
var json = Newtonsoft.Json.JsonConvert.SerializeObject(new
{
    amount = 100.00,
    vatAmount = 20.00,
    currency = "NOK",
    callbackUrl = "https://merchant.api/callback",
    reference = "merchant-order-123",
    acquire = new[] { "shippingAddress" },
    culture = "nb-NO"
});
var paymentSessionContent = new StringContent(json, Encoding.UTF8, "application/json");
var paymentSessionResponse = await httpClient.PostAsync(paymentSessionBaseUrl, paymentSessionContent);

// 3. Find the URL of the created Payment Session in the HTTP 'Location' header and store it alongside the order, shopping cart, or similar.
var paymentSessionUrl = paymentSessionResponse.Headers.Location;

After the above code is executed, the paymentSessionUrl variable will contain the URL to a Payment Session that contains the payment data used to guide the user through the PayEx Checkout user flow. Remember to persist the paymentSessionUrl to storage related to the order, shopping cart or similar represented by the reference above.

Your can read more about the payment session object here.

Step 2: Configure your frontend

PayEx Checkout uses a script that bootstraps the payment process when your purchase button is clicked. Add the PayEx Checkout script to your page:

Please note that the above URL points to PayEx Checkout's test environment. For the URL to PayEx' production environment, please refer to the general API introduction.

Choose the button that you want to start the checkout process with and add the attribute data-payex-checkout with the value returned from return in the initial POST. Then add the disable attribute - the PayEx Checkout JavaScript will enable it when it is properly loaded. The button should be wrapped inside a form that POST to your server.

<form action="<url_to_your_server>" method="post">

<button data-payex-checkout="<payment_session_url>" disabled>Pay</button>
</form>

The PayEx Checkout script will post the form when the payment process is complete.

You can read more about how to implement PayEx Checkout in your frontend here.

Step 3: Payment window (facilitated by PayEx)

When a consumer clicks on the Pay button the PayEx Checkout payment window appears in the web browser. This payment window includes the following steps.

Login

PayEx holds all payer information for easier payment procedure. If the user submits an email address a lookup process begins.
Otherwise an anonymous payment process is used where only credit card is available as payment method.

Authentication

By specifying mobile phone number, a verification code is sent to your phone.

Delivery

Depending on the parameters provided in the acquires property, various address information is required to continue to next step.

Payment

Depending on merchant country, merchant contract and consumer country a list of payment options is displayed.
Possible options are currently credit card and invoice.
Credit card offers the option to add a new card or pick a previous card.
Invoice is only available for consumers in same country as merchant.

Once the payment is authorized at our end - the PayEx Checkout Javascript will post the form.
From the payment window is opened until it closes, everything in the payment process is performed entirely by PayEx. After that we expect a receipt to be sent to the consumer.

Step 4: Get payment status

After a successfully authorized payment, the purchase form will be submitted as earlier mentioned. It is assumed that the form contains the reference connecting the previously persisted paymentSessionUrl to the order, shopping cart, or similar.

When the form is submitted, look up the paymentSesionUrl and perform a GET request on it to retrieve the status of the payment. The returned JSON will also contain the necessary URLs to perform actions on the payment such as capture, cancel and reversal.

HTTP
C#

Retrieve the paymentSessionUrl related to the submitted form from storage, and then retrieve the Payment Session and find the URL of the Payment.

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

{
   "amount": 199.50,
   "vatAmount": 39.90,
   "currency": "NOK",
   "callbackUrl": "https://merchant.api/callback",
   "reference": "merchant-order-123",
   "acquire": ["email", "mobilePhoneNumber", "shippingAddress"],
   "culture": "nb-NO",
   "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",
}

Retrieve the Payment and inspect its state.

Request

GET <payment_url> HTTP/1.1
Content-Type: application/json
Authorization: Bearer merchantToken==

Response

{
   "payment": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
       "number": 1234567890,
       "created": "2016-09-14T13:21:29.3182115Z",
       "updated": "2016-09-14T13:21:57.6627579Z",
       "operation": "Purchase|Verify|Recur",
       "intent": "Authorization|AutoCapture",
       "state": "Ready|Pending|Failed|Aborted",
       "currency": "NOK|SEK|...",
       "amount": 1500,
       "remainingCaptureAmount": 1500,
       "remainingCancellationAmount": 1500,
       "remainingReversalAmount": 0,
       "description": "Test Purchase",
       "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "paymentToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
       "prices": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices"
        },
       "transactions": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions"
        },
       "authorizations": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations"
        },
       "captures": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures"
        },
       "cancellations": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations"
        },
       "reversals": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals"
        },
       "payeeInfo": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo"
        },
       "urls": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls"
        },
       "settings": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings"
        }
    },
   "operations": [
        {
           "href": "<capture_operation_url>",
           "rel": "create-checkout-capture",
           "method": "POST"
        },
        {
           "href": "<cancellation_operation_url>",
           "rel": "create-checkout-cancellation",
           "method": "POST"
        },
        {
           "href": "<reversal_operation_url>",
           "rel": "create-checkout-reversal",
           "method": "POST"
        }
    ]
}

Implementation example

After the above code example is executed, the paymentState variable will contain the value Ready, Pending, Failed or Aborted. Use it to provide a message to the user in the form of a receipt, an error message in the event of failure, etc.

In a normal flow the paymentState will be Ready and it is now expected that an order confirmation is presented to the consumer in your webshop and that you ship the confirmation per email.

Read more about the payment session here.

Step 5: Capture the payment

HTTP
C#

Capture can be done at any time, depending on whether you want to physically send the purchased goods to the customer first, for instance. Just repeat the GET request to the paymentSessionUrl, find the capture operation and execute it. We now expect an order confirmation to be sent to the consumer.

Retrieve the paymentSessionUrl related to the submitted form from storage, and then retrieve the Payment Session and find the URL of the Payment.

Request

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

Response

Retrieve the Payment and find its create-checkout-capture operation:

Request

GET <payment_url> HTTP/1.1
Content-Type: application/json
Authorization: Bearer merchantToken==

Response

Perform the capture request:

Request

POST <capture_operation_href> HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer merchantToken==

{
   "transaction": {
       "description": "description for the transaction"
    }
}

Response

{
   "payment": "<paymentUrl>",
   "capture": {
       "id": "<paymentCaptureUrl>",
       "transaction": {
           "id": "<transactionUrl>",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Capture",
           "state": "Initialized|Completed|Failed",
           "number": 1234567890,
           "amount": 1500,
           "vatAmount": 300,
           "description": "Test Capture",
           "payeeReference": "ABC123",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }
    }
}

As the state property in the response above will indicate, the capture operation should now be Completed, indicating that the payment is captured.

Implementation example

var merchantToken = "<secret merchant token>";
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("Authorization", "Bearer " + merchantToken);

// 1. Retrieve the paymentSessionUrl related to the submitted form from storage.
var paymentSessionUrl = "<retrieved from storage>";

// 2. Retrieve the Payment Session and find the URL of the Payment.
var paymentSessionResponse = await httpClient.GetAsync(paymentSessionUrl);
var paymentSessionContent = await paymentSessionResponse.Content.ReadAsStringAsync();
var paymentSession = Newtonsoft.Json.Linq.JObject.Parse(paymentSessionContent);
var paymentUrl = paymentSession["payment"].ToString();

// 3. Retrieve the Payment and find its 'create-checkout-capture' operation.
var paymentResponse = await httpClient.GetAsync(paymentUrl);
var paymentContent = await paymentResponse.Content.ReadAsStringAsync();
var payment = Newtonsoft.Json.Linq.JObject.Parse(paymentContent);
var captureUrl = payment["operations"]
    .Children()
    .First(x => x["rel"].ToString() == "create-checkout-capture")["href"]
    .ToString();

// 4. Perform the capture request.
var json = Newtonsoft.Json.JsonConvert.SerializeObject(new
{
    transaction = new
    {
        description = "Captured the payment"
    }
});
var captureRequestContent = new StringContent(json, Encoding.UTF8, "application/json");
var captureResponse = await httpClient.PostAsync(captureUrl, captureRequestContent);
var captureResponseContent = await captureResponse.Content.ReadAsStringAsync();
var capture = Newtonsoft.Json.Linq.JObject.Parse(captureResponseContent);

When the above code example is executed, the capture variable will be a JSON object containing the result of the capture operation. It is now excepted that an order receipt is sent per email to the consumer.

The above example performs a complete capture of the authorized amount. If you want to perform a more detailed captured, read more about the capture operation here.

payex-checkout-v1

PayEx Checkout v1

Introduction

What you need before you get started

What you should do, step by step

Step 1: Create payment session

Step 2: Configure your frontend

Step 3: Payment window (facilitated by PayEx)

Login

Authentication

Delivery

Payment

Step 4: Get payment status

Implementation example

Step 5: Capture the payment

Applications

Navigation

Tips

Need help?