Vipps – After Payment

Create Payment

To create a Vipps payment, you perform an HTTP POST against the /psp/vipps/payments resource.

An example of a payment creation request is provided below. Each individual field of the JSON document is described in the following section. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

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
37
38
39
40
41
42
43
44
45

POST /psp/vipps/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "NOK",
        "prices": [
            {
                "type": "Vipps",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Vipps Test",
        "userAgent": "Mozilla/5.0",
        "language": "nb-NO",
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "paymentUrl": "https://example.com/perform-payment",
            "callbackUrl": "https://api.externalintegration.payex.com/psp/payment-callback",
            "logoUrl": "https://example.com/path/to/logo.png",
            "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "Postmantimestamp",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {  
            "payerReference": "AB1234",
        },
        "prefillInfo": {
            "msisdn": "+4793000001"
        }
    }
}

Required	Field	Type	Description
︎	`payment`	`object`	The `payment` object.
︎	└➔ `operation`	`string`	`Purchase`
︎	└➔ `intent`	`string`	`Authorization`
︎	└➔ `currency`	`string`	NOK
︎	└➔ `prices`	`object`	The `prices` object.
︎	└─➔ `type`	`string`	`vipps`
︎	└─➔ `amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` NOK, `5000` = `50.00` NOK.
︎	└─➔ `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` NOK, `5000` = `50.00` NOK. 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(40)`	A 40 character length textual description of the purchase.
︎	└➔ `userAgent`	`string`	The user agent reference of the payer’s browser - see user agent
︎	└➔ `language`	`string`	`sv-SE`, `nb-NO` or `en-US`.
︎	└➔ `urls`	`object`	The object containing URLs relevant for the `payment`.
︎	└─➔ `hostUrls`	`array`	The array of URIs valid for embedding of Swedbank Pay Hosted Views.
︎	└─➔ `completeUrl`	`string`	The URI that Swedbank Pay will redirect back to when the payment page is completed. This does not indicate a successful payment, only that it has reached a completion state. A `GET` request needs to be performed on the payment to inspect it further. See `completeUrl` for details.
	└─➔ `cancelUrl`	`string`	The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an `abort` request of the `payment`.
	└─➔ `paymentUrl`	`string`	The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the `payment`. See `paymentUrl` for details.
	└─➔ `callbackUrl`	`string`	The URI that Swedbank Pay will perform an HTTP `POST` request against every time a transaction is created on the payment. See callback for details.
	└─➔ `logoUrl`	`string`	The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS.
	└─➔ `termsOfServiceUrl`	`string`	The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless `generateReferenceToken` or `generateRecurrenceToken` is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement.
︎	└➔ `payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
︎	└─➔ `payeeId`	`string`	This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
︎	└─➔ `payeeReference`	`string(30)`	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.
	└─➔ `payeeName`	`string`	The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
	└─➔ `productCategory`	`strin`	A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process.
	└─➔ `orderReference`	`string(50)`	The order reference should reflect the order reference found in the merchant’s systems.
	└─➔ `subsite`	`string(40)`	The `subsite` field can be used to perform split settlement on the payment. The `subsites` must be resolved with Swedbank Pay reconciliation before being used.
	└➔ `payer`	`string`	The `payer` object, containing information about the payer.
	└─➔ `payerReference`	`string`	The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if `generateReccurenceToken`, `RecurrenceToken`, `generatePaymentToken` or `paymentToken` is `true`.
	└➔ `prefillInfo`	`object`	An object that holds prefill information that can be inserted on the payment page.
	└─➔ `msisdn`	`string`	Number will be prefilled on payment page, if valid. Only Norwegian phone numbers are supported. The country code prefix is +47

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
        "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 72100003079,
        "created": "2018-09-05T14:18:44.4259255Z",
        "instrument": "Vipps",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Ready",
        "currency": "NOK",
        "prices": {
            "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "amount": 0,
        "description": "Vipps Test",
        "initiatingSystemUserAgent": "PostmanRuntime/7.2.0",
        "userAgent": "Mozilla/5.0 weeeeee",
        "language": "nb-NO",
        "urls": {
            "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "payeeInfo": {
            "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
        },
        "payers": {
           "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "metadata": {
            "id": "/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"
        }
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/vipps/payments/authorize/afccf3d0016340620756d5ff3e08f69b555fbe2e45ca71f4bd159ebdb0f00065",
            "rel": "redirect-authorization"
        }
    ]
}

