Versions

 Changelog

 Payment flow

A payment token can be used only once and a new payment token is required for every order. For saving customer's credit card details see the description for a card token.

E-payments, hosted card payments and terminal payments	Inline frame card payments
This method may be used to implement banks, credit invoices and hosted card form payment methods. Payment buttons can be embedded to your checkout page. Steps: Request a payment token (type of e-payment or terminal) (Optional) You may preselect a payment method (to skip the payment selection page) Redirect user to url generated from returned payment token Get return values from user return and / or from notify callback Show sequence diagram	You have two options to implement embedded card payments to your checkout page. The first way is to use our minified pay page inside an iframe. The second option is to display our card form inside an iframe and then using postMessage method to pass a payment token to it. The second option allows more flexible integration as it's possible to display the card form before a payment token has been created. Compare the two options to find the best fit for your business. Steps for the minified pay page: Request a payment token (type of e-payment) Open an inline frame with an url generated from returned payment token and use the ?minified GET parameter. Get return values from user return and / or from notify callback Steps for the inline card form: Display our card form inside an iframe Request a payment token (type of embedded) Pass the token to the card form using postMessage method Get return values from user return and / or from notify callback Note: Visa Secure Program has defined some cardholder related 3DS fields mandatory starting from August 12th 2024. When using the inline card form, make sure that the Payment token request includes a Customer object with at least the following fields related to the cardholder: firstname lastname email
Charge card token
Customer's credit card details can be tokenized by requesting a card token in the payment token request. A card token can be used multiple times and is suitable for example one click payment solutions or recurring payments. There are two different ways a card token might be used. In a Merchant initiated transaction (MIT) the payment is processed by the merchant on behalf of the cardholder and the cardholder is not present during the payment. This method should be used for recurring payments. In a Customer initiated transaction (CIT) the card holder is present during the payment. In this case an additional card holder authentication might be required and this should be handled in your integration. Steps to accuire a card token: To tokenize a card, set register_card_token to 1 in the payment token request Use the returned card token and set the initiator object according to use case (MIT or CIT) in the charge card token request. If the initiator is not set then the payment defaults to MIT In case of a CIT transaction, handle possible card holder authentication e.g. 3DS and redirect the customer using the returned verify object See our general guidelines about how cards should be charged using a card token.

 Test credentials

The api can be tested with testing account (you may request one from here).

Available test cards and credentials can be found from the testing page.

 Currencies

The following currencies are supported by different payment methods. Currencies use ISO 4217 format.

Group code and payment method codes for the selected field are also displayed.

 Common objects

Common objects used with the API.

 Customer object

Note that Visa Secure Program has defined some cardholder related 3DS fields mandatory starting from August 12th 2024. We recommend that you send at least firstname, lastname and email.
Otherwise the customer will need to provide the missing information on our payment page.

"customer": {  
  "firstname": "Test",
  "lastname": "Person",
  "email": "test.person@example.com",
  "address_street": "Testaddress 1",
  "address_city": "Testlandia",
  "address_zip": "123456"
}

 Product object

"products": [  
  {  
    "id": "as123",
    "title": "Product 1",
    "count": 2,
    "pretax_price": 100,
    "tax": 24,
    "price": 124,
    "type": 1
  },
  {  
    "id": "sku123",
    "title": "Product 2",
    "count": 1,
    "pretax_price": 100,
    "tax": 0,
    "price": 100,
    "type": 1
  },
  {  
    "id": "ab1",
    "title": "Shipping",
    "count": 1,
    "pretax_price": 199,
    "tax": 0,
    "price": 199,
    "type": 2
  }
]

 Payment token request

request url https://www.vismapay.com/pbwapi/auth_payment

request type HTTP JSON

Payment token request is done from backend to Visma Pay API.

 Payment token request fields

 Payment method object

Example request body

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "test-order-1415463675",
  "amount": 548,
  "currency": "EUR",
  "email": "test.person@example.com",
  "payment_method": {
    "type": "e-payment",
    "return_url": "https://test.shop.com/return",
    "notify_url": "https://test.shop.com/notify",
    "lang": "fi",
    "token_valid_until": "1442403776",
    "selected": [
      "nordea"
    ]
  },
  "authcode": "8DF90FF9582EC87C073ACEE5C6194E9E2280D6028D55...",
  "customer": {  
    "firstname": "Test",
    "lastname": "Person",
    "email": "test.person@example.com",
    "address_street": "Testaddress 1",
    "address_city": "Testlandia",
    "address_zip": "123456"
  },
  "products": [  
    {  
      "id": "as123",
      "title": "Product 1",
      "count": 2,
      "pretax_price": 100,
      "tax": 24,
      "price": 124,
      "type": 1
    },
    {  
      "id": "sku123",
      "title": "Product 2",
      "count": 1,
      "pretax_price": 100,
      "tax": 0,
      "price": 100,
      "type": 1
    },
    {  
      "id": "ab1",
      "title": "Shipping",
      "count": 1,
      "pretax_price": 200,
      "tax": 0,
      "price": 200,
      "type": 2
    }
  ]
}

 Payment token return

