Payment Agreements

Server

Get payment agreement status

GET

https://api.entur.io/sales

/v1/payment-agreements/{agreementId}

Returns the current status and details of a payment agreement. The Vipps confirmation URL is only included while the agreement is pending customer confirmation (CREATED or PENDING status).

Get payment agreement status › path Parameters

agreementId

integer · int64 · required · style: simple

agreementId

Get payment agreement status › Headers

Entur-POS

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

Entur Client Header. It is required that all consumers identify themselves by using this header. Entur will deploy strict rate-limiting policies on API-consumers who do not identify with a header and reserves the right to block unidentified consumers. The structure of ET-Client-Name should be: <company>-<application>.

X-Correlation-Id

string · style: simple

Correlation id

Entur-Distribution-Channel

string · style: simple

Distribution channel identifier.

Get payment agreement status › Responses

Response containing payment agreement details.

PaymentAgreementResponse

agreementId

integer · int64

The unique identifier of the payment agreement.

status

string · enum

The current status of the agreement.

Enum values:

CREATED

PENDING

ACTIVE

STOPPED

EXPIRED

productName

string

Name of the product or subscription.

productDescription

string

Description of the product or subscription, shown to the customer in the provider's app.

AgreementPricing

Base pricing model for a payment agreement.

AgreementResponseProviderData

Base provider-specific data in an agreement response.

GET/v1/payment-agreements/{agreementId}

curl https://api.entur.io/sales/v1/payment-agreements/:agreementId \
  --header 'Entur-POS: <string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "agreementId": 42,
  "status": "PENDING",
  "productName": "Månedlig reisekort Oslo",
  "productDescription": "Månedlig reisekort gyldig i Oslo-sonen",
  "pricing": {
    "agreementType": "FIXED",
    "amount": 49900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 1
    }
  },
  "providerData": {
    "agreementProvider": "VIPPS",
    "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9"
  }
}

json

application/hal+json

Update payment agreement

PATCH

https://api.entur.io/sales

/v1/payment-agreements/{agreementId}

Updates the mutable parts of a payment agreement, both at the provider and locally.

Every field is optional and at least one must be supplied; omitting a field leaves it unchanged.

pricing is not currently supported — supplying it returns 501. Only FLEXIBLE agreements can be created, and FLEXIBLE pricing has no updatable fields. The pricing field and the underlying FixedPricing/VariablePricing schemas are kept in the spec and reserved for future use; they will be enabled when FIXED and VARIABLE agreement types are introduced.

productName and the provider's merchantAgreementUrl can be updated on FLEXIBLE agreements.

The agreement must be in status PENDING or ACTIVE.

Update payment agreement › path Parameters

agreementId

integer · int64 · required · style: simple

agreementId

Update payment agreement › Headers

Entur-POS

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Entur-Distribution-Channel

string · style: simple

Distribution channel identifier.

Update payment agreement › Request Body

Request to update a payment agreement. Every field is optional, but at least one must be supplied — omitting a field leaves it unchanged. `pricing` is not currently supported and returns 501; only `productName`, `productDescription`, and `providerData` can be updated on FLEXIBLE agreements.

UpdatePaymentAgreementRequest

productName

string · maxLength: 45

Name of the product or subscription.

productDescription

string · maxLength: 100

Description of the product or subscription, shown to the customer in the provider's app.

AgreementUpdatePricing

Pricing model for updating an agreement. Not yet supported — supplying this field returns 501. FLEXIBLE is absent because its amount is set per charge and has nothing to update; FIXED and VARIABLE are reserved for future use.

AgreementUpdateProviderData

Base provider-specific data for updating an agreement. Contains only the fields the provider allows changing after the agreement exists — which is why this is a separate schema from AgreementRequestProviderData.

Update payment agreement › Responses

Response containing payment agreement details.

PaymentAgreementResponse

agreementId

integer · int64

The unique identifier of the payment agreement.

status

string · enum

The current status of the agreement.

Enum values:

CREATED

PENDING

ACTIVE

STOPPED

EXPIRED

productName

string

