Place order

/adyen/place_order

Target audience: Developers

Release version: 4.2.0

Place order¶

Introduction¶

This endpoint places an Adyen order. Depending on the result further actions might need to be taken. See here.

Attention

This API gives access to Adyen related endpoints. Since this section is quite specific it has it's own section of documentation. See here for more information.

URI¶

Environment	URI
Stage	https://payway-api.stage.adeprimo.se/external/api/v1/adyen/place_order
Production	https://backend.worldoftulo.com/external/api/v1/adyen/place_order

Requirements¶

Identity	Scope
Yes	`/external/adyen/w`

Curl example¶

Request¶

curl --request POST \
  --url https://payway-api.stage.adeprimo.se/external/api/v1/adyen/place_order \
  --header 'authorization: Bearer <token-with-identity>' \
  --header 'content-type: application/json' \
  --data '{
  "payment_method": {
    "type": "scheme",
    "issuer": "265"
  },
  "product_code": "package_code",
  "period_id": "5e4beac909c04c404a46c730",
  "return_url": "https://returnurl.com",
  "traffic_source": "facebook",
  "subscription_start_date": "2015-05-15",
  "discount_code": "code",
  "merchant_reference": "adeprimo-campaign-001",
  "origin": "https://example.purchase.org",
  "browser_info": {
    "browser_ip": "127.0.0.1",
    "browser_language": "sv-FI",
    "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36",
    "referer": "https://adeprimokuriren.se",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "color_depth": 24,
    "screen_height": 723,
    "screen_width": 1536,
    "time_zone_offset": 0,
    "java_enabled": true
  },
  "delivery_address": {
    "first_name": "Donald",
    "last_name": "Duck",
    "street": "Webfoot Walk",
    "street_number": "1313",
    "zip_code": "83145",
    "city": "Ankeborg",
    "country_code": "SE"
  }
}'

Parameters¶

Parameter	Description	Required	Format	Type
payment_method	Payment method received from state data in onSubmit event	Yes	Provided by Adyen widget	Object
product_code	The product code for a package/campaign.	Yes	Size range: 1..50 Allowed values: "/^[a-zA-Z-_0-9]+$/"	String
period_id	Id of the selected payment period	Yes	Size range ..24 Allowed values: "/^[a-f\d]{24}$/i"	String
return_url	URI for payment provider redirects, e.q. 3D Secure 1	Yes	Size range: ..1024 Allowed values: uri regex that is too long to show here. Must be absolute	String
origin	URI where purchase is performed (E.g. https://buy.example.org)	Yes	Size range: ..1024 Allowed values: uri regex that is too long to show here. Must be absolute	String
traffic_source	The source of the purchase. E.g. facebook, web. Traffic sources need to be setup in PAP	Optional	Size range: ..100	String
subscription_start_date	Date when the subscription will be activated	Optional	Allowed values: 2020-05-15	DateTime
discount_code	Discounted price. Code needs to be defined in PAP	Optional	Size range: 1..100	String
merchant_reference	An optional customer reference, can be a code or an url.	Optional	Size range: ..1024	String
browser_info	Information about client browser	Yes		Object
browser_ip	Client ip-address	Yes	e.q. "127.0.0.1"	String
browser_language	Client language	Yes	e.q. "sv-FI" or "sv-SE"	String
browser_user_agent	Client user agent	Yes	e.q. "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36"	String
referer	Origin URI of the request	Yes	e.q. "https://adeprimo.se"	String
accept_header	Client accept header	Yes	e.q. "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,/;q=0.8"	String
color_depth	Color depth of client browser	Yes	e.q. 24	Integer
screen_height	Screen height of client browser	Yes	e.q. 723	Integer
screen_width	Screen width of client browser	Yes	e.q. 1536	Integer
time_zone_offset	TimeZoneOffset of client browser	Yes	e.q. 0	Integer
java_enabled	Is java enabled on client browser	Yes	e.q. true/false	Boolean
delivery_address	Address object. Fields marked as required is always required in order to update any field of the address.	Optional		Object
first_name	First name	Required		String
last_name	Last name	Required		String
street	Streetname	Required		String
street_number	The street number, some subscription-systems only allow numerical values	Optional		String
zip_code	The zipcode	Required		String
floor	The floor	Optional		String
apartment_number	The apartment number	Optional		String
entrance	The entrance	Optional		String
city	The city	Required		String
dropbox	Dropbox	Optional		String
country_code	Country code	Required	SE, FI or AX	String

Here we can receive three types of answers. Depending on the status code received you will have to perform additional actions to complete the payment.

Purchase complete¶

HTTP 200 Purchase complete
{
  "item": {
    "receipt_id": "5e4becc109c04c404a46c744",
    "order_id": "ADEPRIMO-123",
    "message": "The payment was successfully authorised.",
    "status": "complete"
  }
}

If the status is "complete" then no additional actions need to be taken.

The "receipt_id" can be used to fetch the receipt for the recently made payment using the Me API.

Payment pending¶

HTTP 200 Payment pending
{
  "item": {    
    "message": "It's not possible to obtain the final status of the payment at this time.",
    "status": "pending"
  }
}

If the status is "pending" the user has completed the payment but the final result is not yet known. Payway will receive a callback when it is.

Payway either fails or completes the payment depending on the result.

For a successful result, the events associated with a completed purchase will be triggered. For instance order_closed.

In turn, all the events associated with a failed purchase will be triggered on an unsuccessful result. For instance payment_failure.

Action required¶

HTTP 200 Action required
{
  "item": {
    "action": {
      "paymentMethodType": "scheme",
      "token": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY...",
      "type": "threeDS2Fingerprint"
    },
    "session_reference": "session_reference",
    "message": "The issuer requires further shopper interaction before the payment can be authenticated. Returned for 3D Secure 2 transactions.",
    "status": "action_required"
  }
}

If you receive the status "action_required" you need to perform additional action(s) to complete the purchase.

See here for more info.

Errors¶

The error response is sent as application/JSON and will have an HTTP status code ranging between 400-500.

An error message will contain these properties in every response. Some error responses will add additional data for troubleshooting. Third-party errors from Adyen for example.

Error example

{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "correlation_id": "correlation_id only available for third party errors"
}