response type HTTP JSON

 Payment token return fields

Example response body

{
  "result": 0,
  "token": "kufoaskjhigrmkn45p2356n34",
  "type": "e-payment"
}

{
  "result": 1,
  "errors": [  
    "The amount must be an integer.",
    "The contact.email format is invalid.",
    "The product.price sum does not match with the total amount."
  ]
}

 Charge redirection

request url https://www.vismapay.com/pbwapi/token/{:token}

request type HTTP GET

Both e-payment and terminal payments use the same redirection url.

After the payment has been created and the type of the payment is e-payment or terminal, the user should be redirected to the url constructed from the returned token. This can be done with simple HTTP redirect to the request url.

If charge card token endpoint has returned verify object, the customer should be redirected to the given token URL for 3DS verification.

In terminal payments user will be redirected to terminal selection page unless there is only one terminal available for the merchant or defined in the selected_terminals field. In that case, user is redirected to the POS page.

You can also append the URL with ?minified GET parameter to get minified payment page. Minified payment page is stripped down to bare minimum and hence is easier to integrate as a part of your webshop. Minified payment page only shows a card form (no other payment methods). This payment page is optimized for iframe and mobile applications. If the default payment page is displayed in iframe, some bank- and ACS pages might not work correctly. The minified payment page forces the browser to make page redirects on window level instead of inside the iframe. This is done by setting target="_top" in the card form. If you use sandbox attribute in your iframe setup, make sure you have allow-top-navigation, allow-scripts, allow-same-origin and allow-forms parameters enabled.

 User & notify return

request type HTTP GET

 Return codes

In a notify request only return values 0 or 1 are used.

Example

GET https://test.shop.com/return/?RETURN_CODE=0&ORDER_NUMBER=12345&SETTLED=1&AUTHCODE=640B574C2A93E16D30644BEE28CD3F511672D5BB957B2C6CD95F9F2EEDAB398C HTTP/1.1

 Displaying inline card form

iframe url https://www.vismapay.com/e-payments/embedded_card_form?lang={fi,en,sv,ru}

The inline card form page forces the browser to make page redirects (e.g. 3DS redirects) on a window level instead of inside the iframe. This is done by setting target="_top" in the inline form. If you use sandbox attribute in your iframe setup, make sure you have allow-top-navigation, allow-scripts, allow-same-origin and allow-forms parameters enabled.

<iframe id="iframe" height="220px" src="https://www.vismapay.com/e-payments/embedded_card_form?lang=en"></iframe>

 Charging inline card form

After you have requested a payment token you can charge the inline card form by sending the token using postMessage to the iframe.

The charge message is in JSON and the fields are described below.

If card details are inputted correctly to the form, a user is redirected on a window level and eventually to the return_url given in the payment token request. See the returned fields for parsing the user return.

 Charge message fields

 Validate message fields

To catch a response you should add an event listener to your page. The response tells if card details are inputted correctly to the inline card form.

 Validate response event

Example charge message

var chargeMessage = {
	action: "pay",
	token: "kufoaskjhigrmkn45p2356n34"
}

document.getElementById("iframe").contentWindow.postMessage(
	JSON.stringify(chargeMessage), 
	"https://www.vismapay.com/"
)

Example validate event

// add an event listener
window.addEventListener('message', function(event) {
	var data = JSON.parse(event.data);

	if(data.valid)
	{
		// the inline card form is validated successfully
	}
})

var validateMessage = {
	action: "validate"
}

document.getElementById("iframe").contentWindow.postMessage(
	JSON.stringify(validateMessage), 
	"https://www.vismapay.com/"
)

 Charge card token request

request url https://www.vismapay.com/pbwapi/charge_card_token

request type HTTP JSON

Charge a card with a card token. This call can be used for recurring and one click payments. For the first charge, and to acquire required card_token, generate payment token, charge customer and check the payment status (returns the card_token).

If the initiator object type is set to 2 (Customer Initiated Transaction), the issuer might require 3DS authentication. If 3DS is required the endpoint will return verify object with type 3ds. The customer should be redirected to the given token url for 3DS authentication like in the charge redirect.

 Charge card token request fields

