Card – MOTO

MOTO

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

Card-based home orders, also known as MOTO (Mail Order / Telephone Order) is a purchase where you, as a merchant, enter the payer’s card details in order to make a payment. The payer provides the card details to the sales representative by telephone or in writing. The sales representative will then enter the details into the payment interface.

Common use cases are travel or hotel bookings, where the payer calls the sales representative to make a booking. This feature is only supported with the Purchase operation. See the abbreviated example below on how to implement MOTO by setting the generateMotoPayment to true.

MOTO Request

Request

1
2
3
4

POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
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
24
25
26
27
28
29
30
31

{
    "payment": {
        "generateMotoPayment": true,
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "NOK",
        "prices": [{
                "type": "CreditCard",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Moto",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "hostUrls": ["https://example.com"],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        }
    }
}

MOTO Response

To authorize the payment, find the operation with rel equal to redirect-authorization in the response, and redirect the merchant employee to the provided href to fill out the payer’s card details. You will find an abbreviated example of the response provided below.

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

{
  "payment": {
        "id": "/psp/creditcard/payments/a205c77e-2f0a-4564-3e60-08d8d3ed4699",
        "number": 40106480687,
        "created": "2021-02-24T12:51:51.0932275Z",
        "updated": "2021-02-24T12:51:51.2935307Z",
        "instrument": "CreditCard",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Ready",
        "currency": "NOK",
        "prices": {
            "id": "/psp/creditcard/payments/a205c77e-2f0a-4564-3e60-08d8d3ed4699/prices"
        },
        "amount": 0,
        "description": "Test Moto",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "id": "/psp/creditcard/payments/a205c77e-2f0a-4564-3e60-08d8d3ed4699/urls"
        },
        "payeeInfo": {
            "id": "id": "/psp/creditcard/payments/a205c77e-2f0a-4564-3e60-08d8d3ed4699/payeeInfo"
        },
        "metadata": {
            "id": "/psp/creditcard/payments/a205c77e-2f0a-4564-3e60-08d8d3ed4699/metadata"
        }
    },
       "operations": [
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/a205c77e-2f0a-4564-3e60-08d8d3ed4699",
            "rel": "update-payment-abort",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/creditcardv3/core/js/px.creditcard.client.js?token=a0a2da77fe9582387d384b77cc0d7d04fb861d10ba13fc46d3abca00f4a1368f&operation=authorize",
            "rel": "view-authorization",
            "contentType": "application/javascript"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/creditcardv3/payments/authorize/a0a2da77fe9582387d384b77cc0d7d04fb861d10ba13fc46d3abca00f4a1368f",
            "rel": "redirect-authorization",
            "contentType": "text/html"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/creditcardv3/core/js/px.creditcard.client.js?token=a0a2da77fe9582387d384b77cc0d7d04fb861d10ba13fc46d3abca00f4a1368f",
            "rel": "view-payment",
            "contentType": "application/javascript"
        }
    ]
}

Capture

The capture transaction is where you ensure that the funds are charged 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.

Create Capture Transaction

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

Capture Request

Request

1
2
3
4

POST /psp/creditcard/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,
        "description": "Test Capture",
        "payeeReference": "ABC123"
    }
}

transaction object

The object representation of the generic transaction resource, containing information about the current transaction.

amount integer

Amount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.

vatAmount integer

Amount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.

description string

A textual description of the capture transaction.

payeeReference string(30)

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 to the acquirer and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. **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

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

{
    "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": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Capture",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1500,
            "vatAmount": 250,
            "description": "Test Capture",
            "payeeReference": "ABC123",
            "isOperational": false,
            "operations": []
        }
    }
}

payment string

The relative URL of the payment this capture transaction belongs to.

capture object

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

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

Amount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.

vatAmount integer

If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.

description string

A human readable description of maximum 40 characters of the transaction.

payeeReference string(30)

failedReason string

The human readable explanation of why the payment failed.

isOperational boolean

true if the transaction is operational; otherwise false.

operations array

The array of operations that are possible to perform on the payment order in its current state.

List Capture Transactions

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

Request

1
2
3
4

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

The capture resource contains information about the capture transaction made against a creditcard 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": []
            }
        }]
    }
}

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.

reversals object

The current captures resource.

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.

reversalList array

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 textual description of the purchase. Maximum length is 40 characters.

payeeReference string(30)

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 to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(50). 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 [Credit card captures]
  activate SwedbankPay
  SwedbankPay-->>-Merchant: transaction resource