Payment Orders Resource

The Payment Orders resource is utilized when initating Payment Menu, the second main component of PayEx Checkout. This section also describe related sub-resources and event triggers.

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

Payment Orders

The paymentorders resource is used when initiating a payment process through Payment Menu and PayEx Checkout. The payment order is a container for the payment method object selected by the payer. This will generate a payment that is accessed through the sub-resources payments and currentPayment.

Request
GET /psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/ HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "paymentorder": {
       "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
       "created": "2018-09-14T13:21:29.3182115Z",
       "updated": "2018-09-14T13:21:57.6627579Z",
       "operation": "Purchase",
       "state": "Ready",
       "currency": "SEK",
       "amount": 1500,
       "vatAmount": 0,
       "remainingCaptureAmount": 1500,
       "remainingCancellationAmount": 1500,
       "remainingReversalAmount": 0,
       "description": "Test Purchase",
       "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "urls" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
       "payeeInfo" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeinfo" },
       "settings": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" },
       "payers": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers" },
       "orderItems" : { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/orderItems" },
       "metadata": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/metadata" },
       "payments": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments" },
       "currentPayment": { "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/currentpayment" }
    },
   "operations": [
        {
           "method": "PATCH",
           "href": "https://api.externalintegration.payex.com/psp/paymentorders/479a7a2b-3b20-4302-fa84-08d676d15bc0",
           "rel": "update-paymentorder-abort",
           "contentType": "application/json"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com/paymentmenu/4b0baaf8fdb5a56b5bdd78a8dd9e63e42e93ec79e5d0c0b5cc40f79cf43c9428",
           "rel": "redirect-paymentorder",
           "contentType": "text/html"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=4b0baaf8fdb5a56b5bdd78a8dd9e63e42e93ec79e5d0c0b5cc40f79cf43c9428&culture=nb-NO",
           "rel": "view-paymentorder",
           "contentType": "application/javascript"
        }
    ]   
}

Properties

PropertyTypeDescription 
paymentorderobjectThe payment order object.
paymentorder.idstringThe relative URI to the payment order.
paymentorder.createdstringThe ISO-8601 date of when the payment order was created.
paymentorder.updatedstringThe ISO-8601 date of when the payment order was updated.
paymentorder.operationstringPurchase
paymentorder.statestringReady, Pending, Failed or Aborted. Indicates the state of the payment order. This field is only for status display purposes.
paymentorder.currencystringThe currency of the payment order.
paymentorder.amountintegerThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
paymentorder.vatAmountintegerThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
paymentorder.descriptionstring(40)A textual description of maximum 40 characters of the purchase.
paymentorder.userAgentstringThe user agent string of the consumer's browser.
paymentorder.languagestringnb-NO, sv-SE or en-US
paymentorder.urlsstringThe URI to the urls resource where all URIs related to the payment order can be retrieved.
paymentorder.payeeInfostringThe URI to the payeeinfo resource where the information about the payee of the payment order can be retrieved.
paymentorder.payersstringThe URI to the payers resource where information about the payee of the payment order can be retrieved.
paymentorder.orderItemsstringThe URI to the orderItems resource where information about the order items can be retrieved.
paymentorder.metadatastringThe URI to the payments resource where information about all underlying payments can be retrieved.
paymentorder.paymentsstringThe URI to the payments resource where information about all underlying payments can be retrieved.
paymentorder.currentPaymentstringThe URI to the currentPayment resource where information about the current – and sole active – payment can be retrieved.
paymentorder.operationsarrayThe array of possible operations to perform, given the state of the payment order. See Operations for details.

Creating a payment order

To create a payment order, you perform a POST request towards the paymentorders resource:

Request
POST /psp/paymentorders HTTP/1.1
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "paymentorder": {
       "operation": "Purchase",
       "currency": "NOK",
       "amount": 1500,
       "vatAmount": 0,
       "description": "Test Purchase",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "generateRecurrenceToken": false,
       "disablePaymentMenu": false,
       "urls": {
           "hostUrls": ["https://example.com", "https://example.net"],
           "completeUrl": "https://example.com/payment-completed",
           "cancelUrl": "https://example.com/payment-canceled",
           "paymentUrl": "https://example.com/perform-payment",
           "callbackUrl": "https://api.example.com/payment-callback",
           "termsOfServiceUrl": "https://example.com/termsandconditoons.pdf",
           "logoUrl": "https://example.com/logo.png"
        },
       "payeeInfo": {
           "payeeId": "12345678-1234-1234-1234-123456789012",
           "payeeReference": "CD1234",
           "payeeName": "Merchant1",
           "productCategory": "A123",
           "orderReference" : "or-123456",
           "subsite": "Subsite1"
        },
       "payer": {
           "consumerProfileRef": "7d5788219e5bc43350e75ac633e0480ab30ad20f96797a12b96e54da869714c4",
        },
       "orderItems": [
            {
               "reference": "P1",
               "name": "Product1",
               "type": "PRODUCT",
               "class": "ProductGroup1",
               "itemUrl": "https://example.com/products/123",
               "imageUrl": "https://example.com/product123.jpg",
               "description": "Product 1 description",
               "discountDescription": "Volume discount",
               "quantity": 4,
               "quantityUnit": "pcs",
               "unitPrice": 300,
               "discountPrice": 200,
               "vatPercent": 2500,
               "amount": 1000,
               "vatAmount": 250
            },
            {
               "reference": "P2",
               "name": "Product2",
               "type": "PRODUCT",
               "class": "ProductGroup1",
               "description": "Product 2 description",
               "quantity": 1,
               "quantityUnit": "pcs",
               "unitPrice": 500,
               "vatPercent": 2500,
               "amount": 500,
               "vatAmount": 125
            }
        ],
       "metadata": {
           "key1": "value1",
           "key2": 2,
           "key3": 3.1,
           "key4": false
        },
       "items": [
            {
               "creditCard": {
                   "rejectCreditCards": false,
                   "rejectDebitCards": false,
                   "rejectConsumerCards": false,
                   "rejectCorporateCards": false
                }
            },
            {
               "invoice": {
                   "feeAmount": 1900
                }
            },
            {
               "swish": {
                   "enableEcomOnly": false
                }
            }
        ]
    }
}

Properties

PropertyTypeRequiredDescription
paymentorderobjectYThe payment order object.
paymentorder.operationstringYThe operation that the payment order is supposed to perform.
paymentorder.currencystringYThe currency of the payment.
paymentorder.amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
paymentorder.vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
paymentorder.descriptionstringYThe description of the payment order.
paymentorder.userAgentstringYThe user agent of the payer.
paymentorder.languagestringYThe language of the payer.
paymentorder.generateRecurrenceTokenbooleanYDetermines if a payment token should be generated. A recurrence token is primarily used to enable future recurring payments - with the same token - through server-to-server calls. Default value is false
paymentorder.urlsobjectYThe object containing the payee's (such as the webshop or merchant) URLs that are relevant for this payment order. See URLs for details.
paymentorder.payeeInfo.payeeIdstringYThe ID of the payee, usually the merchant ID.
paymentorder.payeeInfo.payeeReferencestring(30)YA unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
paymentorder.payeeInfo.payeeNamestringNThe name of the payee, usually the name of the merchant.
paymentorder.payeeInfo.productCategorystringNA product category or number sent in from the payee/merchant. This is not validated by PayEx, but will be passed through the payment process and may be used in the settlement process.
paymentorder.payeeInfo.orderReferencestring(50)NThe order reference should reflect the order reference found in the merchant's systems.
paymentorder.payeeInfo.subsiteString(40)NThe subsite field can be used to perform split settlement on the payment. The subsites must be resolved with PayEx reconciliation before being used.
paymentorder.payer.consumerProfileRefstringNThe consumer profile reference as obtained through the Consumers API.
paymentorder.orderItemsarrayNThe array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. See Order Items for details.
paymentorder.metadataobjectNThe keys and values that should be associated with the payment order. Can be additional identifiers and data you want to associate with the payment.
paymentorder.itemsarrayNThe array of items that will affect how the payment is performed. See Items for details.

Response

The response given when creating a payment order is equivalent to a GET Request towards the paymentorders resource, as displayed above.

URLs

The urls property of the paymentOrder contains the URIs related to a payment order, including where the consumer gets redirected when going forward with or cancelling a payment session, as well as the callback URI that is used to inform the payee (merchant) of changes or updates made to underlying payments or transaction.

Properties

PropertyTypeRequiredDescription
hostUrlsarrayYThe array of URIs valid for embedding of PayEx Hosted Views.
completeUrlstringYThe URI to redirect the payer to once the payment is completed.
cancelUrlstringNThe URI to redirect the payer to if the payment is canceled. Only used in redirect scenarios. 
paymentUrlstringNThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. If both cancelUrl and paymentUrl is sent, the paymentUrl will used.
callbackUrlstringNThe URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
termsOfServiceUrlstringYThe URI to the terms of service document the payer must accept in order to complete the payment. HTTPS is a requirement.
logoUrlstringNThe URI to the logo that will be displayed on redirect pages. HTTPS is a requirement.