Example request body

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "test-order-2415442341",
  "amount": 547,
  "currency": "EUR",
  "card_token": "sdlklky4456ggi84358",
  "authcode": "C71FA1F5C34C3558DC57E07034C7EF8DDAF7C5C0BB8A...",
  "customer": {  
    "firstname": "Test",
    "lastname": "Person",
    "email": "test.person@example.com",
    "address_street": "Testaddress 1",
    "address_city": "Testlandia",
    "address_zip": "123456"
  },
  "products": [  
    {  
      "id": "as123",
      "title": "Product 1",
      "count": 2,
      "pretax_price": 100,
      "tax": 24,
      "price": 124,
      "type": 1
    },
    {  
      "id": "sku123",
      "title": "Product 2",
      "count": 1,
      "pretax_price": 100,
      "tax": 0,
      "price": 100,
      "type": 1
    },
    {  
      "id": "ab1",
      "title": "Shipping",
      "count": 1,
      "pretax_price": 199,
      "tax": 0,
      "price": 199,
      "type": 2
    }
  }
  ],
  "initiator": {
    "type": 2,
    "return_url": "https://test.shop.com/return",
    "notify_url": "https://test.shop.com/notify",
    "lang": "fi",
    "browser_info": {
      "accept_header": "text/html,application/xml;q=0.9,*/*;q=0.8",
      "java_enabled": 1,
      "language": "fi-FI",
      "color_depth": 32,
      "screen_height": 1080,
      "screen_width": 1920,
      "timezone_offset": 120,
      "user_agent": "Mozilla/5.0"
    }
  }
}

 Charge card token return

response type HTTP JSON

 Charge card token return fields

Example responses

{
  "result": 0,
  "settled": 1,
  "source": {
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "exp_year": 2018,
    "exp_month": 5,
    "card_token": "sfasdfhmn39275y249035bhdfxslg",
    "error_code": null
  }
}

{
  "result": 30,
  "verify": {
    "token": "kufoaskjhigrmkn45p2356n34",
    "type": "3ds"
  }
}

 Payment status request

request url https://www.vismapay.com/pbwapi/check_payment_status

request type HTTP JSON

Payment status request is done from backend to Visma Pay API.

 Payment status request fields

Example request body

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "token": "kufoaskjhigrmkn45p2356n34",
  "authcode": "F54E61647170963E3CE338EABF8410078817D0B3A516..."
}

 Payment status return

response type HTTP JSON

 Payment status return JSON object fields

Example response body

{
  "result": 0,
  "settled": 1,
  "source": {
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "exp_year": 2018,
    "exp_month": 5,
    "card_token": "sfasdfhmn39275y249035bhdfxslg",
    "card_verified": "Y",
    "card_country": "FI",
    "client_ip_country": "FI",
    "error_code": null
  }
}

 Capture payment request

request url https://www.vismapay.com/pbwapi/capture

request type HTTP JSON

Capture payment

 Capture payment request fields

Example request

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "webshop_stuff-1234567",
  "authcode": "F54E61647170963E3CE338EABF8410078817D0B3A516..."
}

 Capture payment return

response type HTTP JSON

 Capture payment return JSON object fields

Example response body

{
  "result": 0
}

 Cancel payment request

request url https://www.vismapay.com/pbwapi/cancel

request type HTTP JSON

Cancel payment

 Cancel payment request fields

Example request

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "webshop_stuff-1234567",
  "authcode": "F54E61647170963E3CE338EABF8410078817D0B3A516..."
}

 Cancel payment return

response type HTTP JSON

 Cancel payment return JSON object fields

Example response body

{
  "result": 0
}

 Get card token request

request url https://www.vismapay.com/pbwapi/get_card_token

request type HTTP JSON

Get a card token

 Get card token request fields

Example request

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "card_token": "sfasdfhmn39275y249035bhdfxslg",
  "authcode": "2B221E1C5F732787E1528EF04D4571CF85EF08EBAB4E..."
}

 Get card token return

response type HTTP JSON

 Get card token return JSON object fields

Example response body

{
  "result": 0,
  "source": {
    "object": "card",
    "last4": "4242",
    "brand": "Visa",
    "exp_year": 2018,
    "exp_month": 5,
    "card_token": "sfasdfhmn39275y249035bhdfxslg"
  }
}

 Delete card token request

request url https://www.vismapay.com/pbwapi/delete_card_token

request type HTTP JSON

Delete a card token

 Delete card token request fields

Example request

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "card_token": "sfasdfhmn39275y249035bhdfxslg",
  "authcode": "2B221E1C5F732787E1528EF04D4571CF85EF08EBAB4E..."
}

 Delete card token return

response type HTTP JSON

 Delete card token return fields

Example response

{
  "result": 0
}

 Get payment request

request url https://www.vismapay.com/pbwapi/get_payment

request type HTTP JSON

Retrieve information about a specific payment. Get payment request is done from backend to Visma Pay API.

 Get payment request fields

