Pay with Card Data

POST /payment

Prerequisites

To use the "Pay with Card Data" feature, you need to have a JWE (JSON Web Encryption) key configured for your merchant account. Contact us at developers@straumur.is to obtain your JWE key and get started.

Attention

Handling encrypted card data comes with significant compliance requirements.

Merchants that choose this option must be PCI DSS certified and provide proof of certification to Straumur on a regular basis.

For most use cases, we recommend using Straumur Web Components, which are PCI-compliant by design and reduce the merchant’s compliance burden.

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 encrypted card data.

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

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	-	200
shopperIp	String	Required	IP address of the shopper trying to make the payment.	127.0.0.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.	-	-	-

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.

External 3D Secure

If you would like to use external 3D Secure authentication, please see the External 3D Secure page.

Configuring Encrypted Card Data on Frontend

To implement encrypted card data on your frontend, you'll need to encrypt the card details using your JWE key before sending them to the payment API.

Getting Your JWE Key (X.509 Certificate)

Implementation Demo

Install and import a third-party JavaScript JWT library. The following example demonstrates using JOSE (JSON Object Signing and Encryption)
Generate a public key from your X.509 certificate.

const certificate = `-----BEGIN CERTIFICATE-----
    MIIDdTCCAl2gAwIBAgIUFakeSerialNumber1234567890abcdef...
    -----END CERTIFICATE-----`;

const rsaPublicKey = await jose.importX509(certificate, "RSA-OAEP-256");

Prepare the card data object for encryption

const objectToEncrypt = JSON.stringify({
    cvc: "737",
    number: "4444 3333 2222 1111",
    expiryMonth: "03",
    expiryYear: "2030",
    generationtime: new Date().toISOString(),
});

info

Maintain the exact property order and casing: cvc, number, expiryMonth, expiryYear, generationtime

info

The generationtime field should be a string representing the current JavaScript date in ISO 8601 format.

Encrypt the card information

const encryptedData = await new jose.CompactEncrypt(new TextEncoder().encode(objectToEncrypt))
    .setProtectedHeader({ alg: "RSA-OAEP-256", enc: "A256GCM", version: "1" })
    .encrypt(rsaPublicKey);

Include the encrypted value in your payment request as shown in the request example.

{
    ...
    "encryptedCardData": {
        "encryptedValue": encryptedData;
    }
}

Test Refusal Reason

In staging environment you can simulate different refusal scenarios to verify how your integration handles them.

To simulate a specific refusal, you need to send an additional field in the request requestedTestAcquirerResponseCode for which the system will return the associated refusal reason.

{
  "terminalIdentifier": "1adfe4a1",
  "amount": 1000,
  "currency": "ISK",
  // ...
  "requestedTestAcquirerResponseCode": "22"
}

`Requested Test Acquirer Response Code`	`Result Code`
0	Error
1	Authorised
6	Refused
12	Refused
13	Received
22	Cancelled

Keep in mind, you can only test refusal reasons in the staging/test environment. Sending this field on live environment will result in an error.

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/additional_details, then the user would be redirected to https://your-store.com/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 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.

Prerequisites​

Test URL​

Request Example​

Request Body Fields​

Encrypted Card Data Fields​

Supported RecurringProcessingModel Values​

External 3D Secure​

Configuring Encrypted Card Data on Frontend​

Getting Your JWE Key (X.509 Certificate)​

Implementation Demo​

Test Refusal Reason​

Responses​

Possible Result Code Values​

Example - Authorised / Cancelled / Error / Refused Response​

Example - RedirectShopper Response​

Response Fields​

Action Fields​

Error Response​

Prerequisites

Test URL

Request Example

Request Body Fields

Encrypted Card Data Fields

Supported RecurringProcessingModel Values

External 3D Secure

Configuring Encrypted Card Data on Frontend

Getting Your JWE Key (X.509 Certificate)

Implementation Demo

Test Refusal Reason

Responses

Possible Result Code Values

Example - Authorised / Cancelled / Error / Refused Response

Example - RedirectShopper Response

Response Fields

Action Fields

Error Response