Order Items

The orderItems property of the paymentOrder is an array containing the items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. Order items can be specified on both payment order creation as well as on Capture.

Properties

PropertyTypeRequiredDescription
referencestringYA reference that identifies the order item.
namestringYThe name of the order item.
typestringYPRODUCT, SERVICE, SHIPPING_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
classstringYThe classification of the order item. Can be used for assigning the order item to a specific product category, for instance. PayEx has no use for this value itself, but it's useful for some payment instruments and integrations.
itemUrlstringNThe URL to a page that contains a human readable description of the order item, or similar.
imageUrlstringNThe URL to an image of the order item.
descriptionstringNThe human readable description of the order item.
discountDescriptionstringNThe human readable description of the possible discount.
quantityintegerYThe quantity of order items being purchased.
quantityUnitstringYThe unit of the quantity, such as pcs, grams, or similar.
unitPriceintegerYThe price per unit of order item.
discountPriceintegerNIf the order item is purchased at a discounted price, this property should contain that price.
vatPercentintegerYThe percent value of the VAT multiplied by 100, so 25% becomes 2500.
amountintegerYThe total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
vatAmountintegerYThe total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.

Items

The items property of the paymentOrder is an array containing items that will affect how the payment is performed.

PropertyTypeRequiredDescription
creditCard.no3DSecurebooleanNtrue if the payment should not require a 3D-secure authentication; otherwise false.
creditCard.mailOrderTelephoneOrderbooleanNtrue if this is a MOTO payment; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectCardNot3DSecureEnrolledbooleanNtrue if cards not enrolled with 3D-secure should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectDebitCardsbooleanNtrue if debit cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectCreditCardsbooleanNtrue if credit cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectConsumerCardsbooleanNtrue if consumer cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectCorporateCardsbooleanNtrue if corporate cards should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request.
creditCard.rejectAuthenticationStatusUbooleanNtrue if response code U from issuer bank should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request. Response code U means that it couldn't be determined if card was 3DSecure enrolled or not. 
creditCard.rejectAuthenticationStatusAbooleanNtrue if response code A from issuer bank should be declined; otherwise false per default. Default value is set by PayEx and can be changed at your request. Response code A means that the 3DSecure service is unavailable and therefore a 3DSecure verification is not made.
invoice.feeAmountintegerNThe fee amount in the lowest monetary unit to apply if the consumer chooses to pay with invoice.
swish.enableEcomOnlybooleanNtrue to only enable Swish on ecommerce transactions.

Purchase Payment Orders

The Purchase operation is used in all common purchase scenarios. 

