Perform additional action

/adyen/perform_additional_action

Target audience: Developers

Release version: 4.2.0

Perform additional action

Introduction

This endpoint performs additional actions required to complete an Adyen purchase. E.q. 3DS authentication.

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/perform_additional_action
Production	https://backend.worldoftulo.com/external/api/v1/adyen/perform_additional_action

Requirements

Identity	Scope
Yes	/external/adyen/w

Curl example

curl --request POST \
  --url https://payway-api.stage.adeprimo.se/external/api/v1/adyen/perform_additional_action \
  --header 'authorization: Bearer <token-with-identity>' \
  --header 'content-type: application/json' \
  --data '{
    "details": {
      "threeds2.fingerprint": "eyJ0aHJlZURTQ29tcEluZCI6IlkifQ=="
    },
    "session_reference": "5e4bfdf209c04c50ab62669d",
    "origin": "https://purchase.example.org"
  }'

Parameters

Parameter	Description	Required	Format	Type
details	Parameters received from Adyen either from dropin.handleAction or provider redirect	Yes	Provided by Adyen	Object
session_reference	Id of the payway purchase session	Yes	Size range ..24 Allowed values: "/^[a-f\d]{24}$/i"	String
origin	URI where purchase is performed (E.g. https://purchase.example.org)	Yes	Size range: ..1024 Allowed values: uri regex that is too long to show here. Must be absolute	String

How to construct the details parameter?

The contents for the details object is provided by Adyen either from the onAdditionalDetails event or by a provider redirect, such as swish or a bank.

In the case of onAdditionalDetails you'll need to post the data from Adyen to your server. There you'll collect all the body parameters and pass them in the details object.

The same is true for a provider redirect. You'll need to maintain a GET and a POST endpoint for the provider callback. You define the callback url with the return_url parameter in place_order.

In the case of a GET callback you'll need to collect all query parameters and pass them in the details object.
In the case of a POST callback you'll need to collect the body parameters and pass them in the details object.

See code example for more info on how to construct the details parameter.

Response

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" yet again you need to perform additional action(s) to complete the purchase until you receive the status "pending" or "complete".

The "action" object received needs to be passed to the dropin.handleAction method found in the script. The result from dropin.handleAction should then be sent to your server to complete the additional action by calling the /perform additional action endpoint.

You will also receive the "session_reference" again.

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