Online Payments – Token Handling

GET Single Payer Token

A GET request used when you need to retrieve a single token.

GET Single Payer Token Request

GET Single Payer Token Response

1
2
3

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

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

{
   "token": {
     "id" : <resourceId>,
     "payerReference" : "{payerReference}",
     "token": <Guid>,
     "tokenType": "Unscheduled",
     "instrument": "Trustly",
     "instrumentDisplayName" : "Custom value, or default depending on instrument",
     "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d",
     "state": "Active",
     "instrumentParameters": {
       .....
    }
  },
  "operations": [
    {
       "method": "GET",
       "href": "https://api.<environment>.swedbankpay.com/online/payer/payees/<guid>/tokens/<token>-<tokenType>",
       "rel": "get-token",
       "contentType": "application/json"
    },
    {
       "method": "PATCH",
       "href": "https://api.<environment>.swedbankpay.com/online/payer/payees/<guid>/tokens/<token>-<tokenType>/displaynames",
       "rel": "update-displayname",
       "contentType": "application/json"
     },
     {
        "method": "PATCH",
        "href": "https://api.<environment>.swedbankpay.com/online/payer/payees/<guid>/tokens/<token>-<tokenType>/archives",
        "rel": "archive-token",
        "contentType": "application/json"
     }
   ]
}

token object

The token object.

id string

The token ID.

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

token string

The token guid.

tokenType string

The available token types: Payment, Recurrence, TransactionOnFile or Unscheduled.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrumentDisplayName string

The displayed payment method name. Either a custom value or the default instrument name.

correlationsId string

A unique ID (guid) used in the system. Makes it easier to trace cards, accounts etc. which is connected to the token.

state string

The state of the token. Can either be Active or Archived.

</details>

archivedBy string

Present if the token state is Archived and indicates who archived it. Can either be PAYEE SWEDBANK_PAY or TOKEN_ISSUER.

</details>

archiveReason string

The state of the token. Can either be active or archived.

instrumentParameters object

A list of additional information connected to the token. The content may differ depending on the payment method. See tables connected to payment method specific nodes below.

</details>

operations array

### Instrument Parameters - CreditCard

Instrument Parameters - CreditCard

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { "token": { "instrumentParameters": { "cardBrand": "Visa", "expiryDate" : "12/2028", "expiryPan": "12/2028", "issuerName": "Name of issuer if present", "lastFourPan": "0004" "bin": "492500", "cardHolderType" : "Consumer", "cardType" : "Debit", "countryCode" : "752", "lastFourDPan" : "1234", "expiryDPan" : "02/2029" }, } } ````

token object

The token object.

instrumentParameters object

A list of additional information connected to the token.

cardBrand string

Visa, MC, etc. The brand of the card.

expiryDate string

The month and year when the card expires.

expiryPan string

issuerName string

The name of the card issuer.

lastFourPan string

The last four digits og the card's PAN.

bin string

The first six digits of the maskedPan.

cardHolderType string

Indicates if the card holder is a consumer or corporate customer.

cardType string

Indicates if the card is a debit or credit card.

countryCode string

The card's country code.

lastFourDPan string

The last four digits of the card's DPAN (network token).

expiryDPan string

Expiry date of the card's DPAN (network token).

### Instrument Parameters - Trustly

Instrument Parameters - Trustly <button aria-describedby="tooltipCopy" class="code-view-copy tooltip" aria-label="Copy json to clipboard" value='{ "token": { "instrumentParameters": { "AccountId": "156", -> ('DisplayName' default) }, } }' onclick='javascript:navigator.clipboard.writeText(this.value)'>

</button> ````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { "token": { "instrumentParameters": { "AccountId": "156", -> ('DisplayName' default) }, } } ````

token object

The token object.

instrumentParameters object

A list of additional information connected to the token.

AccountId string

Account identifier.

## GET All Payer Tokens A GET request used to retrieve all payer tokens linked to a payee using the payer's `payerReference`. ## GET All Payer Tokens Request

GET All Payer Tokens Request

## Get All Payer Tokens Response

