Pay with Token

POST /payment

Prerequisites

To use the "Pay with Token" feature for recurring/subscription payments, first ensure that you have acquired the Token.

Tokens can be obtained in the webhook for each Hosted Checkout where you have set the "Recurring Processing Model" optional field.

For more details, refer to the Recurring Processing Model optional parameter documentation and Token additional data field on webhooks documentation.

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 token.

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/straumur_additional_details",
  "tokenDetails": {
    "tokenValue": "A1B2C3D4E5F6G7H8",
    "recurringProcessingModel": "CardOnFile"
  }
}

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/straumur_additional_details	-	-
tokenDetails	Object	Required	The token information for the payment.	-	-	-

Token Details Fields

Field	Required	Description	Example
tokenValue	Required	The card token used for the transaction. You will obtain tokens through the Tokenization event on the webhooks.	A1B2C3D4E5F6G7H8
recurringProcessingModel	Required	The type of transaction that will be processed with this token.	CardOnFile

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.

Responses

Possible Result Code Values

Result Code	Description
Authorised	The payment was successfully authorised.
RedirectShopper	The issuer requires the shopper to provide authentication. Redirect the shopper to complete the authentication.
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 - Authorised / Cancelled / Error / Refused 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", // Cancelled, Error, Refused
  "action": null,
  "responseDateTime": "2025-01-04T09:50:14.343503Z",
  "responseIdentifier": "e3605f81-6b09-4ce1-83ad-5a8d49f3cd44"
}

Example - RedirectShopper Response

info

Status RedirectShopper means that the transaction requires the shopper to complete a 3DS check.

Please redirect the shopper to the action.url with the mentioned action.method. The action response will contain a GET method and a simple redirect will suffice.

After the shopper completes the 3DS, they will be redirected to the provided returnUrl in the request.

If the returnUrl provided was https://your-store.com/straumur_additional_details, then the user would be redirected to https://your-store.com/straumur_additional_details?redirectResult=Ab02b4c0....

You will need to call the payment/details endpoint with the query parameters from 3DS result.

{
  "checkoutReference": "fp3afbpdtsw3jw1br7lxi0lcd4gnfq6wxdrueeq2cwlks5vahj",
  "payfacReference": null,
  "reference": "9990QQAZ1221",
  "resultCode": "RedirectShopper",
  "action": {
    "method": "GET",
    "url": "https://3ds-website-redirect.com/..."
  },
  "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 hosted 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.
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.