Submit 3DS Challenge Outcome

post/api/3ds-challenges/{challengeId}/outcome

Submit the outcome of a 3DS Strong Customer Authentication (SCA) challenge. Call this endpoint after presenting the cardholder with the challenge received via the Payment 3DS SCA webhook, to approve or decline the transaction on their behalf.

Request

Path Parameters

challengeIdstringrequired
The Immersve ID for the 3DS challenge, as received in the Payment 3DS SCA webhook payload.

Body application/json

One of

outcomestringrequired
Allowed values:approved
The cardholder's response to the SCA challenge.
authTypestringdeprecated
The authentication method used by the cardholder. May include the following values: pin, face-id, fingerprint, device-passcode. Deprecated — use authTypes instead. Either authType or authTypes must be provided.
authTypesstring[]required
A list of authentication methods used by the cardholder. May include the following values: pin, face-id, fingerprint, device-passcode. Either authTypes or the deprecated authType must be provided.
authenticatedAtstring<date-time>required
The timestamp when the cardholder completed authentication in UTC.
metadataobjectrequired
Additional context about the app and device used during authentication.
- appIdstringrequired
  An ID for the app submitting the outcome.
- deviceIdstringrequired
  A stable, platform-native ID for the cardholder's device. Should be consistent across sessions and recognisable to the cardholder.
- ipAddressstringrequired
  The IP address of the cardholder's device.

outcomestringrequired
Allowed values:declined
The cardholder's response to the SCA challenge.
metadataobjectrequired
Additional context about the app and device used during authentication.
- appIdstringrequired
  An ID for the app submitting the outcome.
- deviceIdstringrequired
  A stable, platform-native ID for the cardholder's device. Should be consistent across sessions and recognisable to the cardholder.
- ipAddressstringrequired
  The IP address of the cardholder's device.

Response

Challenge outcome submitted successfully.

Request fields are invalid.

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
errorsobject[]
Items
- messagestring
- pathstring
  The location of the invalid path param, query param or payload attribute.

No Authorization to access resource.

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
reasonstring

Example

Example Request

ServerAuthentication

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://api.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "approved",
  "authType": "string",
  "authTypes": [
    "face-id"
  ],
  "authenticatedAt": "2024-01-01T12:00:00Z",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

curl 'https://test.immersve.com/api/3ds-challenges/{challengeId}/outcome' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '{
  "outcome": "declined",
  "metadata": {
    "appId": "com.example.wallet",
    "deviceId": "FBDDF7E1-7A11-4D4E-9C9B-3D8E5C2F1A4B",
    "ipAddress": "192.0.2.1"
  }
}'

Example Response

No response body.

{
  "statusCode": 400,
  "statusName": "Bad Request",
  "errorCode": "INVALID_REQUEST_INPUT",
  "errors": [
    {
      "message": "Invalid type",
      "path": "items[1].attributes.invalidField"
    }
  ]
}

{
  "statusCode": 403,
  "statusName": "Forbidden",
  "errorCode": "FORBIDDEN",
  "reason": "Unauthorized"
}