GET All Payer Tokens Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { { "tokens": { "id": "/online/payer/payees//payers/{payerReference}/tokens", "payerReference": "{payerReference}", "migratedFromConsumerProfile": true "tokenlist": [ { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "TransactionOnFile", "instrument": "Trustly", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "TOKEN_ISSUER", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] }, { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Unscheduled", "instrument": "CreditCard|Trustly|CarPay", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Active", "instrumentParameters": { ..... } "operations": [...] }, { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Payment", "instrument": "CreditCard", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "PAYEE", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] } ] }, "operations": [ { "method": "GET", "href": "https://api..swedbankpay.com/online/payer/payees//payers/{payerReference}/tokens", "rel": "get-payer-tokens", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//payers/{payerReference}/archives", "rel": "archive-payer-tokens", "contentType": "application/json" } ] } } ````

tokens object

The token object.

id string

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

migratedFromConsumerProfile bool

Indicates if the token was migrated from Swedbank Pay's old consumer profile solution. Set to true or false.

tokenlist array

The array of token objects

id string

The token ID.

id string

The token ID.

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

token string

The token guid.

tokenType string

The available token types: Payment, Recurrence, TransactionOnFile or Unscheduled.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrumentDisplayName string

The displayed payment method name. Either a custom value or the default instrument name.

correlationsId string

A unique ID (guid) used in the system. Makes it easier to trace cards, accounts etc. which is connected to the token.

state string

The state of the token. Can either be Active or Archived.

</details>

archivedBy string

Present if the token state is Archived and indicates who archived it. Can either be PAYEE SWEDBANK_PAY or TOKEN_ISSUER.

</details>

archiveReason string

The state of the token. Can either be active or archived.

instrumentParameters object

A list of additional information connected to the token. The content may differ depending on the payment method. See tables connected to payment method specific nodes under GET single payer token.

</details>

operations array

## GET Archived Payer Tokens A GET request used to retrieve all archived tokens by a payee using the payer's `payerReference`. ## GET Archived Payer Tokens Request

GET Archived Tokens Request

## GET Archived Payer Tokens Response

GET Archived Payer Tokens Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { { "tokens": { "id": "/online/payer/payees//payers/{payerReference}/tokens", "payerReference": "{payerReference}", "migratedFromConsumerProfile": false "tokenlist": [ { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Payment", "instrument": "CreditCard", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "PAYEE", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] }, { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Unscheduled", "instrument": "Trustly", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "SWEDBANK_PAY", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] }, { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Recurrence", "instrument": "CreditCard", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "TOKEN_ISSUER", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] } ] }, "operations": [ { "method": "GET", "href": "https://api..swedbankpay.com/online/payer/payees//payers/{payerReference}/tokens", "rel": "get-payer-tokens", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//payers/{payerReference}/archives", "rel": "archive-payer-tokens", "contentType": "application/json" } ] } } ````

tokens object

The token object.

id string

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

migratedFromConsumerProfile bool

Indicates if the token was migrated from Swedbank Pay's old consumer profile solution. Set to true or false.

tokenlist array

The array of token objects

id string

The token ID.

id string

The token ID.

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

token string

The token guid.

tokenType string

The available token types: Payment, Recurrence, TransactionOnFile or Unscheduled.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrumentDisplayName string

The displayed payment method name. Either a custom value or the default instrument name.

correlationsId string

A unique ID (guid) used in the system. Makes it easier to trace cards, accounts etc. which is connected to the token.

state string

The state of the token. Can either be Active or Archived.

</details>

archivedBy string

Present if the token state is Archived and indicates who archived it. Can either be PAYEE SWEDBANK_PAY or TOKEN_ISSUER.

</details>

archiveReason string

The state of the token. Can either be active or archived.

instrumentParameters object

A list of additional information connected to the token. The content may differ depending on the payment method. See tables connected to payment method specific nodes under GET single payer token.

</details>

operations array

## PATCH Update Display Name A PATCH request used to update a payer token's display name. ## PATCH Update Display Name Request

PATCH Update Display Name Request

````jsonc { "displayName" : "xxxxxxxxxxxxxxxxxxxxxxx" } ```` ## PATCH Update Display Name Response

PATCH Update Display Name Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { "token": { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Unscheduled", "instrument": "Trustly", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Active", "instrumentParameters": { ..... } }, "operations": [ { "method": "GET", "href": "https://api..swedbankpay.com/online/payer/payees//tokens/-", "rel": "get-token", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//tokens/-/displaynames", "rel": "update-displayname", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//tokens/-/archives", "rel": "archive-token", "contentType": "application/json" } ] } ````

token object

The token object.

id string

The token ID.

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

token string

The token guid.

tokenType string

The available token types: Payment, Recurrence, TransactionOnFile or Unscheduled.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrumentDisplayName string

The displayed payment method name. Either a custom value or the default instrument name.

correlationsId string

A unique ID (guid) used in the system. Makes it easier to trace cards, accounts etc. which is connected to the token.

state string

The state of the token. Can either be Active or Archived.

</details>

archivedBy string

Present if the token state is Archived and indicates who archived it. Can either be PAYEE SWEDBANK_PAY or TOKEN_ISSUER.

</details>

archiveReason string

The state of the token. Can either be active or archived.

instrumentParameters object

A list of additional information connected to the token. The content may differ depending on the payment method. See tables connected to payment method specific nodes under GET single payer token.

</details>

operations array

## PATCH Archive Single Payer Token A PATCH request used to archive a single, specific payer token. ## PATCH Archive Single Payer Token Request

PATCH Archive Single Payer Token Request

````jsonc { "reason" : "description", "updatedBy": "PAYEE" } ```` ## PATCH Archive Single Payer Token Response

PATCH Archive Single Payer Token Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { "token": { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Unscheduled", "instrument": "Trustly", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "PAYEE", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } }, "operations": [ { "method": "GET", "href": "https://api..swedbankpay.com/online/payer/payees//tokens/-", "rel": "get-token", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//tokens/-/displaynames", "rel": "update-displayname", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//tokens/-/archives", "rel": "archive-token", "contentType": "application/json" } ] } ````

token object

The token object.

id string

The token ID.

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

token string

The token guid.

tokenType string

The available token types: Payment, Recurrence, TransactionOnFile or Unscheduled.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrumentDisplayName string

The displayed payment method name. Either a custom value or the default instrument name.

correlationsId string

A unique ID (guid) used in the system. Makes it easier to trace cards, accounts etc. which is connected to the token.

state string

The state of the token. Can either be Active or Archived.

</details>

archivedBy string

Present if the token state is Archived and indicates who archived it. Can either be PAYEE SWEDBANK_PAY or TOKEN_ISSUER.

</details>

archiveReason string

The state of the token. Can either be active or archived.

instrumentParameters object

A list of additional information connected to the token. The content may differ depending on the payment method. See tables connected to payment method specific nodes under GET single payer token.

</details>

operations array

## PATCH Archive All Payer Tokens A PATCH request used to archive all tokens linked to a specific `payerReference`. ## PATCH Archive All Payer Tokens Request

PATCH Archive All Payer Tokens Request

````jsonc { "reason" : "description", "updatedBy": "SWEDBANK_PAY" } ```` ## PATCH Archive All Payer Tokens Response

PATCH Archive All Payer Tokens Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { { "tokens": { "id": "/online/payer/payees//payers/{payerReference}/tokens", "payerReference": "{payerReference}", "migratedFromConsumerProfile": false "tokenlist": [ { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Payment", "instrument": "CreditCard", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "PAYEE", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] }, { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Unscheduled", "instrument": "Trustly", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "SWEDBANK_PAY", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] }, { "id" : , "payerReference" : "{payerReference}", "token": , "tokenType": "Recurrence", "instrument": "CreditCard", "instrumentDisplayName" : "Custom value, or default depending on instrument", "correlationsId": "e2f06785-805d-4605-bf40-426a725d313d", "state": "Archived", "archivedBy": "TOKEN_ISSUER", "archiveReason": "Comment with reason for archive", "instrumentParameters": { ..... } "operations": [...] } ] }, "operations": [ { "method": "GET", "href": "https://api..swedbankpay.com/online/payer/payees//payers/{payerReference}/tokens", "rel": "get-payer-tokens", "contentType": "application/json" }, { "method": "PATCH", "href": "https://api..swedbankpay.com/online/payer/payees//payers/{payerReference}/archives", "rel": "archive-payer-tokens", "contentType": "application/json" } ] } } ````

tokens object

The token object.

id string

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

migratedFromConsumerProfile bool

Indicates if the token was migrated from Swedbank Pay's old consumer profile solution. Set to true or false.

tokenlist array

The array of token objects

id string

The token ID.

id string

The token ID.

payerReference string

The <a href=A reference used to recognize the payer in the absence of SSN and/or a secure login.

token string

The token guid.

tokenType string

The available token types: Payment, Recurrence, TransactionOnFile or Unscheduled.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrument string

Available payment methods which support tokens: CreditCard or Trustly.

instrumentDisplayName string

The displayed payment method name. Either a custom value or the default instrument name.

correlationsId string

A unique ID (guid) used in the system. Makes it easier to trace cards, accounts etc. which is connected to the token.

state string

The state of the token. Can either be Active or Archived.

</details>

archivedBy string

Present if the token state is Archived and indicates who archived it. Can either be PAYEE SWEDBANK_PAY or TOKEN_ISSUER.

</details>

archiveReason string

The state of the token. Can either be active or archived.

instrumentParameters object

A list of additional information connected to the token. The content may differ depending on the payment method. See tables connected to payment method specific nodes under GET single payer token.

</details>

operations array

## Delete Unscheduled, Recurrence Or Payment Tokens Payers should be able to delete tokens connected to them. How to do this is described in the example below. Note that the different token types have different responses. The `state` field must have the state `Deleted` when deleting the token. No other states are supported. ## Delete recurrenceToken Request

Request

````http PATCH /psp/paymentorders/recurrenceTokens/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1 Host: api.externalintegration.payex.com Authorization: Bearer Content-Type: application/json;version=3.x/2.0 ```` ````jsonc { "state": "Deleted", "comment": "Comment on why the deletion is happening" } ```` ## Delete recurrenceToken Response

Response

Request

````http PATCH /psp/paymentorders/unscheduledTokens/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1 Host: api.externalintegration.payex.com Authorization: Bearer Content-Type: application/json;version=3.x/2.0 ```` ````jsonc { "state": "Deleted", "comment": "Comment on why the deletion is happening" } ```` ## Delete unscheduledToken Response The example shows a token connected to a card. The parameters and display name will vary depending on the payment method.

Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { "token": "5a17c24e-d459-4567-bbad-aa0f17a76119", "instrument": "CreditCard", "instrumentDisplayName": "123456xxxxxx1111" "correlationId": "e2f06785-805d-4605-bf40-426a725d313d", "instrumentParameters": { "cardBrand": "Visa", "expiryDate": "MM/YYYY" } } ```` ## Delete paymentToken Request

Request

````http PATCH /psp/paymentorders/paymentTokens/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1 Host: api.externalintegration.payex.com Authorization: Bearer Content-Type: application/json;version=3.x/2.0 ```` ````jsonc { "state": "Deleted", "comment": "Comment on why the deletion is happening" } ```` ## Delete paymentToken Response The example shows a token connected to a card. The parameters and display name will vary depending on the payment method.

Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.x/2.0 api-supported-versions: 3.x/2.0 ```` ````jsonc { "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119", "instrument": "CreditCard", "instrumentDisplayName": "123456xxxxxx1111" "correlationId": "e2f06785-805d-4605-bf40-426a725d313d", "instrumentParameters": { "cardBrand": "Visa", "expiryDate": "MM/YYYY" } } ```` ## Delete payerOwnedToken Request

Request

````http PATCH /psp/paymentorders/payerownedtokens/ HTTP/1.1 Host: api.externalintegration.payex.com Authorization: Bearer Content-Type: application/json;version=3.1/2.0 ```` ````jsonc { "state": "Deleted", "comment": "Comment stating why this is being deleted" } ```` ## Delete payerownedToken Response

Response

````http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8; version=3.1 api-supported-versions: 3.x/2.0 ```` ````jsonc { "payerOwnedTokens": { "id": "/psp/paymentorders/payerownedtokens/{payerReference}", "payerReference": "{payerReference}", "tokens": [ { "tokenType": "Payment", "token": "{paymentToken}", "instrument": "Invoice-payexfinancingno", "instrumentDisplayName": "260267*****", "correlationId": "e2f06785-805d-4605-bf40-426a725d313d", "instrumentParameters": { "email": "hei@hei.no", "msisdn": "+4798765432", "zipCode": "1642" } }, { "tokenType": "Payment", "token": "{paymentToken}", "instrument": "CreditCard", "instrumentDisplayName": "492500******0004", "correlationId": "e2f06785-805d-4605-bf40-426a725d313d", "instrumentParameters": { "expiryDate": "12/2020", "cardBrand": "Visa" } } ] } } ````