warning

Two-phase payments: When dealing in physical goods using two-phase payment methods, all goods must be shipped before you capture the authorized amount. This is regulated in part by the Swedish Distance and Doorstep Sales Act, required in our terms and (for card payments) required by Visa and Mastercard.

Capture

The capture transaction is where you ensure that the funds are drawn from the payer. This step usually takes place when the product has exchanged possession. You must first do a GET request on the payment to find the create-capture operation.

Please note that you have a maximum of 5 consecutive failed attempts at a reversal. The payment will be locked after this, and you need to contact us for another attempt.

Create Capture Transaction

To create a capture transaction to withdraw money from the payer’s Vipps account, you need to perform the create-capture operation.

Capture Request

Request

1
2
3
4
POST /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
1
2
3
4
5
6
7
8
{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "payeeReference": "cpttimestamp",
        "description" : "description for transaction"
    }
}
Required Field Type Description
check transaction object The object representation of the generic transaction resource, containing information about the current transaction.
check amount integer Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK.
check vatAmount integer Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK.
check description string A textual description of the capture transaction.
check payeeReference string A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits.

Capture Response

The created capture resource contains information about the capture transaction made against a vipps payment.

Capture Response

Response

1
2
3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0
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
34
35
36
{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Capture",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "ABC123", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/vipps/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-capture",
                    "method": "PATCH"
                }
            ]
        }
    }
}
Field Type Description  
paymentOrder string The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.  
id string The relative URL and unique identifier of the capture resource . 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 . 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, containing information about the current transaction.  
id string The relative URL and unique identifier of the transaction resource . 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 or failed. If a partial capture has been done and further transactions are possible, the state will be awaitingActivity.  
number integer 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. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
receiptReference string A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.  
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.  

List Capture Transactions

The captures resource lists the capture transactions (one or more) on a specific payment.

Transaction List Request

Request

1
2
3
4
GET /psp/vipps/vipps/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
1
2
3
4
5
6
7
8
{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "payeeReference": "cpttimestamp",
        "description" : "description for transaction"
    }
}

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

Transaction List Response

Response

1
2
HTTP/1.1 200 OK
Content-Type: application/json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "captures": { 
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
        "captureList": [{
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                "created": "2016-09-14T01:01:01.01Z",
                "updated": "2016-09-14T01:01:01.03Z",
                "type": "Capture",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}
Field Type Required
paymentOrder string The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
id string The relative URL and unique identifier of the captures resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
{{ transaction }}List array The array of capture transaction objects.
{{ transaction }}List[] object The capture transaction object described in the capture resource below.
id string The relative URL and unique identifier of the transaction resource . 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 or failed. If a partial capture has been done and further transactions are possible, the state will be awaitingActivity.
number integer 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. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. 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.

Capture Sequence Diagram

Capture can only be done on an authorized transaction. It is possible to do a partial capture where you only capture a part of the authorized amount. You can do more captures on the same payment up to the total authorization amount later.

sequenceDiagram
  activate Merchant
  Merchant->>-SwedbankPay: POST [Vipps captures]
  activate SwedbankPay
  SwedbankPay-->>-Merchant: transaction resource

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

Authorizations are kept valid in our systems for 180 days, and we accept captures within this timeframe. Please be aware that acquirers might have a shorter time limit before authorized amounts are released in their systems. We advise you to check with your acquirer if you have concerns about these limits.