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.

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

Encrypted Card Data Fields

Field	Required	Description	Example
encryptedValue	Required	The JWE encrypted card data containing card number, expiry date, and CVV.	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.

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)

Contact us at developers@straumur.is to obtain your JWE key for encrypting card data.

Implementation Demo

1. Install and import a third-party JavaScript JWT library. The following example demonstrates using JOSE (JSON Object Signing and Encryption)

2. 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");

3. 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: cvv, number, expiryMonth, expiryYear, generationtime

info

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

4. 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);

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