Purchase
{    
   "paymentorder": {
       "operation": "Purchase"
    {
}

Verify Payment Orders

The Verify operation lets you post verifications to confirm the validity of credit card information, without reserving or charging any amount. This option is mainly used to initiate a recurring payment scenario where the card will be charged at a later date. The request body is equivalent to a Purchase order with credit card as the selected item. A payment token will be generated automatically, rendering the parameter generatePaymenttoken unnecessary for this operation. 

Verify
{    
   "paymentorder": {
       "operation": "Verify"
    {
}


Enabling recurring credit card payments

If you want to enable subsequent recurring - server-to-server - payments for credit card, you need to create a recurrence token. This token will be utilized after the initial payment order.  

Recurrence Token

  • When initiating a Purchase payment order, you need to make sure that the attribute generateRecurrenceToken is set to true. This recurrence token will stored in the authorization transaction sub-resource on the underlying credit card payment resource.
  • When initiating a Verify payment order, a recurrence token will be generated automatically. This recurrence token is stored in the verification transaction sub-resource on the underlying credit card payment resource.       

You can view the current payment resource, containg the recurrence token and other payment instrument properties, by expanding the sub-resource currentpayment when doing a GET request on the paymentorders resource.

Request
GET /psp/paymentorders/<paymentorderId>?$expand=currentpayment HTTP/1.1
Host: api.payex.com

Creating recurring credit card payments

When you have a recurrenceToken token safely tucked away, you can use this token in a subsequent Recur payment order. This will be a server-to-server affair, as we have tied all necessary payment instrument details related to the recurrence token during the initial payment order.

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

{
   "paymentOrder": {
       "operation": "Recur",
       "recurrenceToken": "5adc265f-f87f-4313-577e-08d3dca1a26c",
       "currency": "NOK",
       "amount": 15610,
       "vatAmount": 3122,
       "description": "Test recurring payment",
       "language": "nb-NO",
       "urls": {
           "callbackUrl": "https://api.example.com/payment-callback"
        },
       "payeeInfo": {
           "payeeId": "12345678-1234-1234-1234-123456789012",
           "payeeReference": "CD1234",
           "payeeName": "Merchant1",
           "productCategory": "A123",
           "orderReference": "or-12456"
           "subsite": "Subsite1"
        }
    }
}

Disable payment menu when only one instrument exist

Request
{    
   "paymentorder": {
       "disablePaymentMenu": true
    {
}

example disablePaymentMenu = true

disablePaymentMenu_True.PNG

example disablePaymentMenu = false

disablePaymentMenu_False.PNG

Payment Menu Styling

You can customize the visual look by inserting style attributes in the JavaScript function call, inside the <script> element. See the styling section of the technical reference for more information about all styling options available.

JavaScript function call
{
    payex.hostedView.paymentMenu({
        container: 'checkout',
        culture: 'nb-NO',
        onPaymentCompleted: function(paymentCompletedEvent) {
            console.log(paymentCompletedEvent);
        },
        onPaymentFailed: function(paymentFailedEvent) {
            console.log(paymentFailedEvent);
        },
        onPaymentCreated: function(paymentCreatedEvent) {
            console.log(paymentCreatedEvent);
        },
        onPaymentToS: function(paymentToSEvent) {
            console.log(paymentToSEvent);
        },
        onPaymentMenuInstrumentSelected: function(paymentMenuInstrumentSelectedEvent) {
            console.log(paymentMenuInstrumentSelectedEvent);
        },
        onError: function(error) {
            console.error(error);
        },
        style: {   
            body: {
                backgroundColor: "somecolor|#rrggbb",
                border: "1px solid black",
                borderRadius: "5px",
                boxShadow: "10px 5px 5px red;",
                font: "italic small-caps bold normal 14px/1.5em Verdana, Arial, Helvetica, sans-serif",
                color: "hotpink",
                margin: "2px 3px 2px 3px",
                padding: "3px 2px 3px 2px"
            }
        }     
    }).open();
}             

Sub-resources

The paymentOrders resource utilize several sub-resources, relating to underlying payments, the current payment active, payers and URLs.  Common sub-resources like payeeinfo, that are structurally identical for both payments and payments orders, are described in the Payment Resources section. 

Payments Resource

A payment order is able to hold more than one payment object, even though a successful payment order only harbour one successful payment. This is necessary as the consumer might select and initate a payment option that is not followed through successfully. I.e. if the consumer cancels an invoice payment, a cancel transaction will still be tied to that particular invoice payment resource. This payment resource will continue to exist, even if the consumer successfully should finish the purchase with a credit card payment instead.

Request
GET /psp/paymentorders<paymentorderId>/payments HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "payments": {
       "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payments",
       "paymentList" : [
            {
               "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
               "instrument" : "CreditCard",
               "Created": "2016-09-14T13:21:29.3182115Z"
            },
            {   
               "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26d",
               "instrument" : "Invoice",
               "Created": "2016-09-14T13:21:29.3182115Z"
            }
        ]
    }
}
PropertyTypeDescription
paymentorderobjectThe payment order object.
payments.idstringThe relative URI of the current payments resource.
payments.paymentListstringThe array of payment objects.
payments.paymentList[]stringThe payment object.

Current Payment Resource

The currentpayment resource displays the payment that are active within the payment order container.

Request
GET /psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/currentpayment HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "menuElementName": "creditcard",
   "payment": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
       "number": 1234567890,
       "instrument": "CreditCard",
       "created": "2016-09-14T13:21:29.3182115Z",
       "updated": "2016-09-14T13:21:57.6627579Z",
       "operation": "Purchase|Verify|Recur|Payout",
       "intent": "PreAuthorization|Authorization|AutoCapture",
       "state": "Ready|Pending|Failed|Aborted",
       "currency": "NOK|SEK|...",
       "amount": 1500,
       "remainingCaptureAmount": 1500,
       "remainingCancellationAmount": 1500,
       "remainingReversalAmount": 0,
       "description": "Test Purchase",
       "payerReference": "AB1234",
       "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" },
       "verifications": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/verifications" },
       "urls" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls" },
       "payeeInfo" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo" },
       "metadata" : { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/metadata" },
       "settings": { "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings" }
    },
   "operations": []
}
PropertyTypeDescription
paymentorderobjectThe payment order object.
paymentorder.menuElementNamestringcreditcard, invoice, etc. The name of the selected menu element.
paymentorder.paymentobjectThe payment object.
payment.idstringThe relative URI to the payment.
payment.numberintegerThe payment number, useful when there's need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead.
payment.instrumentstringThe payment instrument used.
payment.createdstringThe ISO-8601 date of when the payment was created.
payment.updatedstringThe ISO-8601 date of when the payment was updated.
payment.operationstringpurchase, payout, verify or recur. The type of the initiated payment.
payment.statestringReady, Pending, Failed or Aborted. Indicates the state of the payment. This field is only for status display purposes.
payment.prices.amountintegerAmount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
payment.prices.remainingCaptureAmountintegerThe available amount to capture.
payment.prices.remainingCancelAmountintegerThe available amount to cancel.
payment.prices.remainingReversalAmountintegerThe available amount to reverse.
payment.descriptionstring(40)A textual description of maximum 40 characters of the purchase.
payment.payerReferencestringThe reference to the consumer from the merchant system, like mobile number, customer number etc.
payment.generatePaymentTokenbooleanIf this value is set to true you can use the paymentToken to initiate recurring payments or One-Click purchases with the same credit card. The default value is false.

URLs Resource

The urls resource contains the URIs related to a payment order, including where the consumer gets redirected when going forward with or cancelling a payment session, as well as the callback URI that is used to inform the payee (merchant) of changes or updates made to underlying payments or transaction.

Request
GET /psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/urls/ HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "urls": {
       "id": "/psp/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls",
       "hostUrls": [ "http://test-dummy.net", "http://test-dummy2.net" ],
       "completeUrl": "http://example.com/payment-complete",
       "cancelUrl": "http://example.com/payment-canceled",
       "paymentUrl": "http://example.com/perform-payment",
       "callbackUrl": "http://api.example.com/payment-callback",
       "logoUrl": "http://merchant.com/path/to/logo.png",
       "termsOfServiceUrl": "http://merchant.com/path/to/tems"
    }
}

Properties

PropertyData typeDescription
paymentorderstringThe URI to the payment order the resource belong to.
paymentorder.urls.idstringThe relative URI to the current resource.
paymentorder.urls.hostsUrlstringAn array of the whitelisted URIs that are allowed as parents to a Hosted View, typically the URI of the web shop or similar that will embed a Hosted View within it.
paymentorder.urls.completeUrlstringThe URI that PayEx will redirect back to when the payment page is completed.
paymentorder.urls.cancelUrlstringThe URI to redirect the payer to if the payment is canceled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both. 
paymentorder.urls.paymentUrlstringThe URI that PayEx will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. Only used in hosted views. Can not be used simultaneously with cancelUrl; only cancelUrl or paymentUrl can be used, not both.
paymentorder.urls.callbackUrlstringThe URI that PayEx will perform an HTTP POST against every time a transaction is created on the payment. See callback for details.
paymentorder.urls.logoUrlstringThe URI that will be used for showing the customer logo. Must be a picture with at most 50px height and 400px width.
paymentorder.urls.termsOfServiceUrlstringA URI that contains your terms and conditions for the payment, to be linked on the payment page.

Payer Resource

The payer resource contains payer information related to the payment order. The information is retrieved via a consumer profile token (consumerProfileRef), from the Consumers resource during login/checkin.

Request
GET /psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payers/ HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

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

{
   "paymentorder": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "payer" : {
       "id": "/psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c/payer",
       "reference": "reference to payer",                
       "email": "email",                                
       "msisdn": "msisdn",                              
       "shippingAddress": {                             
           "addressee": "firstName + lastName",
           "coAddress": "coAddress",
           "streetAddress": "streetAddress",
           "zipCode": "zipCode",
           "city": "city",
           "countryCode": "countryCode"
        }
    }
}

Properties

PropertyData typeDescription
paymentorderstringThe URI to the payment order the payer object belongs to.
payerobjectThe payer object.
payer.idstringThe relative URI to the current payer resource.
payer.emailstringPayer's registered email address.
payer.msisdnstringPayer'registered mobile phone number.
payer.shippingAdress.addresseobjectThe shipping address object related to the payer.
payer.shippingAdress.coAddressstringPayer' s C/o address, if applicable. 
payer.shippingAdress.streetAddressstringPayer's street address
payer.shippingAdress.zipCodestringPayer's zip code
payer.shippingAdress.citystringPayer's city of residence
payer.shippingAdress.countryCodestringCountry Code for country of residence.

Payment Menu Events

During operation in the Payment Menu, several events can occur. They are described below.

On Payment Menu Instrument Selected

This event triggers when a user actively changes payment instrument in the Payment Menu. The onPaymentMenuInstrumentSelected event is raised with the following event argument object: 

On Payment Menu Instrument Selected
{
   "name": "menu identifier",
   "instrument": "creditcard | vipps | swish | invoice",
}

Properties

PropertyTypeDescription
namestringThe name and identifier of specific instrument instances - i.e. if you deploy more than one type of credit card payments, they would be distinguished by name.
instrumentstringCreditcard, vipps, swish, invoice. The instrument selected by the user.

On Payment created

This event triggers when a user has selected a payment instrument and actively attempts to perform a payment. The onPaymentCreate event is raised with the following event argument object: 

On Payment Created
{
   "id": "/psp/creditcard/payments/653b1f5d-8e6c-4cce-d42d-08d58e414c69",
   "instrument": "creditcard | vipps | swish | invoice",
}

Properties

PropertyTypeDescription
idstringThe relative URI to the payment.
instrumentstringCreditcard, vipps, swish, invoice. The instrument selected when initiating the payment.

On Payment Completed

This event triggers when a payment has completed successfully. The onPaymentCompleted event is raised with the following event argument object:

On Payment Completed
{
   "id": "/psp/creditcard/payments/653b1f5d-8e6c-4cce-d42d-08d58e414c69",
   "redirectUrl": "https://en.wikipedia.org/wiki/Success"
}

Properties

PropertyTypeDescription
idstringThe relative URI to the payment.
redirectUrlstringThe URI the user will be redirect to after a completed payment.  

On Payment Canceled

This event triggers when the user cancels the payment. The onPaymentCanceled event is raised with the following event argument object:

On Payment Canceled
{
   "id": "/psp/creditcard/payments/653b1f5d-8e6c-4cce-d42d-08d58e414c69",
   "redirectUrl": "https://en.wikipedia.org/wiki/Canceled"
}

Properties

PropertyTypeDescription
idstringThe relative URI to the payment.
redirectUrlstringThe URI the user will be redirect to after a canceled payment.  

On Payment Failed

This event triggers when a payment has failed, disabling further attempts to perform a payment. The onPaymentFailed event is raised with the following event argument object:

On Payment Failed
{
   "id": "/psp/creditcard/payments/653b1f5d-8e6c-4cce-d42d-08d58e414c69",
   "redirectUrl": "https://en.wikipedia.org/wiki/Failed"
}

Properties

PropertyTypeDescription
idstringThe relative URI to the payment.
redirectUrlstringThe URI the user will be redirect to after a failed payment.

On Payment Terms of Service

This event triggers when the user clicks on the "Display terms and conditions" link. The onPaymentToS event is raised with the following event argument object:

On Payment Terms of Service
{
   "origin": "owner | merchant",
   "OpenUrl": "https://example.org/terms.html"
}

Properties

PropertyTypeDescription
originstringowner, merchant. The value is always merchant unless PayEx hosts the view. 
OpenUrlstringThe URI containing Terms of Service and conditions.

On Error

This event triggers during terminal errors or if the configuration fails validation. 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.

Operations

When a payment order resource is created and during its lifetime, it will have a set of operations that can be performed on it. The state of the payment order resource, what the access token is authorized to do, the chosen payment instrument and its transactional states, etc. determine the available operations before the initial purchase. A list of possible operations and their explanation is given below.

Operations
{
   "paymentOrder": {
       "id": "/psp/paymentorders/8bf85423-841d-4fb8-d754-08d6d398f0c5",
    }
   "operations": [
        {
           "method": "PATCH",
           "href": "https://api.externalintegration.payex.com/psp/paymentorders/8bf85423-841d-4fb8-d754-08d6d398f0c5",
           "rel": "update-paymentorder-abort",
           "contentType": "application/json"
        },
        {
           "method": "PATCH",
           "href": "https://api.externalintegration.payex.com/psp/paymentorders/8bf85423-841d-4fb8-d754-08d6d398f0c5",
           "rel": "update-paymentorder-updateorder",
           "contentType": "application/json"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com/paymentmenu/eb6932c2e24113377ecd88da343a10566b31f59265c665203b1287277224ef60",
           "rel": "redirect-paymentorder",
           "contentType": "text/html"
        },
        {
           "method": "GET",
           "href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=eb6932c2e24113377ecd88da343a10566b31f59265c665203b1287277224ef60&culture=nb-NO",
           "rel": "view-paymentorder",
           "contentType": "application/javascript"
        },
        {
           "method": "POST",
           "href": "https://api.externalintegration.payex.com/psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4/captures",
           "rel": "create-paymentorder-capture",
           "contentType": "application/json"
        },
        {
           "method": "POST",
           "href": "https://api.externalintegration.payex.com/psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4/cancellations",
           "rel": "create-paymentorder-cancel",
           "contentType": "application/json"
        },
        {
           "method": "POST",
           "href": "https://api.externalintegration.payex.com/psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4/reversals",
           "rel": "create-paymentorder-reversal",
           "contentType": "application/json"
        }
    ]
}

Properties

PropertyDescription
hrefThe target URI to perform the operation against.
relThe name of the relation the operation has to the current resource.
methodThe HTTP method to use when performing the operation.
contentTypeThe HTTP content type of the resource referenced in the href property.

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

Operations

Operation Description
update-paymentorder-abortAborts the payment order before any financial transactions are performed.
update-paymentorder-updateorderUpdates the order with a change in the amount and/or vatAmount.
redirect-paymentorderContains the URI that is used to redirect the consumer to the PayEx Payment Pages containing the Payment Menu.
view-paymentorderContains the JavaScript href that is used to embed the Payment Menu UI directly on the webshop/merchant site.
create-paymentorder-captureThe second part of a two-phase transaction where the authorized amount is sent from the payer to the payee. It is possible to do a part-capture on a subset of the authorized amount. Several captures on the same payment are possible, up to the total authorization amount.
create-paymentorder-cancellationUsed to cancel authorized and not yet captured transactions. If a cancellation is performed after doing a part-capture, it will only affect the not yet captured authorization amount.
create-paymentorder-reversalUsed to reverse a payment. It is only possible to reverse a payment that has been captured and not yet reversed.

View Payment Order

The view-paymentorder operation contains the URI of the JavaScript that needs to be set as a script element's src attribute, either client-side through JavaScript or server-side in HTML as shown below.

<!DOCTYPE html>
<html>
    <head>
        <title>PayEx Checkout is Awesome!</title>
    </head>
    <body>
        <div id="checkout"></div>
        <script src="https://ecom.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=38540e86bd78e885fba2ef054ef9792512b1c9c5975cbd6fd450ef9aa15b1844&culture=nb-NO"></script>
        <script language="javascript">
            payex.hostedView.paymentMenu({
                container: 'checkout',
                culture: 'nb-NO',
                onPaymentCompleted: function(paymentCompletedEvent) {
                    console.log(paymentCompletedEvent);
                },
                onPaymentFailed: function(paymentFailedEvent) {
                    console.log(paymentFailedEvent);
                },
                onPaymentCreated: function(paymentCreatedEvent) {
                    console.log(paymentCreatedEvent);
                },
                onPaymentToS: function(paymentToSEvent) {
                    console.log(paymentToSEvent);
                },
                onPaymentMenuInstrumentSelected: function(paymentMenuInstrumentSelectedEvent) {
                    console.log(paymentMenuInstrumentSelectedEvent);
                },
                onError: function(error) {
                    console.error(error);
                },
            }).open();
        </script>
    </body>
</html>

Update Order

Change amount and vat amount on a payment order. If you implement updateorder you need to refresh() the Payment Menu front end so the new amount is shown to the end customer.

Request
PATCH /psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4 HTTP/1.1
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "paymentorder": {
       "operation": "UpdateOrder",
       "amount": 2500,
       "vatAmount": 120
    }
}

Response

The response given when changing a payment order is equivalent to a GET request towards the paymentorders resource, as displayed above. Remember to call .refresh() on the Payment Menu in JavaScript

Capture

Capture can only be done on a payment with a successful authorized transaction. It is possible to do a part-capture where you only capture a smaller amount than the authorized amount. You can later do more captures on the same payment up to the total authorization amount.

To capture the authorized payment, we need to perform create-paymentorder-capture against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request
POST /psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "description": "Capturing the authorized payment",
       "amount": 15610,
       "vatAmount": 3122,
       "payeeReference": "AB832",
       "orderItems": [
            {
               "reference": "P1",
               "name": "Product1",
               "type": "PRODUCT",
               "class": "ProductGroup1",
               "itemUrl": "https://example.com/products/123",
               "imageUrl": "https://example.com/product123.jpg",
               "description": "Product 1 description",
               "discountDescription": "Volume discount",
               "quantity": 4,
               "quantityUnit": "pcs",
               "unitPrice": 300,
               "discountPrice": 200,
               "vatPercent": 2500,
               "amount": 1000,
               "vatAmount": 250
            },
            {
               "reference": "P2",
               "name": "Product2",
               "type": "PRODUCT",
               "class": "ProductGroup1",
               "description": "Product 2 description",
               "quantity": 1,
               "quantityUnit": "pcs",
               "unitPrice": 500,
               "vatPercent": 2500,
               "amount": 500,
               "vatAmount": 125
            }
        ]
    }
}

