Checkout v2

Verify

schedule 4 min read

Validating the payer’s payment details.

Edit "Verify" on GitHub

The Verify operation lets you post verification payments, which are used to confirm the validity of card information without reserving or charging any amount.

Introduction to Verify

This option is commonly used when initiating a subsequent recurring card payment flow - where you do not want to charge the payer right away.

info

Please note that all boolean credit card attributes involving the rejection of certain card types are optional and require enabling on the contract with Swedbank Pay.

Verification through Swedbank Pay Payments

  • When properly set up in your merchant/webshop site and the payer initiates a verification operation, you make a POST request towards Swedbank Pay with your Verify information. This will create a payment resource with a unique id. You either receive a Redirect URL to a hosted page or a JavaScript source in response.
  • You need to embed the script source on your site to create aSeamless View in an iframe; so that the payer can enter the card details in a secure Swedbank Pay hosted environment.
  • Swedbank Pay will handle 3-D Secure authentication when this is required.
  • Swedbank Pay will redirect the payer’s browser to - or display directly in the iframe - one of two specified URLs, depending on whether the payment session is followed through completely or cancelled beforehand. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.
  • When you detect that the payer reach your completeUrl, you need to do a GET request to receive the state of the transaction.
  • Finally you will make a GET request towards Swedbank Pay with the id of the payment received in the first step, which will return the payment result and a recurrenceToken that can be used for subsequent recurring server-to-server based payments.

Screenshots

You will redirect the payer to Swedbank Pay hosted pages to collect the credit card information.

screenshot of the swedish card verification page

API Requests

The API requests are displayed in the Verification flow below. The options you can choose from when creating a payment with key operation set to Value Verify are listed below.

Please note that not including paymentUrl in the request will generate a redirect-verification operation in the response, meant to be used in the Redirect flow. Adding paymentUrl input will generate the response meant for Seamless View, which does not include the redirect-verification. The request below is the Redirect option.

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
POST /psp/checkout/v2/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Verify",
        "currency": "NOK",
        "description": "Test Verification",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "generateRecurrenceToken": true,
        "generateUnscheduledToken": true,
        "urls": {
            "hostUrls": ["https://example.com", "https://example.net"],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.html"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        }
    },
    "creditCard": {
        "rejectCreditCards": false,
        "rejectDebitCards": false,
        "rejectConsumerCards": false,
        "rejectCorporateCards": false
    }
}

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "operation": "Verify",
        "state": "Ready",
        "currency": "NOK",
        "amount": 0,
        "description": "Test Verification",
        "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "nb-NO",
        "transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "verifications": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications" },
        "urls" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "payeeInfo" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
        "payers": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "settings": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
    },
    "operations": [
        {
            "href": "https://api.externalintegration.payex.com/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH",
            "contentType": "application/json"
        },
        {
            "href": "https://ecom.externalintegration.payex.com/payments/verification/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "redirect-verification",
            "method": "GET",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "view-verification",
            "contentType": "application/javascript"
        },
        {
            "method": "POST",
            "href": "https://ecom.externalintegration.payex.com/psp//confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications",
            "rel": "direct-verification",
            "contentType": "application/json"
        }
    ]
}

Verification flow

The sequence diagram below shows the two requests you have to send to Swedbank Pay to make a purchase. The links will take you directly to the API description for the specific request. The diagram also shows in high level, the sequence of the process of a complete purchase. When dealing with credit card payments, 3-D Secure authentication of the cardholder is an essential topic. There are three alternative outcome of a credit card payment:

  • 3-D Secure enabled - by default, 3-D Secure should be enabled, and Swedbank Pay will check if the card is enrolled with 3-D Secure. This depends on the issuer of the card. If the card is not enrolled with 3-D Secure, no authentication of the cardholder is done.
  • Card supports 3-D Secure - if the card is enrolled with 3-D Secure, Swedbank Pay will redirect the cardholder to the autentication mechanism that is decided by the issuing bank. Normally this will be done using BankID or Mobile BankID.
sequenceDiagram
    participant Payer
    participant Merchant
    participant SwedbankPay as Swedbank Pay
    participant IssuingBank

  activate Payer
  Payer->>+Merchant: start verification
  deactivate Payer
  Merchant->>+SwedbankPay: POST /psp//payments(operation=VERIFY)
  deactivate Merchant
  note left of Payer: First API request
  SwedbankPay-->+Merchant: payment resource
  deactivate SwedbankPay
  Merchant-->>+Payer: redirect to verification page
  deactivate Merchant
  Payer->>+SwedbankPay: access verification page
  deactivate Payer
  note left of Payer: redirect to SwedbankPay<br>(If Redirect scenario)
  SwedbankPay-->>+Payer: display purchase information
  deactivate SwedbankPay

  Payer->>Payer: input  information
  Payer->>+SwedbankPay: submit information
  deactivate Payer
  opt Card supports 3-D Secure
    SwedbankPay-->>Payer: redirect to IssuingBank
    deactivate SwedbankPay
    Payer->>IssuingBank: 3-D Secure authentication process
    Payer->>+SwedbankPay: access authentication page
    deactivate Payer
  end

  SwedbankPay-->>+Payer: redirect to merchant
  deactivate SwedbankPay
  note left of Payer: redirect back to merchant<br>(If Redirect scenario)

  Payer->>+Merchant: access merchant page
  Merchant->>+SwedbankPay: GET <payment.id>
  deactivate Merchant
  note left of Merchant: Second API request
  SwedbankPay-->>+Merchant: rel: redirect-authorization
  deactivate SwedbankPay
  Merchant-->>Payer: display purchase result
  deactivate Merchant

  opt Callback is set
    activate SwedbankPay
    SwedbankPay->>SwedbankPay: Payment is updated
    SwedbankPay->>Merchant: POST Payment Callback
    deactivate SwedbankPay
  end