Digital Payments – Automated Fuel Dispenser Payments

Automated Fuel Dispenser Payments

This feature is only available for merchants who have a specific agreement with Swedbank Pay.

An Automated Fuel Dispenser (AFD) payment is a purchase where the user requests an authorization transaction for an automatic fuel dispenser. The request contains the maximum purchase amount, but the issuer can reply with a partial approval to lower the maximum purchase amount. This can be used to stop the fuel dispension at the maximum price.

The only supported use case is automated fuel dispensers. To be able to verify this, it is required that the Merchant Category Code mcc is passed in the request under PayeeInfo. This feature is only supported with the Purchase operation. It does not support with order items.

By default the available instruments and card types will be limited to those which support AFD payments. To enable other payment options for the payer, pass in restrictedToAfdInstruments with the value false.

See the abbreviated example below on how to implement AFD payments by setting the generateAfdPayment to true.

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

POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0      // Version optional for 3.0 and 2.0

{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 10000,
        "vatAmount": 2500,
        "generateAfdPayment": true,
        "restrictedToAfdInstruments": true,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ], 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditions.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "mcc": 5542
        },
        "orderItems": null
    }
}

Request fields not covered in the common Digital Payments Initialized redirect or seamless view table:

Field	Type	Description
`generateAfdPayment`	`bool`	Set to `true` if the payment order is an AFD payment, `false` if not.
`restrictedToAfdInstruments`	`bool`	Set to `true` if the payment menu should show only payment options that support AFD, `false` to show all options. Default is true when using `generateAfdPayment`.
`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
`mcc`	`integer`	The merchant category code used for the purchase, 4 digits.

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
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1/3.0/2.0
api-supported-versions: 3.1/3.0/2.0

{
    "paymentorder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
        "created": "2020-06-22T10:56:56.2927632Z",
        "updated": "2020-06-22T10:56:56.4035291Z",
        "operation": "Purchase",
        "status": "Initialized",
        "currency": "SEK",
        "amount": 10000,
        "vatAmount": 2500,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "language": "sv-SE",
        "availableInstruments": [ "CreditCard" ],
        "implementation": "PaymentsOnly",  
        "instrumentMode": false,
        "guestMode": false,
        "orderItems": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/orderitems"
        },
        "urls": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/urls"
        },
        "payeeInfo": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/payeeinfo"
        },
        "payer": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/payers"
        },
        "history": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/history"
        },
        "failed": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/failed"
        },
        "aborted": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/aborted"
        },
        "paid": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/paid"
        },
        "cancelled": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/cancelled"
        },
        "financialTransactions": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/financialtransactions"
        },
        "failedAttempts": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/failedattempts"
        },
        "metadata": {
            "id": "/psp/paymentorders/08090909-626e-4b90-1943-08d9eaebca86/metadata"
        }
    },
      "operations": [  
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel":"update-order",
          "method":"PATCH",
          "contentType":"application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel": "abort",
          "method": "PATCH",
          "contentType": "application/json"
        }
       ]
      }

When The Authorization Is Completed

The authorized amount might be a lower value than the requested amount, known as partial approval. In this case, the original submitted amount might be found by requesting rel:paid-paymentorder and checking the field submittedAmount. Then the amount and vatAmount will contain the value that is authorized. The final amount to be paid must be passed in the capture request, and if the authorized amount is larger than the final amount the rest should be cancelled.

Capture

Captures are only possible when a payment has a successful authorize transaction, naturally excluding one-phase payment instruments like Swish and Trustly. Two-phase payment instruments like Card and Vipps however, require a Capture to be completed.

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

In addition to full captures, it is possible to do partial captures of a part of the authorized amount. You can do other captures on the same payment later, up to the total authorized amount. Useful for when you have to split orders into several shipments, for instance.

First off, you must request the order information from the server to get the request link. With this, you can request the capture with the amount to capture, and get the status back.

To capture the authorized payment, we need to perform capture against the accompanying href returned in the operations list. See the abbreviated request and response below:

Capture Request

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
46

POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.0/2.0      // Version optional

{
    "transaction": {
        "description": "Capturing the authorized payment",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "AB832",
        "receiptReference": "AB831",
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product 2 description",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}

Show fields

Required	Field	Type	Description
	`transaction`	`object`	The transaction object.
	`description`	`string`	The description of the capture transaction.
	`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. The amount displayed is the final amount the payer paid for their order, including any instrument specific discounts or fees.
	`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.
	`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(30)`	A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to `payeeReference`.
	`orderItems`	`array`	The array of items being purchased with the order. Note that authorization `orderItems` will not be printed on invoices, so lines meant for print must be added in the Capture request. The authorization `orderItems` will, however, be used in the Merchant Portal when captures or reversals are performed, and might be shown other places later. It is required to use this field to be able to send Capture `orderItems`. `Capture` requests should only contain items meant to be captured from the order.
	`reference`	`string`	A reference that identifies the order item.
	`name`	`string`	The name of the order item.
	`type`	`enum`	`PRODUCT`, `SERVICE`, `SHIPPING_FEE`, `PAYMENT_FEE`, `DISCOUNT`, `VALUE_CODE` or `OTHER`. The type of the order item.
	`class`	`string`	The classification of the order item. Can be used for assigning the order item to a specific product category, such as `MobilePhone`. Note that `class` cannot contain spaces and must follow the regex pattern `[\w-]*`. Swedbank Pay may use this field for statistics.
	`itemUrl`	`string`	The URL to a page that can display the purchased item, product or similar.
︎︎︎	`imageUrl`	`string`	The URL to an image of the order item.
	`description`	`string`	The human readable description of the order item.
	`discountDescription`	`string`	The human readable description of the possible discount.
	`quantity`	`number`	The 4 decimal precision quantity of order items being purchased.
	`quantityUnit`	`string`	The unit of the quantity, such as `pcs`, `grams`, or similar. This is used for your own book keeping.
	`unitPrice`	`integer`	The price per unit of order item, including VAT.
	`discountPrice`	`integer`	If the order item is purchased at a discounted price. This field should contain that price, including VAT.
	`vatPercent`	`integer`	The percent value of the VAT multiplied by 100, so `25%` becomes `2500`.
	`amount`	`integer`	The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. `10000` equals `100.00 SEK` and `5000` equals `50.00 SEK`.
	`vatAmount`	`integer`	The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. `10000` equals `100.00 SEK` and `5000` equals `50.00 SEK`.
	`reference`	`string`	A reference that identifies the order item.
	`name`	`string`	The name of the order item.
	`type`	`enum`	`PRODUCT`, `SERVICE`, `SHIPPING_FEE`, `PAYMENT_FEE`, `DISCOUNT`, `VALUE_CODE` or `OTHER`. The type of the order item.
	`class`	`string`	The classification of the order item. Can be used for assigning the order item to a specific product category, such as `MobilePhone`. Note that `class` cannot contain spaces and must follow the regex pattern `[\w-]*`. Swedbank Pay may use this field for statistics.
︎︎︎	`itemUrl`	`string`	The URL to a page that can display the purchased item, such as a product page
︎︎︎	`imageUrl`	`string`	The URL to an image of the order item.
︎︎︎	`description`	`string`	The human readable description of the order item.
︎︎︎	`discountDescription`	`string`	The human readable description of the possible discount.
	`quantity`	`number`	The 4 decimal precision quantity of order items being purchased.
	`quantityUnit`	`string`	The unit of the quantity, such as `pcs`, `grams`, or similar.
	`unitPrice`	`integer`	The price per unit of order item, including VAT.
︎︎︎	`discountPrice`	`integer`	If the order item is purchased at a discounted price. This field should contain that price, including VAT.
	`vatPercent`	`integer`	The percent value of the VAT multiplied by 100, so `25%` becomes `2500`.
	`amount`	`integer`	The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. `10000` equals `100.00 NOK` and `500`0 equals `50.00 NOK`.
	`vatAmount`	`integer`	The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. `10000` equals `100.00 NOK` and `500`0 equals `50.00 NOK`.

Capture Response

If the capture request succeeds, this should be the response:

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.0/2.0
api-supported-versions: 3.0/2.0

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2020-06-22T10:56:56.2927632Z",
            "updated": "2020-06-22T10:56:56.4035291Z",
            "type": "Capture",
            "state": "Completed",
            "amount": 1500,
            "vatAmount": 375,
            "description": "Capturing the authorized payment",
            "payeeReference": "AB832",
            "receiptReference": "AB831"
        }
    }
}

Show fields

Property	Type	Description
`payment`	`string`	The relative URL of the payment this capture transaction belongs to.
`capture`	`object`	The capture object, containing the information about the capture transaction.
`id`	`string`	The relative URL of the created capture transaction.
`transaction`	`object`	The object representation of the generic `transaction` resource, containing information about the current transaction.
`id`	`string`	The relative URL of the current `transaction` resource.
`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 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. The amount displayed is the final amount the payer paid for their order, including any instrument specific discounts or fees.
`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(30)`	A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. It is used to supplement `payeeReference` as an additional receipt number.

Capture Sequence Diagram

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        activate Merchant
        note left of Payer: Capture
        Merchant ->>+ SwedbankPay: rel:capture
        deactivate Merchant
        SwedbankPay -->>- Merchant: Capture status
        note right of Merchant: Capture here only if the purchased<br/>goods don't require shipping.<br/>If shipping is required, perform capture<br/>after the goods have shipped.<br>Should only be used for <br>Payment Instruments that support <br>Authorizations.
    end