Skip to main content

​
Payment Widget Backend Integration Guide

​
Why is Backend Integration Needed?

Before you can render the Resurs Payment Widget on your frontend, your backend must securely obtain a session token from the Widget API. This token is required to initialize the widget for each customer session, ensuring secure and personalized payment experiences.

​
Integration Flow Overview

  1. Obtain a JWT access token from the Merchant API (/oauth2/token).
  2. Create a widget session by calling the Widget API /session endpoint, using the JWT as a bearer token.
  3. Receive a widget session token from the Widget API.
  4. Pass the session token to your frontend, where it will be used to initialize the payment widget.

​
Sequence Diagram

​
Step 1: Get a JWT Access Token

Request a JWT from the Merchant API. The response will contain an access token, valid for 1 hour, which you’ll use as a bearer token in subsequent API calls. POST /oauth2/token (See Merchant API documentation for details.)

​
Step 2: Create a Widget Session

Use the JWT access token to create a widget session. This returns a session token, which is required by the frontend widget. Example Request: 
POST /api/mock_payment_widget_service/session HTTP/1.1
Host: apigw.integration.resurs.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000"
}
Example Response: 
{
  "data": {
    "token": "rpmw_3jZ8k9Xy7Vb2N5mQ1rT6W",
    "expiresAt": "2025-10-04T10:30:00Z"
  }
}
  • The token is your session token for widget operations. Pass this to your frontend and reuse it until it expires.

​
Step 3: Provide the Session Token to the Frontend

The session token from the previous step must be sent to your frontend. The frontend will use this token to initialize and render the Resurs Payment Widget.

​
Optional: Fetching Payment Method Types for Widget

Note: This step is only needed for advanced use cases, such as custom filtering or categorization of payment methods in your widget. Most integrations do not require this.
Example Request: 
POST /api/mock_payment_widget_service/payment-methods/types HTTP/1.1
Host: apigw.integration.resurs.com
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "customerType": "B2C",
  "paymentMethodId": [
    "550e8400-e29b-41d4-a716-446655440000",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ]
}
Example Response: 
{
  "types": {
    "550e8400-e29b-41d4-a716-446655440000": "RESURS_INVOICE",
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8": "RESURS_PART_PAYMENT_SELECT_NOW"
  }
}
  • The response maps each payment method ID to its type.
Possible payment method types:
  • RESURS_INVOICE
  • RESURS_PART_PAYMENT_SELECT_LATER
  • RESURS_PART_PAYMENT_SELECT_NOW
  • RESURS_CARD
  • RESURS_REVOLVING_CREDIT
  • RESURS_NEW_REVOLVING_CREDIT
These types can be used to identify and handle payment methods in your frontend or backend logic.

​
Error Handling

When making backend requests to the Resurs Widget API, error responses follow the Problem Details for HTTP APIs (RFC 9457) standard. This provides a consistent structure for communicating errors in HTTP APIs, with additional fields for more expressive error reporting in modern APIs. Example Error Response (Session Endpoint): 
{
  "type": "https://api.resurs.se/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "One or more fields failed validation. Please check the provided data.",
  "instance": "/api/mock_payment_widget_service/session",
  "errors": [
    {
      "pointer": "#/storeId",
      "detail": "Field must be a valid UUID format"
    }
  ]
}
Example Error Response (Types Endpoint): 
{
  "type": "https://api.resurs.se/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "One or more fields failed validation. Please check the provided data.",
  "instance": "/api/mock_payment_widget_service/payment-methods/types",
  "errors": [
    {
      "pointer": "#/storeId",
      "detail": "Field must be a valid UUID format"
    }
  ]
}
  • type: URI reference for the error type
  • title: Short summary of the error
  • status: HTTP status code
  • detail: Human-readable explanation
  • instance: The request path
  • errors: Array of field-specific validation errors (if applicable)
Handling errors:
  • Always check the HTTP status code of the response.
  • Use the detail and errors fields to provide feedback or logging in your backend.
  • Common error codes: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Validation Error), 500 (Internal Server Error)