Purchase

Posting a payment (operation Purchase) returns the options of aborting the payment altogether or creating an authorization transaction through the redirect-authorization hyperlink.

Request

1
2
3
4
5

{
    "payment": {
        "operation": "Purchase"
    }
}

Operations

When a payment resource is created and during its lifetime, it will have a set of operations that can be performed on it. Which operations are available will vary depending on the state of the payment resource, what the access token is authorized to do, etc.

Field	Description
`href`	The target URI to perform the operation against.
`rel`	The name of the relation the operation has to the current resource.
`method`	The HTTP method to use when performing the operation.

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

Operation	Description
`update-payment-abort`	Aborts the payment before any financial transactions are performed.
`redirect-authorization`	Used to redirect the payer to Swedbank Pay Payments and the authorization UI.
`create-capture`	Creates a `capture` transaction.
`create-cancellation`	Creates a `cancellation` transaction.
`create-reversal`	Creates a `reversal` transaction.

Vipps transactions

All Vipps after payment transactions are described below.

Authorizations

The authorizations resource contains information about the authorization transactions made on a specific payment.

Request

1
2
3
4

GET /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The created authorization resource contains information about the authorization transaction made against a `` 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
34
35
36
37
38
39
40

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp//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": "Authorization",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail//3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-authorization",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Field	Type	Description
`payment`	`string`	The relative URI and unique identifier of the `payment` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
`authorization`	`string`	The current `authorization` transaction resource.
└➔ `id`	`string`	The relative URI and unique identifier of the `authorization` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `itemDescriptions`	`object`	The object representation of the `itemDescriptions` resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `itemDescriptions` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `transaction`	`object`	The object representation of the generic transaction resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `transaction` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs 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 authorization 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.

Request

1
2
3
4

GET /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The created authorization resource contains information about the authorization transaction made against a `` 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
34
35
36
37
38
39
40

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp//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": "Authorization",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail//3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-authorization",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Field	Type	Description
`payment`	`string`	The relative URI and unique identifier of the `payment` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
`authorization`	`string`	The current `authorization` transaction resource.
└➔ `id`	`string`	The relative URI and unique identifier of the `authorization` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `itemDescriptions`	`object`	The object representation of the `itemDescriptions` resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `itemDescriptions` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `transaction`	`object`	The object representation of the generic transaction resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `transaction` resource this `authorization` belongs to.. Please read about URI Usage to understand how this and other URIs 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 authorization 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.

Cancellations

The cancellations resource lists the cancellation transactions on a specific payment.

Request

1
2
3
4

GET /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The cancel resource contains information about the cancel transaction made against a payment. You can return a specific cancel 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//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancellations": { 
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations",
        "cancelList": [{
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp//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": "Cancel",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Field	Type	Required
`payment`	`string`	The relative URI and unique identifier of the `payment` resource this `cancellations` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
`cancellations`	`object`	The current `cancellations` resource.
└➔ `id`	`string`	The relative URI and unique identifier of the `cancellations` resource this `cancellations` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `cancelList`	`array`	The array of cancel transaction objects.
└➔ `cancelList[]`	`object`	The cancel transaction object described in the `cancel` resource below.
└─➔ `id`	`string`	The relative URI and unique identifier of the `transaction` resource this `cancellations` belongs to.. Please read about URI Usage to understand how this and other URIs 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 cancel 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.

Create cancellation transaction

A payment may be cancelled if the rel create-cancellation is available. You can only cancel a payment, or part of it, if it has yet to be captured. To revert a capture, or part of a capture, you must perform a reversal. Performing a cancellation will cancel all the remaining authorized amount on a payment.

Request

1
2
3
4
5
6
7
8
9
10
11

POST /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "payeeReference": "testabc",
        "description" : "description for transaction"
    }
}