Request Properties

PropertyTypeRequiredDescription
transaction.descriptionstringYThe description of the capture transaction.
transaction.amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
transaction.vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
transaction.payeeReferencestring(30)YA unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
transaction.orderItemsarrayNThe array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. See Order Items for details.

If the capture succeeds, it should respond with something like the following:

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

{
   "payment": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251",
   "capture": {
       "id": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251/captures/af43be30-8dfa-4458-2222-08d5df73b9f1",
       "transaction": {
           "id": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251/transactions/af43be30-8dfa-4458-2222-08d5df73b9f1",
           "type": "Capture",
           "state": "Completed",
           "amount": 15610,
           "vatAmount": 3122,
           "description": "Capturing the authorized payment",
           "payeeReference": "AB832",
        }
    }
}

Response Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction belongs to.
capture.idstringThe relative URI of the created capture transaction.
capture.transactionobjectThe object representation of the generic transaction resource.

Et voilà! Checkout should now be complete, the payment should be secure and everyone should be happy. But, sometimes you also need to implement the cancellation and reversal operations described below.

Abort

To abort a payment order, perform the update-paymentorder-abort operation that is returned in the payment order response. You need to include the following HTTP body:

Request
PATCH /psp/paymentorders/5adc265f-f87f-4313-577e-08d3dca1a26c HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
 "paymentorder": {
   "operation": "Abort",
   "abortReason": "CancelledByConsumer"
  }
}

