Invoice

Direct

Direct is a payment service where Swedbank Pay helps improve cashflow by purchasing merchant invoices. Swedbank Pay receives invoice data, which is used to produce and distribute invoices to the payer.

Edit "Direct" on GitHub
report_problem

Availability: Note that this invoice integration is no longer available in Sweden. If you are a Swedish merchant and wish to offer invoice as a payment option, this has to be done through our payment order implementation.

Invoice Direct Implementation Flow

  1. Collect all purchase information and send it in a POST request to Swedbank Pay. Make sure to include personal information (SSN and postal code).

  2. Make a new POST request towards Swedbank Pay to retrieve the name and address of the customer to create a purchase.

  3. Create a POSTrequest to retrieve the transaction status.

  4. Send a GET request with the paymentID to get the authorization result.

  5. Make a Capture by creating a POST request.

  • An invoice payment is always two-phased based - you create an Authorize transaction, that is followed by a Capture or Cancel request. The Capture , Cancel, Reversal opions are described in features.
info

Note that the invoice will not be created/distributed before you have made a capture request. By making a Capture, Swedbank Pay will generate the invoice to the payer and the order is ready for shipping.

link

Callback URL: It is mandatory to set a callbackUrl in the POST request creating the payment. When callbackUrl is set, Swedbank Pay will send a POST request to this URL when the payer has fulfilled the payment. Upon receiving this POST request, a subsequent GET request towards the id of the payment generated initially must be made to receive the state of the transaction.

The 3 most important steps in the Invoice Direct flow are shown below.

Step 1: Create A Purchase

Our payment example below uses the FinancingConsumer value.

warning

GDPR: GDPR sensitive data such as email, phone numbers and social security numbers must not be used directly in request fields such as payerReference. If it is necessary to use GDPR sensitive data, it must be hashed and then the hash can be used in requests towards Swedbank Pay.

Financing Consumer 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



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

{
    "payment": {
        "operation": "FinancingConsumer",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [
            {
                "type": "Invoice",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "generatePaymentToken": false,
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls": {
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/logo.png",
            "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "PR123",
            "payeeName": "Merchant1",
            "productCategory": "PC1234",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        }
    },
    "invoice": {
        "invoiceType": "PayExFinancingSe"
    }
}
Required Field Type Description
check︎︎︎︎︎ payment object The payment object contains information about the specific payment.
check︎︎︎︎︎ operation string The operation that the payment is supposed to perform. The FinancingConsumer operation is used in our example.
check︎︎︎︎︎ intent string Authorization is the only intent option for invoice. Reserves the amount, and is followed by a cancellation or capture of funds.
check︎︎︎︎︎ currency string NOK, SEK, DKK, USD or EUR.
check︎︎︎︎︎ prices object The prices resource lists the prices related to a specific payment.
check︎︎︎︎︎ type string Use the value ``.See the prices resource for more information.
check︎︎︎︎︎ 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.
check︎︎︎︎︎ 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.
check︎︎︎︎︎ description string(40) A 40 character length textual description of the purchase.
check︎︎︎︎︎ userAgent string The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser.
check︎︎︎︎︎ language string sv-SE, nb-NO or en-US.
check︎︎︎︎︎ urls object The urls resource lists urls that redirects users to relevant sites.
  hostUrl array The array of URLs valid for embedding of Swedbank Pay Seamless Views. If not supplied, view-operation will not be available.
check︎︎︎︎︎ completeUrl string The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET request needs to be performed on the payment to inspect it further. See completeUrl for details.
  cancelUrl string The URL to redirect the payer to if the payment is cancelled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both.
  callbackUrl string The URL that Swedbank Pay will perform an HTTP POST 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 URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.
check︎︎︎︎︎ payeeInfo object The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
check︎︎︎︎︎ payeeId string This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
  payeeName string The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
  productCategory string(50) 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 different subsite values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown subsite value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of A-Za-z0-9.
  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 generateRecurrenceToken, RecurrenceToken, generatePaymentToken or paymentToken is true.

Financing Consumer Response

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
74
75
76
77
78
79



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

{
    "payment": {
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "state": "Ready",
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SE",
        "amount": 0,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "prices": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "transactions": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions"
        },
        "authorizations": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations"
        },
        "captures": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures"
        },
        "reversals": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals"
        },
        "cancellations": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations"
        },
        "payeeInfo": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo"
        },
        "payers": {
           "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "urls": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "settings": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings"
        },
        "approvedLegalAddress": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress"
        },
        "maskedApprovedLegalAddress": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/maskedapprovedlegaladdress"
        }
    },
    "approvedLegalAddress": {
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress"
    },
    "operations": [
        {
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
            "rel": "create-capture",
            "method": "POST"
        },
        {
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations",
            "rel": "create-cancel",
            "method": "POST"
        },
        {
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress",
            "rel": "create-approved-legal-address",
            "method": "POST"
        }
    ]
}
Field Type Description
payment object The payment object contains information about the specific payment.
id 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.
number integer The payment number, useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, where id should be used instead.
created string The ISO-8601 date of when the payment was created.
updated string The ISO-8601 date of when the payment was updated.
state string Ready, Pending, Failed or Aborted. Indicates the state of the payment, not the state of any transactions performed on the payment. To find the state of the payment’s transactions (such as a successful authorization), see the transactions resource or the different specialized type-specific resources such as authorizations or sales.
prices object The prices resource lists the prices related to a specific payment.
id string The relative URL and unique identifier of the prices resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
description string(40) A 40 character length textual description of the purchase.
userAgent string The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser.
language string sv-SE, nb-NO or en-US.
urls string The URL to the urls resource where all URLs related to the payment can be retrieved.
payeeInfo object The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
payers string The URL to the payer resource where the information about the payer can be retrieved.
operations array The array of operations that are possible to perform on the payment in its current state.
method string The HTTP method to use when performing the operation.
href string The target URL to perform the operation against.
rel string The name of the relation the operation has to the current resource.

