External 3D Secure

POST /payment

Test URL

The payment request will be made to the following URL:

https://checkout-api.staging.straumur.is/api/v1/payment

This call will create a payment request with the provided external 3D secure data.

You can use external 3D secure for both Token payments and encrypted card data payments.

Request Example

{
  "terminalIdentifier": "1adfe4a1",
  "amount": 1000,
  "currency": "ISK",
  "reference": "9990QQAZ1221",
  "shopperIp": "127.0.0.1",
  "origin": "https://your-store.com/",
  "channel": "Web",
  "returnUrl": "https://your-store.com/additional_details",
  "encryptedCardData": {
    "encryptedValue": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...",
    "recurringProcessingModel": "CardOnFile",
    "merchantShopperReference": "shopper_12345"
  },
  "external3DSecure": {
    "authenticationResponse": "Y",
    "directoryResponse": "C", 
    "cavv": "3q2+78r+ur7erb7vyv66vv////8=",
    "dsTransID": "c4e59ceb-a382-4d6a-bc87-385d591fa09d",
    "eci": "05",
    "threeDSVersion": "2.1.0",
    "challengeCancel": "00"
  }
}

Request Body Fields

Field	Type	Required	Description	Example	Min Length	Max Length
terminalIdentifier	String	Required	The terminal identifier to uniquely identify the terminal. You can find your Terminal Identifier in the Merchant Portal. Open Section "Terminals" > Select Terminal to open Details panel > Copy Terminal Identifier	1adfe4a1
amount	Integer	Required	The adjusted amount to be charged in minor units.	127300	-	-
currency	String	Required	The three-character ISO currency code.	ISK	3	3
reference	String	Required	Merchant reference to uniquely identify a payment.	9990QQAZ1221	1	100
shopperIp	String	Required	IP address of the shopper trying to make the payment.	127.0.0.1	1	100
origin	String	Required	Location where the payment originates from. This must be in line with the channel provided.	https://your-store.com/	-	-
channel	String	Required	Location where the payment originates from. Accepted Values: Web, Android, IOS	Web	-	-
returnUrl	String	Required	Location where the shopper should be redirected if 3DS occurs. This must be in line with the channel provided.	https://your-store.com/additional_details	-	-
encryptedCardData	Object	Required	The encrypted card information for the payment.	-	-	-
external3DSecure	Object	Optional	External 3DS authentication results for payments that have been pre-authenticated outside of Straumur.	-	-	-

Encrypted Card Data Fields

Field	Required	Description	Example
encryptedValue	Required	The JWE encrypted card data containing card number, expiry date, and CVC.	eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...
recurringProcessingModel	Optional	The type of transaction that will be processed with this encrypted card data. This field must be set if merchantShopperReference is used.	CardOnFile
merchantShopperReference	Optional	Your unique reference for the shopper to enable future recurring payments or card-on-file transactions. This field must be set if recurringProcessingModel is used.	shopper_12345

Supported RecurringProcessingModel Values

Value	Description
CardOnFile	Card details are stored for one-click purchases, omnichannel journeys, or subscriptions with non-fixed schedules.
Subscription	Transactions for fixed or variable amounts following a fixed schedule.
UnscheduledCardOnFile	Unscheduled transactions using stored card details, such as automatic top-ups based on predefined conditions.

External3DSecure Fields

Field	Required	Description	Example
authenticationResponse	Required	The authentication response from the 3DS authentication. Required unless DirectoryResponse is "Y" (frictionless flow).	Y
directoryResponse	Required	The directory server response indicating if the cardholder is enrolled for 3DS authentication.	C
cavv	Required	Cardholder Authentication Verification Value. A cryptographic value that provides evidence of the authentication.	3q2+78r+ur7erb7vyv66vv////8=
dsTransId	Required	Directory Server Transaction ID. Unique identifier assigned by the directory server for the transaction.	c4e59ceb-a382-4d6a-bc87-385d591fa09d
eci	Required	Electronic Commerce Indicator. A value that indicates the security level of the transaction.	05
threeDSVersion	Required	The version of 3DS protocol used for the authentication.	2.1.0
tokenAuthenticationVerificationValue	Optional	Token Authentication Verification Value for tokenized transactions.	null
challengeCancel	Optional	Indicates if the authentication challenge was cancelled.	00
transStatusReason	Optional	Additional information about the transaction status.	18

Responses

Possible Result Code Values

Result Code	Description
Authorised	The payment was successfully authorised.
Cancelled	The payment was cancelled (by either the shopper or your own system) before processing was completed.
Error	There was an error when the payment was being processed.
Refused	The payment was refused.

Example Response

info

Status Authorised means that the transaction has gone through.

You will also receive a webhook regarding this transaction with additional details.

{
  "checkoutReference": "fp3afbpdtsw3jw1br7lxi0lcd4gnfq6wxdrueeq2cwlks5vahj",
  "payfacReference": "T3WJMB84TFCCJ875",
  "reference": "9990QQAZ1221",
  "resultCode": "Authorised", // or Cancelled, Error, Refused
  "action": null,  // always null since no 3DS redirect if 3rd Party 3DS is provided
  "responseDateTime": "2025-01-04T09:50:14.343503Z",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44"
}

Response Fields

This table outlines the response fields with their corresponding types, descriptions and examples.

Field	Type	Description	Example
checkoutReference	String	The reference to uniquely identify the checkout session.	faf984ad76db7b2dea3f7bab
payfacReference	String	Straumur reference to uniquely identify a payment.	T3WJMB84TFCCJ875
reference	String	Merchant reference to uniquely identify a payment.	9990QQAZ1221
resultCode	String	The status of the payment. Can be authorized or a redirect shopper instruction.	Authorised
action	Object	Contains information about the 3DS action you need to consume.	null
responseDateTime	String	The date and time when the response was generated.	2024-09-04T09:50:14.343503Z
responseIdentifier	String	The unique identifier for the response.	7be7111c-2e8e-4cd4-a5ba-f15bdfd177c1

Action Fields

Field	Type	Description	Example
method	string	Specifies the HTTP method, for example GET or POST.	GET
url	string	Specifies the URL to redirect to.	https://3ds-website-redirect.com/...

Error Response

Our error responses are standardised. Please see Errors.

You can also find a detailed overview of our HTTP Status Codes.