Payment Services

POST /paylink

Requires authentication with server access token.

Create a new paylink.

The items parameter should be a JSON array of objects. Each object should contain at least the following required fields:

  • description
  • price (total price including VAT, in cents - 10000 is 100,-)
  • vat (fraction × 10000, for instance 25% would be 2500)

These fields may be omitted if the optional field productId is provided. This will make the item inherit description, price, vat from the product. Example: if only description and productId is provided, the item will not inherit description from the product.

Additionally, you may use the following optional fields:

  • clientItemReference
  • productId
  • ogpUri
  • currency
  • quantity
  • name

See the paylink item object specification for further details on these fields.

The paymentOptions parameter defines allowed payment methods for Paylink. It can be provided in two formats - as:

See also

Help us improve

Did you spot an error? Or maybe you just have a suggestion for how we can improve? Leave us a comment.

Request

POST /api/2/paylink

title

required

The PayLink title. Displayed to the user on the payment page, and shown on the New Credit Card page at Payex.

items

required

The items to be sold. A list of PayLink Item objects.

clientReference

optional

Your reference. Useful for tracking and processing the Order generated by this PayLink.

purchaseFlow

optional

Defaults to DIRECT, which will process the payment straight away. Can also be AUTHORIZE, where the payment is on hold and must later be captured.

paymentOptions

optional

The allowed payment methods for this PayLink. Payment options can be provided in two formats: as an integer bit mask or as a JSON array of objects (this format allows providing data for external payment methods). Defaults to integer bitmask, 2 (bank card with PayEx).

expires

optional

The date when the PayLink expires. A unix timestamp. Defaults to 24 hours from creation.

redirectUri

optional

Redirect the user to this URL after payment is complete.

cancelUri

optional

Redirect the user to this URL if login or payment is cancelled.

buyerUserId

optional

If set, only this user has access to the PayLink.

Example request

curl
Minimal example
curl https://login.schibsted.com/api/2/paylink \
   -X POST \
   -H "Authorization: Bearer [access token]" \
   -d "title=Freebies for all" \
   -d "items=[{\"name\":\"Episode\",\"description\":\"Star Wars IV\",\"price\":9900,\"vat\":2500},{\"description\":\"Star Wars V\",\"price\":9900,\"vat\":2500},{\"description\":\"Star Wars VI\",\"price\":9900,\"vat\":2500}]"
With all parameters
curl https://login.schibsted.com/api/2/paylink \
   -X POST \
   -H "Authorization: Bearer [access token]" \
   -d "title=Freebies for all" \
   -d "items=[{\"name\":\"Episode\",\"description\":\"Star Wars IV\",\"price\":9900,\"vat\":2500},{\"description\":\"Star Wars V\",\"price\":9900,\"vat\":2500},{\"description\":\"Star Wars VI\",\"price\":9900,\"vat\":2500}]" \
   -d "clientReference=ref" \
   -d "purchaseFlow=AUTHORIZE" \
   -d "paymentOptions=[{\"type\":\"PAYEX_CC\"},{\"type\":\"KLARNA\"},{\"type\":\"PROVIDED\",\"subType\":\"Vouchers\",\"url\":\"https://external-url.com\",\"name\":\"Vouchers\",\"imageUrl\":\"https://external-url.com/vouchers-icon.jpeg\",\"description\":\"Vouchers allow you to pay with voucher code.\"}]" \
   -d "expires=2016-06-01" \
   -d "redirectUri=http://somewhere.com/else/" \
   -d "cancelUri=http://somewhere.com" \
   -d "buyerUserId=632784"

Response

This endpoint supports the JSON and JSON-P response formats.

Success: 200 OK

Returns the newly created paylink object

paylinkId

integer (as string)

Paylink ID Although the typical format is as an integer we recommend using 36 character length string so the client ensures to be compatible for future possible changes

clientId

string

ID of the client that gets paid (seller client ID). Defaults to the authenticated client

code

string

Paylink code

shortUrl

string

Paylink short URL

sellerUserId

integer (as string)

ID of the user that gets paid. If set, will connect this paylink to the user as seller and receiver of payment

buyerUserId

integer (as string)

ID of the user that can pay. If set, will lock this paylink to this user

clientReference

string

Client's custom reference

title

string

The title shown to the user in the payment flow. Will also be shown on Payex' "new credit card" page

purchaseFlow

Purchase flow

Defaults to DIRECT (1 phase payment, no authorization)

paymentOptions

Payment options

Payment options can be returned in two formats (depending on format provided in Paylink create request): as a bit mask or as a JSON array of objects (this format allows providing data for external payment methods).

redirectUri

string

The URL the user is redirected to after payment. Can also be overridden by the client in the payment flow

cancelUri

string

The URL the user is redirected to if the user aborts the payment or login flow. Can also be overridden by the client in payment flow

expires

string

When the paylink will expire. A unix timestamp or a datetime. Defaults to 24 hours from creation

status

Paylink status

updated

datetime

When the paylink was last updated

updatedBy

string

ID of the person/client who last updated the paylink

created

datetime

When the paylink was created

createdBy

string

ID of the person/client who created the paylink

items

collection of Paylink items, as an object with paylinkItemId for property names, and Paylink items for values

Purchase flow

An enum, with the following possible values:

"DIRECT"

Direct purchase flow

"AUTHORIZE"

Authorize/Capture purchase flow

An enum, with the following possible values:

"-1"

Deleted

"0"

Not available

"1"

Available

"2"

Used

Payment options

Payment options can be provided as a bit mask.

Bitmask format is the default format. If payment options are not provided, the default value is 2 (bank card with PayEx).

Examples: 2 means credit card, 4 means SMS, while 6 means both credit card and SMS.

An enum, with the following possible values:

"1"

