Sandbox.payex-checkout-v1.Introduction.Payment - Payment 
Page of - last modified by Trieu Tran on 2019/12/04 14:12 
Payment 

Trieu Tran

2019/12/04 14:12
Table of Contents
Retrieve Payment
Example
Request
Response
Operations
Capture
Simple capture request
Advanced capture request
Capture response
Cancellation
Cancellation request
Cancel response
Reversal
Reversal request
Reversal response
Problems

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

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

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

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

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.