The created cancel resource contains information about the cancel transaction made against a `` 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
34
35
36
37
38
39
40

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancel": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp//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": "Cancel",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail//3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-cancel",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Field	Type	Description
`payment`	`string`	The relative URI and unique identifier of the `payment` resource this `cancel` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
`cancel`	`string`	The current `cancel` transaction resource.
└➔ `id`	`string`	The relative URI and unique identifier of the `cancel` resource this `cancel` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `itemDescriptions`	`object`	The object representation of the `itemDescriptions` resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `itemDescriptions` resource this `cancel` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `transaction`	`object`	The object representation of the generic transaction resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `transaction` resource this `cancel` belongs to.. Please read about URI Usage to understand how this and other URIs 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 cancel 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.

Reversals

The reversals resource lists the reversal transactions (one or more) on a specific payment.

Request

1
2
3
4

GET /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The reversal resource contains information about the reversal transaction made against a payment. You can return a specific reversal 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//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversals": { 
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals",
        "reversalList": [{
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp//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": "Reversal",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Field	Type	Required
`payment`	`string`	The relative URI and unique identifier of the `payment` resource this `reversals` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
`reversals`	`object`	The current `reversals` resource.
└➔ `id`	`string`	The relative URI and unique identifier of the `reversals` resource this `reversals` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `reversalList`	`array`	The array of reversal transaction objects.
└➔ `reversalList[]`	`object`	The reversal transaction object described in the `reversal` resource below.
└─➔ `id`	`string`	The relative URI and unique identifier of the `transaction` resource this `reversals` belongs to.. Please read about URI Usage to understand how this and other URIs 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 reversal 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.

Create reversal transaction

A reversal transaction can be created if the rel create-reversal is available.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13

POST /psp/vipps/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "payeeReference": "cpttimestamp",
        "description" : "description for transaction"
    }
}

Field	Type	Description
`transaction`	`object`	The transaction object.
└➔ `amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` NOK, `5000` = `50.00` NOK.
└➔ `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` NOK, `5000` = `50.00` NOK. 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 textual description of the capture
└➔ `payeeReference`	`string(50)`	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.

The created reversal resource contains information about the reversal transaction made against a `` 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
34
35
36
37
38
39
40

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversal": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp//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": "Reversal",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail//3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-reversal",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Field	Type	Description
`payment`	`string`	The relative URI and unique identifier of the `payment` resource this `reversal` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
`reversal`	`string`	The current `reversal` transaction resource.
└➔ `id`	`string`	The relative URI and unique identifier of the `reversal` resource this `reversal` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `itemDescriptions`	`object`	The object representation of the `itemDescriptions` resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `itemDescriptions` resource this `reversal` belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.
└➔ `transaction`	`object`	The object representation of the generic transaction resource.
└─➔ `id`	`string`	The relative URI and unique identifier of the `transaction` resource this `reversal` belongs to.. Please read about URI Usage to understand how this and other URIs 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 reversal 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.

Abort

To abort a payment, perform the update-payment-abort operation that is returned in the payment request. You need to include the following HTTP body:

Request

1
2
3
4
5
6
7
8
9
10
11

PATCH /psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
  "payment": {
    "operation": "Abort",
    "abortReason": "CancelledByConsumer"
  }
}

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
34
35
36
37

HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 70100130293,
        "created": "2019-01-09T13:11:28.371179Z",
        "updated": "2019-01-09T13:11:46.5949967Z",
        "instrument": "",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Aborted",
        "currency": "SEK",
        "prices": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "amount": 0,
        "description": " Test",
        "initiatingSystemUserAgent": "PostmanRuntime/7.1.1",
        "userAgent": "Mozilla/5.0",
        "language": "sv-SE",
        "urls": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "payeeInfo": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
        },
        "payers": {
           "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "metadata": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"
        }
    },
    "operations": []
}

The response will be the payment resource with its state set to Aborted.