Consumers Resource

The Consumers resource is the fundament of Checkin in PayEx Checkout.

Please be sure to read the general introduction of technical reference before proceeding.

Initiate Consumer Session

Payer identification is done through the initiate-consumer-session operation. In the request body, all properties are optional. The more information that is provided, the easier an identification process for the payer.

Request

POST /psp/consumers HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "operation": "initiate-consumer-session",
   "msisdn": "+4798765432",
   "email": "olivia.nyhuus@example.com",
   "consumerCountryCode": "NO",
   "nationalIdentifier": {
       "socialSecurityNumber": "26026708248",
       "countryCode": "NO"
    }
}

Request Properties

PropertyTypeRequiredDescription
operationstringYinitiate-consumer-session, the operation to perform.
msisdnstringNThe MSISDN (mobile phone number) of the payer. Format Sweden: +46707777777. Format Norway: +4799999999.
emailstringNThe e-mail address of the payer.
consumerCountryCodestringYConsumers country of residence. Used by the consumerUi for validation on all input fields.
nationalIdentifier.socialSecurityNumberstringNThe social security number of the payer. Format: Norway DDMMYYXXXXX, Sweden: YYYYMMDDXXXX.
nationalIdentifier.countryCodestringNThe country code, denoting origin for the issued social security number. Required if nationalIdentifier.socialSecurityNumber is set. 

When the request is sent the following response contains a session token -  that is used to initiate the Checkout UI - and an array of operations that can be acted upon.

Response

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

{
   "token": "7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
   "operations": [
        {
           "rel": "redirect-consumer-identification",
           "method": "GET",
           "contentType": "text/html",
           "href": "https://ecom.externalintegration.payex.com/consumers/sessions/123456123412341234123456789012",
        },
        {
           "rel": "view-consumer-identification",
           "method": "GET",
           "contentType": "application/javascript",
           "href": "https://ecom.externalintegration.payex.com/consumers/core/scripts/client/px.consumer.client.js?token=7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871",
        }
    ]
}

Response Properties

PropertyTypeDescription
tokenstringA session token used to initiate Checkout UI.
operationsarrayThe array of operation objects to choose from for.
operations[].relstringThe relational name of the operation, used as a programmatic identifier to find the correct operation given the current state of the application.
operations[].methodstringThe HTTP method to use when performing the operation.
operations[].contentTypestringThe HTTP content type of the target URI. Indicates what sort of resource is to be found at the URI, how it is expected to be used and behave.
operations[].hrefstringThe target URI of the operation. 

View Consumer Identification

The view-consumer-identification operation is meant to be embedded in a <script> element in an HTML document, like the example below:

HTML
<!DOCTYPE html>
<html>
    <head>
        <title>PayEx Checkout is Awesome!</title>
    </head>
    <body>
        <div id="checkin"></div>
        <script data-payex-hostedview="checkin"
               data-payex-hostedview-culture="nb-NO"
               src="https://ecom.payex.com/consumers/core/scripts/client/px.consumer.client.js?token=7e380fbb3196ea76cc45814c1d99d59b66db918ce2131b61f585645eff364871"></script>
        <script>
            payex.hostedView.consumer({
                container: "checkin",
                onConsumerIdentified: function(consumerIdentifiedEvent) {
                    console.log(consumerIdentifiedEvent);
                },
                onShippingDetailsAvailable: function(shippingDetailsAvailable){
                    console.log(shippingDetailsAvailable);
                },
                onError: function(error) {
                    console.error(error);
                }
            }).open();
        </script>
    </body>
</html>

Note that the <script> element is added after the <div> container the checkin will be hosted in.

Retrieve Consumer Shipping Details

When the payer has been identified through checkin you can retrieve the consumers shipping details with the operation received through the event onShippingDetailsAvailable

Request

GET /psp/consumers/<consumerProfileRef>/shipping-details HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
  "email": "payex.shipping@company.com",
  "msisdn": "+4798765432",
  "shippingAddress": {
    "addressee": "Olivia Nyhuus",
    "coAddress": "c/o Azra Oliveira",
    "streetAddress": "Saltnestoppen 43",
    "zipCode": "1642",
    "city": "Saltnes",
    "countryCode": "NO"
    }
}

Retrieve Consumer Billing Details

When the payer has been identified through checkin you can retrieve the consumers billing details with the operation received through the event OnBillingDetailsAvailable

Request

GET /psp/consumers/<consumerProfileRef>/billing-details HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "email": "PayexTester@payex.com",
   "msisdn": "+46739000001",
   "billingAddress": {
       "addressee": "Leia Ahlström",
       "streetAddress": "Hökvägen 5",
       "zipCode": "17674",
       "city": "Järfälla",
       "countryCode": "SE"
    }
}

Consumer Identification Events

During Consumer identification, three events can occur. They are described below.

On Consumer Identified

When the consumer is identified the event onConsumerIdentified will be raised with the above event argument object. The consumerProfileRef can be used to initiate Payment Menu through the payment orders resource described here.

On Consumer Identified
{
   "actionType": "OnConsumerIdentified",
   "consumerProfileRef": "7d5788219e5bc43350e75ac633e0480ab30ad20f96797a12b96e54da869714c4"
}

Properties

PropertyTypeDescription
actionTypestringThe type of event that was raised.
consumerProfileRefstringThe unique reference to the identified consumer.

On Shipping Details Available

When the consumer is identified the event onShippingDetailsAvailable will be raised with the above event argument object. The url can be used to retrieve the shipping details through the consumers resource described here.

On Shipping Details Available
{
   "actionType": "OnShippingDetailsAvailable",
   "url": "psp/consumers/<consumerProfileRef>/shipping-details"
}

Properties

PropertyTypeDescription
actionTypestringThe type of event that was raised.
urlstringThe URI to retrieve shipping details of the consumer.

On Billing Details Available

When the consumer is identified the event OnBillingDetailsAvailable will be raised with the above event argument object. The url can be used to retrieve the billing details through the consumers resource described here.

On Billing Details Available
{
   "actionType": "OnBillingDetailsAvailable",
   "url": "/psp/consumers/<consumerProfileRef>/billing-details"
}

Properties

PropertyTypeDescription
actionTypestringThe type of event that was raised.
urlstringThe URI to retrieve billing details of the consumer.

On Error

This event triggers during terminal errors or if the configuration fails validaton. The onError event will be raised with the following event argument object:

On Error
{
   "origin": "consumer | paymentmenu | creditcard | invoice | ...",
   "messageId": "<unique message ID>",
   "details": "Descriptive text of the error"
}

Properties

PropertyTypeDescription
originstringconsumer, paymentmenu, creditcard, identifies the system that originated the error.
messageIdstringA unique identifier for the message.
detailsstringA human readable and descriptive text of the error.
Created by Fredrik Köhler on 2018/10/26 11:08