Checkout v2

Transactions

schedule 3 min read

The transactions making up a specific payment.

Edit "Transactions" on GitHub

Transactions

A payment contains sub-resources in the form of transactions. Most operations performed on a payment ends up as a transaction resource. The different types of operations that alter the state of the payment by creating a transaction is described below.

The transactions resource will list the transactions (one or more) on a specific payment.

Request

1
2
3
4
GET /psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The transaction resource contains information about the transaction transaction made against a checkout/v2 payment. You can return a specific transaction transaction by performing a GET request towards the specific transaction’s id.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transactions": { 
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions",
        "transactionList": [{
            "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                "created": "2016-09-14T01:01:01.01Z",
                "updated": "2016-09-14T01:01:01.03Z",
                "type": "Transaction",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}
Field Type Required
payment string The relative URL and unique identifier of the payment resource this transactions belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
transactions object The current transactions resource.
└➔ id string The relative URL and unique identifier of the transactions resource this transactions belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
└➔ transactionList array The array of transaction transaction objects.
└➔ transactionList[] object The transaction transaction object described in the transaction resource below.
└─➔ id string The relative URL and unique identifier of the transaction resource this transactions belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
└─➔ created string The ISO-8601 date and time of when the transaction was created.
└─➔ updated string The ISO-8601 date and time of when the transaction was updated.
└─➔ type string Indicates the transaction type.
└─➔ state string Indicates the state of the transaction, usually initialized, completed orfailed. If a partial transaction has been done and further transactionsare possible, the state will be awaitingActivity.
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id should be used instead.
└─➔ amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
└─➔ vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
└─➔ description string A 40 character length textual description of the purchase.
└─➔ payeeReference string A 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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
└─➔ isOperational bool true if the transaction is operational; otherwise false.
└─➔ operations array The array of operations that are possible to perform on the transaction in its current state.

Transaction

The transaction resource contains the generic details of a transaction on a specific payment.

When a transaction is created it will have one of three states:

  • Initialized - if there is some error where the source is undeterminable (network failure, etc), the transaction will remain Initialized. The corresponding state of the payment order will in this case be set to pending. No further transactions can be created.
  • Completed - if everything went ok the transaction will follow through to completion.
  • Failed - if the transaction has failed (i.e. a denial from the acquiring bank) it is possible to retry (i.e the payer tries using another card) up to a maximum amount of retries (in that case which the payment order gets the state failed as well).

Request

1
2
3
4
GET /psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transaction": {
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "created": "2016-09-14T01:01:01.01Z",
        "updated": "2016-09-14T01:01:01.03Z",
        "type":  "Capture", 
        "state": "Initialized",
        "number": 1234567890,
        "amount": 1000,
        "vatAmount": 250,
        "description": "Test transaction",
        "payeeReference": "AH123456",
        "failedReason": "",
        "isOperational": true,
        "operations": []
    }
}

Transaction Problems

In the event that a transaction is failed, the transaction response will contain a problem property as seen in the example below. To view all the problems that can occur due to an unsuccesful transaction, head over to the problems section.

The created transaction resource contains information about the transaction transaction made against a checkout/v2 payment.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transaction": {
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Transaction",
            "state": "Failed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/checkout/v2/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
        }
    }
}

Field Type Description  
payment string The relative URL and unique identifier of the payment resource this transaction belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.  
transaction string The current transaction transaction resource.  
└➔ id string The relative URL and unique identifier of the transaction resource this transaction belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.  
└➔ itemDescriptions object The object representation of the itemDescriptions resource.  
└─➔ id string The relative URL and unique identifier of the itemDescriptions resource this transaction belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.  
└➔ transaction object The object representation of the generic transaction resource.  
└─➔ id string The relative URL and unique identifier of the transaction resource this transaction belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.  
└─➔ created string The ISO-8601 date and time of when the transaction was created.  
└─➔ updated string The ISO-8601 date and time of when the transaction was updated.  
└─➔ type string Indicates the transaction type.  
└─➔ state string Indicates the state of the transaction, usually initialized, completed orfailed. If a partial transaction has been done and further transactionsare possible, the state will be awaitingActivity.  
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id should be used instead.  
└─➔ amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
└─➔ vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.  
└─➔ description string A 40 character length textual description of the purchase.  
└─➔ payeeReference string A 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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
└─➔ receiptReference string A unique reference for the transaction. This reference is used as an invoice/receipt number.  
└─➔ failedReason string The human readable explanation of why the payment failed.  
└─➔ isOperational bool true if the transaction is operational; otherwise false.  
└─➔ operations array The array of operations that are possible to perform on the transaction in its current state.