Response

The response given when aborting a payment order is equivalent to a GET request towards the paymentorders resource, as displayed above, with its state set to Aborted.

Cancel

If we want to cancel up to the total authorized (not captured) amount, we need to perform create-paymentorder-cancel against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request
POST /psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "payeeReference": "ABC123",
       "description": "Cancelling parts of the total amount"
    }
}

Request Properties

PropertyTypeRequiredDescription
transaction.payeeReferencestring(30)YA unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
transaction.descriptionstringYA textual description of why the transaction is cancelled.

If the cancellation request succeeds, the response should be similar to the example below:

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

{
   "payment": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251",
   "cancellation": {
       "id": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251/cancellations/af43be30-8dfa-4458-2222-08d5df73b9f1",
       "transaction": {
           "id": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251/transactions/af43be30-8dfa-4458-2222-08d5df73b9f1",
           "type": "Cancel",
           "state": "Completed",
           "amount": 5610,
           "vatAmount": 1122,
           "description": "Cancelling parts of the authorized payment",
           "payeeReference": "AB832",
        }
    }
}

Response Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction belongs to.
cancellation.idstringThe relative URI of the created capture transaction.
cancellation.transactionobjectThe object representation of the generic transaction resource.

Reversal

If we want to reverse a previously captured amount, we need to perform create-paymentorder-reversal against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request
POST /psp/paymentorders/b80be381-b572-4f1e-9691-08d5dd095bc4/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "amount": 15610,
       "vatAmount": 3122,
       "payeeReference": "ABC123",
       "description": "description for transaction"
    }
}

Request Properties

PropertyTypeRequiredDescription
transaction.amountintegerYThe amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
transaction.vatAmountintegerYThe amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
transaction.payeeReferencestring(30)YA unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.
transaction.descriptionstringYTextual description of why the transaction is reversed.

If the reversal request succeeds, the response should be similar to the example below:

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

{
   "payment": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251",
   "reversals": {
       "id": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251/cancellations/af43be30-8dfa-4458-2222-08d5df73b9f1",
       "transaction": {
           "id": "/psp/creditcard/payments/d34bceb7-2b19-488a-cbf2-08d5df73b251/transactions/af43be30-8dfa-4458-2222-08d5df73b9f1",
           "type": "Reversal",
           "state": "Completed",
           "amount": 5610,
           "vatAmount": 1122,
           "description": "Reversing the capture amount",
           "payeeReference": "ABC987",
        }
    }
}

Response Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this reversal transaction belongs to.
reversal.idstringThe relative URI of the created reversal transaction.
reversal.transactionobjectThe object representation of the generic transaction resource.
Created by Fredrik Köhler on 2018/10/26 11:08