Retrieve Payment

An implementer must first perform a POST to the Payment Session resource to begin the PayEx Checkout user flow. When done, a Payment resource will be created. Operations to perform a Capture, Cancel or Reversal transaction requests will be found within the Payment resource.

The URL of the Payment is found within the Payment Session resource. Read about how to retrieve the payment session here. This resource requires authentication as mentioned in the Intro.

Example

Request

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

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"
        },
    },
   "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"
        }
    ]
}

Operations

The available operations that can be performed on a Payment will be listed inside the operations property. For documentation on these operations, please see below.

Capture

To perform a Capture operation in PayEx Checkout, you find the create-checkout-capture operation listed in the Payment resource. It will look something like this:

{
    ...
   "operations": [{
         "href": "<capture_operation_url>"
         "rel": "create-checkout-capture",
         "method": "POST"
    },
    {
          ...
    }]
    ...
}

Simple capture request

Build the Capture request by finding the href and method properties of the create-checkout-capture operation.

The simple Capture request does a full capture of the amount and fees specified in the Payment Session. Unless you want to perform a partial Capture or add item descriptions, the simple Capture is the recommended way to Capture the payment.

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

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

Parameters

Param Details
description
string
Description of the item you are capturing.

Advanced capture request

If you want to Capture less than the total amount of the Payment (partial capture) or add additional item descriptions that may be printed on an invoice. The advanced Capture adds any fees specified in the Payment Session. An advanced Capture request may look something like this:

{
   "transaction": {
       "amount": 350.00,
       "vatAmount": 70.00,               // Note: please see the valid VAT rates in the parameter description below.
       "description": "description for transaction"
       "payeeReference": "reference of the Capture. Will be shown on Invoice"
    },
   "itemDescriptions": [{
           "amount": 250.00,
           "vatAmount": 50.00,           // Note: please see the valid VAT rates in the parameter description below.
           "itemAmount": 50.00,
           "quantity": 5,
           "description": "item description 1"
        },
        {
           "amount": 100.00,
           "vatAmount": 20.00,           // Note: please see the valid VAT rates in the parameter description below.
           "itemAmount": 50.00,
           "quantity": 2,
           "description": "item description 2"
        }
    ]
}

Parameters

ParamDetails
transaction.amount
decimal
Total amount of the transaction (sum of itemDescriptions.amount), including VAT.
transaction.vatAmount
decimal
Total VAT amount of the transaction.  Note: Due to legal requirements, VAT must be calculated from the following valid rates:   0%, 6%, 8%, 10%, 12%, 14%, 15%, 22%, 24% and 25%. All other VAT rates will be declined and cause an input validation error.
transaction.description
string
Description of the transaction.
transaction.payeeReference
string
The reference of the order capture. This reference will be visible on Invoice payment if consumer has paid with invoice. Must match the regular expression ^\w*$ and be no longer than 40 characters.
itemDescriptions.amount
decimal
The total amount of the items (itemAmount * quantity), including VAT.
itemDescriptions.vatAmount
decimal
Total VAT amount of the items (not divided by quantity).
itemDescriptions.itemAmount
decimal
Amount per item, VAT included.
itemDescriptions.quantity
integer
Number of items.
itemDescriptions.description
string
Description of the item (order line, product, shopping cart item, or similar).

Capture response

{
   "payment": "<paymentUrl>",
   "capture": {
       "id": "<paymentCaptureUurl>",
       "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": 350.00,
           "vatAmount": 70.00,
           "description": "Test Capture",
           "payeeReference": "ABC123",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }
    }
}

Cancellation

To perform a Cancellation operation in PayEx Checkout, you find the create-checkout-cancellation operation listed in the Payment resource.
It will look something like this:

...
"operations": [{
   "href": "<cancellation_operation_url>"
   "rel": "create-checkout-cancellation",
   "method": "POST"
} ... ]
...

Cancellation request

Build the Cancellation request by finding the href and method properties of the create-checkout-cancellation operation.

The Cancellation request does a full cancellation of the amount and fees specified in the Payment Session

POST <cancel_operation_href> HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

{
   "transaction": {
       "description": "Test Cancellation",
    }
}

Parameters

Param Details
Description
string
Description of the item you are canceling.

Cancel response

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

Reversal

To perform a Reversal operation in PayEx Checkout, you find the create-checkout-reversal operation listed in the Payment resource.
It will look something like this:

{
    ...
   "operations": [{
       "href": "<reversal_operation_url>",
       "rel": "create-checkout-reversal",
       "method": "POST"
    },
    {
        ...
    }]
    ...
}

Reversal request

Build the Reversal request by finding the href and method properties of the create-checkout-reversal operation.

The Reversal request does a reversal of the amount specified in the Request. 

POST <reversal_operation_href> HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

{
   "transaction": {
       "amount": 100.00,
       "vatAmount": 20.00,
       "description": "Test Reversal"
    }
}

Parameters

ParamDetails
transaction.amount
decimal
Total amount of the transaction vat included.
transaction.vatAmount
decimal
Total vat amount of the transaction.
transaction.description
string
Description of the transaction

Reversal response

{
   "payment": "<paymentUrl>",
   "reversal": {
       "id": "<paymentReversalUrl>",
       "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": 1000,
           "vatAmount": 200,
           "description": "Testtransaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }
    }
}

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 this here.

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

Tips

You can click on the arrows next to the breadcrumb elements to quickly navigate to sibling and children pages.

Need help?

If you need help with XWiki you can contact: