Payment
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
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.
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
| Param | Details |
| 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.
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.
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>
{
"transaction": {
"amount": 100.00,
"vatAmount": 20.00,
"description": "Test Reversal"
}
}
Parameters
| Param | Details |
| 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.