Place gift order

/adyen/place_gift_order

Target audience: Developers

Release version: 4.7.2

Place gift order¶

Introduction¶

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

Attention

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

Attention

As for now this endpoint can only be used for creating gift orders on campaigns that are configured to be sold as gifts using the campaign gift rules.

URI¶

Environment	URI
Stage	https://payway-api.stage.adeprimo.se/external/api/v1/adyen/place_gift_order
Production	https://backend.worldoftulo.com/external/api/v1/adyen/place_gift_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_gift_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",
  "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: ..128	String
subscription_start_date	Date when the subscription will be activated Note that this property will be ignored if voucher_purchase is set to true	Optional	Allowed values: 2020-05-15	DateTime
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, the gift subscriptions delivery address. 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
staircase	The staircase	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 gift_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¶

This API uses the common error conventions of the Payway API

See common error responses