Name of the product or subscription.

productDescription

string

Description of the product or subscription, shown to the customer in the provider's app.

AgreementPricing

Base pricing model for a payment agreement.

AgreementResponseProviderData

Base provider-specific data in an agreement response.

PATCH/v1/payment-agreements/{agreementId}

curl https://api.entur.io/sales/v1/payment-agreements/:agreementId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Entur-POS: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "pricing": {
    "agreementType": "FIXED",
    "amount": 59900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 1
    }
  }
}'

Example Request Body

{
  "pricing": {
    "agreementType": "FIXED",
    "amount": 59900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 1
    }
  }
}

json

application/json

Example Responses

{
  "agreementId": 42,
  "status": "ACTIVE",
  "productName": "Månedlig reisekort Oslo",
  "pricing": {
    "agreementType": "FIXED",
    "amount": 59900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 3
    }
  },
  "providerData": {
    "agreementProvider": "VIPPS"
  }
}

json

application/hal+json

Stop payment agreement

POST

https://api.entur.io/sales

/v1/payment-agreements/{agreementId}/stop

Stops a payment agreement, both at the provider and locally. The agreement must be in status PENDING or ACTIVE.

Stopping is irreversible. A stopped agreement cannot be reactivated — resuming service for the customer requires setting up a new agreement. The provider also cancels any outstanding charges on the agreement as part of the stop, so a charge that has not yet been captured will not be captured afterwards.

Any charge on the agreement that has not yet reached the provider is cancelled as part of the stop, and its transaction ends up CANCELLED. That covers the initial charge of an agreement stopped before the customer confirmed it, and a charge on an ACTIVE agreement that had been created but not yet claimed. Neither can make progress once the agreement is stopped.

The endpoint is idempotent: stopping an already STOPPED agreement returns 200 with the unchanged agreement and does not call the provider. An agreement in status CREATED or EXPIRED cannot be stopped and is rejected with 409.

The request has no body.

Stop payment agreement › path Parameters

agreementId

integer · int64 · required · style: simple

agreementId

Stop payment agreement › Headers

Entur-POS

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Entur-Distribution-Channel

string · style: simple

Distribution channel identifier.

Stop payment agreement › Responses

Response containing payment agreement details.

PaymentAgreementResponse

agreementId

integer · int64

The unique identifier of the payment agreement.

status

string · enum

The current status of the agreement.

Enum values:

CREATED

PENDING

ACTIVE

STOPPED

EXPIRED

productName

string

Name of the product or subscription.

productDescription

string

Description of the product or subscription, shown to the customer in the provider's app.

AgreementPricing

Base pricing model for a payment agreement.

AgreementResponseProviderData

Base provider-specific data in an agreement response.

Query payment agreements

GET

https://api.entur.io/sales

/v1/payment-agreements

Returns payment agreements for a given customer across all organisations the caller has access to. Optionally filter by one or more statuses.

Query payment agreements › query Parameters

customerNumber

string · required · style: form · explode: true

Customer number to query agreements for. Required.

status

string[] · style: form · explode: true

Optional. Filter by one or more agreement statuses.

Enum values:

CREATED

PENDING

ACTIVE

STOPPED

EXPIRED

Query payment agreements › Headers

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Query payment agreements › Responses

PaymentAgreementResponse[]

Response containing payment agreement details.

PaymentAgreementResponse

agreementId

integer · int64

The unique identifier of the payment agreement.

status

string · enum

The current status of the agreement.

Enum values:

CREATED

PENDING

ACTIVE

STOPPED

EXPIRED

productName

string

Name of the product or subscription.

productDescription

string

Description of the product or subscription, shown to the customer in the provider's app.

AgreementPricing

Base pricing model for a payment agreement.

AgreementResponseProviderData

Base provider-specific data in an agreement response.

Register a new payment agreement

POST

https://api.entur.io/sales

/v1/payment-agreements

Registers a payment agreement with the specified provider. For Vipps, this drafts the agreement and returns a confirmation URL to redirect the customer to.