Step 2: Get approvedLegalAddress Confirmation

Retrieve the payer’s legal address, which is needed to do the next step.

Request



1
2
3
4
5
6
7
8
9
10
11



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

{
    "addressee": {
        "socialSecurityNumber": "194810205957",
        "zipCode": "55560"
    }
}

Response



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



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

{
    "payment": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "approvedLegalAddress": {
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress",
        "addressee": "Leo 6",
        "streetAddress": "Gata 535",
        "zipCode": "55560",
        "city": "Vaxholm",
        "countryCode": "SE"
    }
}

Step 3: Complete The Payment

Add the legal address in your complete request.

Complete 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



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

{
    "transaction": {
        "activity": "FinancingConsumer"
    },
    "consumer": {
        "socialSecurityNumber": "194810205957",
        "customerNumber": "123456",
        "email": "someExample@payex.com",
        "msisdn": "+46765432198",
        "ip": "127.0.0.1"
    },
    "legalAddress": {
        "addressee": "Leo 6",
        "streetAddress": "Gata 535",
        "zipCode": "55560",
        "city": "Vaxholm",
        "countryCode": "SE"
    }
}

Complete Response

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



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

{
    "payment": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "shippingAddress": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/shippingaddress"
        },
        "legalAddress": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/legaladdress"
        },
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/23fc8ea7-57b8-44bb-8313-08d7ca2e1a26",
        "transaction": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/23fc8ea7-57b8-44bb-8313-08d7ca2e1a26",
            "created": "2020-03-17T09:46:10.3506297Z",
            "updated": "2020-03-17T09:46:12.2512221Z",
            "type": "Authorization",
            "state": "Completed",
            "number": 71100537930,
            "amount": 4201,
            "vatAmount": 0,
            "description": "Books & Ink",
            "payeeReference": "1584438350",
            "isOperational": false,
            "operations": []
        }
    }
}

The sequence diagram below shows a high level description of the invoice process, including the four requests you have to send to Swedbank Pay to create an authorized transaction.

Invoice Flow 

sequenceDiagram
    Payer->>Merchant: Start purchase (collect SSN and postal number)
    activate Merchant
    note left of Merchant: First API request
    Merchant->>-Swedbank Pay: POST <Invoice Payments> (operation=FinancingConsumer)
    activate Swedbank Pay
    Swedbank Pay-->>-Merchant: payment resource
    activate Merchant
    note left of Merchant: Second API request
    Merchant->>-Swedbank Pay: POST <approvedLegalAddress> (SNN and postal number)
    activate Swedbank Pay
    Swedbank Pay->>Swedbank Pay: Update payment with payer's delivery address
    Swedbank Pay-->>-Merchant: Approved legaladdress information
    activate Merchant
    Merchant-->>-Payer: Display all details and final price
    activate Payer
    Payer->>Payer: Input email and mobile number
    Payer->>-Merchant: Confirm purchase
    activate Merchant

    note left of Merchant: Third API request
    Merchant->>-Swedbank Pay: POST <invoice authorizations> (Transaction Activity=FinancingConsumer)
    activate Swedbank Pay
    Swedbank Pay-->>-Merchant: Transaction result
    activate Merchant
    note left of Merchant: Fourth API request
    Merchant->>-Swedbank Pay: GET <invoice payments>
    activate Swedbank Pay
    Swedbank Pay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Payer: Display result

Options After Posting A Purchase Payment

Head over to Capture to complete the Invoice Direct integration.