Example request body

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "test_order_1",
  "authcode": "ACA7E762BA1138F0C5C8561599D72409055A16701B901..."
}

 Get payment return

response type HTTP JSON

 Get payment return JSON object fields

 Payment object

 Refund object

 Payment product object

 Payment customer object

Example of a successful response body

{
  "result": 0,
  "payment": {
    "id": 123,
    "amount": 562,
    "currency": "EUR",
    "order_number": "test_order_1",
    "created_at": "2018-09-12 08:30:22",
    "status": 4,
    "refund_type": "email",
    "source": {
      "object": "e-payment",
      "brand": "Nordea"
    },
    "customer": {
      "firstname": "Test",
      "lastname": "Person",
      "email": "test.person@vismapay.com",
      "address_street": "",
      "address_city": "",
      "address_zip": ""
    },
    "payment_products": [{
      "id": "as123",
      "product_id": 1123,
      "title": "Product 1",
      "count": 2,
      "pretax_price": 100,
      "tax": 24,
      "price": 124,
      "type": 1
    },
    {
      "id": "sku123",
      "product_id": 1124,
      "title": "Product 2",
      "count": 1,
      "pretax_price": 100,
      "tax": 14,
      "price": 114,
      "type": 1
    },
    {
      "id": "ab1",
      "product_id": 1125,
      "title": "Shipping",
      "count": 1,
      "pretax_price": 200,
      "tax": 0,
      "price": 200,
      "type": 2
    }],
    "refunds": [{
      "id": 123,
      "amount": -114,
      "created_at": "2018-09-12 09:09:01",
      "order_number": "test_order_1",
      "status": 9,
      "payment_products": [{
        "id": "sku123",
        "product_id": 1124,
        "title": "Product 2",
        "count": 1,
        "pretax_price": 100,
        "tax": 14,
        "price": 114,
        "type": 1
      }]
    }]
  }
}

 Get refund request

request url https://www.vismapay.com/pbwapi/get_refund

request type HTTP JSON

Retrieve information about a specific refund. Get refund request is done from backend to Visma Pay API.

 Get refund request fields

Example request body

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "refund_id": "123",
  "authcode": "ECA7E762BA1138F0C5CB561599D72409066A16701B901..."
}

 Get refund return

response type HTTP JSON

 Get refund return JSON object fields

Example of a successful response body

{
  "result": 0,
  "refund": {
    "refund_id": 123,
    "amount": -114,
    "created_at": "2018-09-12 09:09:01",
    "order_number": "test_order_1",
    "status": 9,
    "payment_products": [
      {
        "id": "sku123",
        "product_id": 1124,
        "title": "Product 2",
        "count": 1,
        "pretax_price": 100,
        "tax": 14,
        "price": 114,
        "type": 1
      }
    ]
  }
}

 Refund payment request

request url https://www.vismapay.com/pbwapi/create_refund

request type HTTP JSON

Refund payment. Please contact our support if you want to use this feature.

Payment can be refunded if the status of the payment is 4 (Settled), 5 (Paid) or 15 (Forwarded Paid). Status of the payment is returned in the Get payment request

 Refund payment request fields

Example request (with amount)

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "webshop_stuff-1234567",
  "amount": 5000,
  "authcode": "F54E61647170963E3CE338EABF8410078817D0B3A516..."
}

Example request (with products)

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "order_number": "webshop_stuff-1234567",
  "notify_url": "https://test.shop.com/return/",
  "authcode": "F54E61647170963E3CE338EABF8410078817D0B3A516...",
  "products": [
    {
      "product_id": 9532,
      "count": 1
    },
    {
      "product_id": 9534,
      "count": 2
    }
  ]
}

 Refund payment return

response type HTTP JSON

 Refund payment return JSON object fields

Example response body

{
  "result": 0,
  "type": "instant",
  "refund_id": 2587411
}

 Refund payment notify return

response type HTTP GET

Notify-request is done to the notify_url specified in the Refund payment request.

 Notify-request fields

Example

GET https://test.shop.com/return/?RETURN_CODE=0&REFUND_ID=2587411&AUTHCODE=C250B657F55442415F5F2422D20453D029E381E17EF665BA24FB1109AA045A71 HTTP/1.1

 Cancel refund request

request url https://www.vismapay.com/pbwapi/cancel_refund

request type HTTP JSON

Cancel a refund request. Only refunds where type is email and are not accepted by a customer can be cancelled.

 Refund payment request fields

Example request

{
  "version": "w3.1",
  "api_key": "15-ku74gbued",
  "refund_id": 235468,
  "authcode": "F54E61647170963E3CE338EABF8410078817D0B3A516..."
}

 Cancel refund return

response type HTTP JSON

 Cancel refund request return JSON object fields

Example response body

{
  "result": 0
}