Only FLEXIBLE pricing is currently supported. Supplying FixedPricing or VariablePricing returns 501; those agreement types are reserved for future use.

Register a new payment agreement › Headers

Entur-POS

string · required · style: simple

Point-of-sale identifier.

ET-Client-Name

string · style: simple

X-Correlation-Id

string · style: simple

Correlation id

Entur-Distribution-Channel

string · style: simple

Distribution channel identifier.

Register a new payment agreement › Request Body

Request to create a new payment agreement.

CreatePaymentAgreementRequest

productName

string · maxLength: 45 · required

Name of the product or subscription.

customerNumber

string · required

The customer number for the agreement.

AgreementPricing · required

Base pricing model for a payment agreement.

AgreementRequestProviderData · required

Base provider-specific data for creating an agreement.

productDescription

string · maxLength: 100

Optional description of the product or subscription, shown to the customer in the provider's app.

Register a new payment agreement › Responses

Created

Response containing payment agreement details.

PaymentAgreementResponse

agreementId

integer · int64

The unique identifier of the payment agreement.

status

string · enum

The current status of the agreement.

Enum values:

CREATED

PENDING

ACTIVE

STOPPED

EXPIRED

productName

string

Name of the product or subscription.

productDescription

string

Description of the product or subscription, shown to the customer in the provider's app.

AgreementPricing

Base pricing model for a payment agreement.

AgreementResponseProviderData

Base provider-specific data in an agreement response.

POST/v1/payment-agreements

curl https://api.entur.io/sales/v1/payment-agreements \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Entur-POS: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "productName": "Månedlig reisekort Oslo",
  "productDescription": "Månedlig reisekort gyldig i Oslo-sonen",
  "customerNumber": "12345678",
  "pricing": {
    "agreementType": "FIXED",
    "amount": 49900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 1
    }
  },
  "providerData": {
    "agreementProvider": "VIPPS",
    "merchantRedirectUrl": "https://entur.no/avtaler/bekreftelse",
    "merchantAgreementUrl": "https://entur.no/avtaler/123",
    "phoneNumber": "4791234567"
  }
}'

Example Request Body

{
  "productName": "Månedlig reisekort Oslo",
  "productDescription": "Månedlig reisekort gyldig i Oslo-sonen",
  "customerNumber": "12345678",
  "pricing": {
    "agreementType": "FIXED",
    "amount": 49900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 1
    }
  },
  "providerData": {
    "agreementProvider": "VIPPS",
    "merchantRedirectUrl": "https://entur.no/avtaler/bekreftelse",
    "merchantAgreementUrl": "https://entur.no/avtaler/123",
    "phoneNumber": "4791234567"
  }
}

json

application/json

Example Responses

{
  "agreementId": 42,
  "status": "PENDING",
  "productName": "Månedlig reisekort Oslo",
  "productDescription": "Månedlig reisekort gyldig i Oslo-sonen",
  "pricing": {
    "agreementType": "FIXED",
    "amount": 49900,
    "currency": "NOK",
    "interval": {
      "unit": "MONTH",
      "count": 1
    }
  },
  "providerData": {
    "agreementProvider": "VIPPS",
    "confirmationUrl": "https://api.vipps.no/dwo-api-application/v1/deeplink/vippsgateway?v=2&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9"
  }
}

json

application/hal+json

API Documentation

Did you find what you were looking for?

Payment Agreements

Get payment agreement status

Get payment agreement status › path Parameters

Get payment agreement status › Headers

Get payment agreement status › Responses

Update payment agreement

Update payment agreement › path Parameters

Update payment agreement › Headers

Update payment agreement › Request Body

Update payment agreement › Responses

Stop payment agreement

Stop payment agreement › path Parameters

Stop payment agreement › Headers

Stop payment agreement › Responses

Query payment agreements

Query payment agreements › query Parameters

Query payment agreements › Headers

Query payment agreements › Responses

Register a new payment agreement

Register a new payment agreement › Headers

Register a new payment agreement › Request Body

Register a new payment agreement › Responses

Build with Entur

Contribute

Terms & Policies