Masterpass

"2"

Credit card

"4"

SMS

"8"

PayEx Invoice

"16"

Voucher

"32"

Klarna Invoice

"64"

Klarna Mobile

"128"

Wallet

Payment options - array format

This format allows providing data for provided payment methods. See the provided payment methods specification for further details.

type

Payment option type

Required. Example: PAYEX_CC, STREX, PROVIDED

subType

string

Required when type is PROVIDED. A subtype used to distinguish between various types of provided payment methods.

url

string

Required when type is PROVIDED. User is redirected to this URL after choosing payment with provided payment method.

name

string

Required when type is PROVIDED. Provided payment method name.

imageUrl

string

Required when type is PROVIDED. Provided payment method image url.

description

string

Required when type is PROVIDED. Provided payment method description.

paylinkItemId

integer (as string)

paylinkId

integer (as string)

clientId

string

ID of the client that gets paid (seller client_id)

productId

integer (as string)

ID of an existing product in Schibsted account

clientItemReference

string

Client's custom reference for this item

type

Paylink item type

name

string

Control receipt item name, optional, uses Paylink title if not set

description

string

Control cart item description

ogpUri

string

Open Graph Protocol enabled URI representing the product being purchased

price

integer (as string)

Price (including VAT amount), in "cents". 0 or a positive integer.

vat

integer (as string)

VAT, fraction × 10000. For instance, 25% would be 2500

currency

string

Currency. Ex. NOK. Defaults to the to platform currency

quantity

integer (as string)

The quantity of this item. Defaults to 1, the total cost is price multiplied by quantity

updated

string

When the paylink was last changed

updatedBy

string

ID of the user/client who last updated the paylink item

created

string

When the paylink item was created

createdBy

string

ID of the user/client who created the paylink item

Failure cases

Some HTTP response codes are used for multiple error situations. There is no consistent way to tell these apart, but the error object will contain a textual explanation of the reason for the error. For explanation on OAuth related failures and errors see OAuth authentication failures.

  • 400 Bad Request Missing one or more required parameters
  • 400 Bad Request Paylink items is not a list of items
  • 400 Bad Request Validation error(s)
  • 401 Unauthorized You don't have administration rights for this client.
  • 401 Unauthorized Your client doesn't have administration rights for this client.
  • 403 Forbidden Client is not authorized to access this API endpoint. Contact Schibsted account to request access.
  • 403 Forbidden Requesting IP is not whitelisted
  • 403 Forbidden Access token rejected
  • 404 Not Found Unknown client ID
  • 404 Not Found Client ID mismatch. The client making the request is no the owner of this resource, and does not have administrative privileges for it.
  • 404 Not Found Paylink not found
  • 420 Request Ratelimit exceeded

Sample response

JSON
{
  "sellerUserId": null,
  "updatedBy": "52f8e3d9efd04bb749000000",
  "status": "1",
  "clientReference": "Order number #3242",
  "items": {
    "6199": {
      "updatedBy": null,
      "vat": "1917",
      "clientId": "[Your client ID]",
      "currency": "NOK",
      "paylinkId": "4638",
      "createdBy": "[ID of admin user, or client]",
      "quantity": "1",
      "ogpUri": null,
      "productId": null,
      "clientItemReference": null,
      "created": "2014-08-06 08:16:36",
      "updated": "2014-08-06 08:16:36",
      "type": "0",
      "paylinkItemId": "6199",
      "price": "7983",
      "description": "Star Wars IV"
    }
  },
  "clientId": "[Your client ID]",
  "paylinkId": "4638",
  "cancelUri": "http://localhost:8000/cancel",
  "createdBy": "[ID of admin user, or client]",
  "expires": "2014-08-07 08:16:36",
  "buyerUserId": null,
  "title": "Star Wars Movies",
  "code": "4638",
  "created": "2014-08-06 08:16:36",
  "updated": "2014-08-06 08:16:36",
  "shortUrl": "https://identity-pre.schibsted.com/auth/start?paylink\u003d4638",
  "paymentOptions": "2",
  "purchaseFlow": "DIRECT",
  "redirectUri": "http://localhost:8000/callback"
}
JSON-P
callback({
  "sellerUserId": null,
  "updatedBy": "52f8e3d9efd04bb749000000",
  "status": "1",
  "clientReference": "Order number #3242",
  "items": {
    "6199": {
      "updatedBy": null,
      "vat": "1917",
      "clientId": "[Your client ID]",
      "currency": "NOK",
      "paylinkId": "4638",
      "createdBy": "[ID of admin user, or client]",
      "quantity": "1",
      "ogpUri": null,
      "productId": null,
      "clientItemReference": null,
      "created": "2014-08-06 08:16:36",
      "updated": "2014-08-06 08:16:36",
      "type": "0",
      "paylinkItemId": "6199",
      "price": "7983",
      "description": "Star Wars IV"
    }
  },
  "clientId": "[Your client ID]",
  "paylinkId": "4638",
  "cancelUri": "http://localhost:8000/cancel",
  "createdBy": "[ID of admin user, or client]",
  "expires": "2014-08-07 08:16:36",
  "buyerUserId": null,
  "title": "Star Wars Movies",
  "code": "4638",
  "created": "2014-08-06 08:16:36",
  "updated": "2014-08-06 08:16:36",
  "shortUrl": "https://identity-pre.schibsted.com/auth/start?paylink\u003d4638",
  "paymentOptions": "2",
  "purchaseFlow": "DIRECT",
  "redirectUri": "http://localhost:8000/callback"
});

Comments/feedback

Do you have questions, or just want to contribute some newly gained insight? Want to share an example? Please leave a comment. Our team reads and responds to every question. Additionally, your experience can help others using Schibsted account, and it can help us continuously improve our documentation.