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