The CONNECT Payment API

The CONNECT Payment API allows you to create a single transaction or a series of transactions. We call the series of transactions a charging agreement.

Single payment

Transactions

Create transaction

POST

/transactions

Prepares a transaction so the user can complete it. The user completes the transaction at the “PAYMENT” link given in the response.

The user will be redirected to the successRedirect after the transaction is completed. If the user aborts, they will be redirected to the cancelRedirect.

Requires basic auth credentials, or OAuth access token of a CONNECT ID user. The OAuth scope required is “payment.transactions.write”.

Parameters
orderId
string (required)
Your ID for the transaction. This is used to track the transaction.

Must be unique. Maximum length is 100 characters.

Example: “4d35310c”

purchaseDescription
string (required)
A human readable description of the purchase. This is what is shown as the header in the payment information on the payment page. This will also be the information showing up on the invoice on the means of pay.

Maximum length is 1023 characters.

Example: “Purchase for Test Merchant”

amount
string (required)
The total amount to be charged together with the currency to charge it in.

Format: “CUR AMOUNT” where CUR is the ISO4217 currency code of the currency and AMOUNT is the amount written as a decimal number.

Example: “USD 18.14”

vatRate
string (required)
The VAT percentage for the transaction as a decimal number.

Example: “0.10” is the rate for 10% VAT

successRedirect
string (required)
Where the customer is redirected after they successfully got charged.

Maximum length is 145 characters.

Example: "http://example.com/receipt/4d35310c"

cancelRedirect
string (required)
Where the customer is redirected when they cancel the payment flow. This should be where the user came from.

Maximum length is 145 characters.

Example: "http://example.com/products"

products
list (optional)
A list of the products being purchased. If you choose to have this list of products it must be complete and the sum of the prices must match the amount and the average VAT percentage must match the vatRate given in this object.
- name (string, required) -
  
  The name of the product. This will be in the list below the purchaseDescription field on the payment page for the user.
  
  Maximum length is 145 characters.
  
  Example: “White unicorn”
- price (string, required) -
  
  The price of the product in the same format as amount above.
  
  Example: “USD 18.14”
- vatRate (string, optional) -
  
  The VAT percentage of the product.
  
  Example: “0.10” is the rate for 10% VAT
- sku (string, optional) -
  
  The stock keeping unit id used to identify the product in the rights system.
  
  Use this if you want us to grant rights for your users automatically when the purchase is done. If you use a sku a timeSpec is also required.
  
  Maximum length is 145 characters.
  
  Example: “CMO-EXM-2-M”
- timeSpec (string, optional) -
  
  The ISO8601 duration of the right generated by the sku
  
  Example: “P1M2D” will make the right valid for 1 month and 2 days after the purchase went through.

RequestShowHide

Headers

Content-Type: application/json
Authorization: Bearer <access token>
Accept: application/json

Body

{
  "orderId": "4d35310c",
  "purchaseDescription": "Purchase for TestMerchant",
  "amount": "USD 99.98",
  "vatRate": "0.10",
  "successRedirect": "http://example.com/receipt/4d35310c",
  "cancelRedirect": "http://example.com/products",
  "products": [
    {
      "name": "Red Unicorn",
      "price": "USD 49.99",
      "vatRate": "0.10"
    },
    {
      "name": "Blue Unicorn",
      "price": "USD 49.99",
      "vatRate": "0.10"
    }
  ]
}

Response 201ShowHide

Headers

Content-Type: application/json
Location: https://payment.telenordigital.com/transactions/wYRR_DeITSuqGwiG7JsTPA

Body

{
  "orderId": "4d35310c",
  "purchaseDescription": "Purchase for TestMerchant",
  "amount": "USD 99.98",
  "vatRate": "0.10",
  "successRedirect": "http://example.com/receipt/4d35310c",
  "cancelRedirect": "http://example.com/products",
  "connectId": "584xxxx72",
  "allowedPaymentMethods": null,
  "products": [
    {
      "name": "Red Unicorn",
      "price": "USD 49.99",
      "vatRate": "0.10"
    },
    {
      "name": "Blue Unicorn",
      "price": "USD 49.99",
      "vatRate": "0.10"
    }
  ],
  "vatAmount": "USD 9.99",
  "id": "wYRR_DeITSuqGwiG7JsTPA",
  "startTime": "2010-01-02T03:05:06.000Z",
  "state": "STARTED",
  "chargedPaymentMethod": "NOT_SELECTED",
  "chargingAgreement": null,
  "previousTransactionId": null,
  "links": [
    {
      "rel": "PAYMENT",
      "href": "https://payment.telenordigital.com/transactions/wYRR_DeITSuqGwiG7JsTPA"
    }
  ],
  "type": "CHARGE"
}

Response 400ShowHide

If the request entity has errors.

Headers

Content-Type: application/json

Body

{
    "errorNamespace" : "telenordigital.payment",
    "errorCode" : {code},
    "errorMessage" : {message}
}

Response 401ShowHide

If the user is unauthorized.

Headers

Content-Type: application/json

Body

{
  "errorNamespace": "null",
  "errorCode": null,
  "errorMessage": "Unauthorized access"
}

Response 402ShowHide
If the request is malformed.

Headers
```
Content-Type: application/json
```
Response 403ShowHide

Body

If you do not have the correct credentials. This can be one of the following errors:

- The OAuth token was not provided properly.
- The OAuth token could not be validated.
- The OAuth token had the wrong scope for this user.
- Basic auth credentials were incorrect.
- Basic auth credentials did not have the privileges to access this endpoint.

Response 500ShowHide

Headers

Content-Type: application/json

Body

{
    "errorNamespace" : "telenordigital.payment",
    "errorCode" : {code},
    "errorMessage" : {message}
}

Get transactions

GET

/transactions

Get all transactions filtered by the parameters.

Example: /transactions?connectId=123456789&type=CHARGE&orderId=4d35310c&limit=3&offset=0

Parameters
connectId
string (optional)
The CONNECT ID of the user that owns this transaction.

state
string (optional)
Filter Transactions based on state. Example: state=COMPLETED.

Allowed values are:
- STARTED
- FAILED
- VERIFICATION_FAILED
- COMPLETED
- FAILED_RETRIABLE
orderId
string (optional)
Your ID for the transaction.

type
string (optional)
Filter Transactions based on type.

Allowed values are:
- CHARGE
- VERIFY
- REFUND
- PAY4ME
chargeToken
string (optional)
String representation of ChargeToken.

remoteTransactionId
string (optional)
Id provided by the payment method when performing a charge.

latestOnly
boolean (optional)
If set to true, this will only return latest transaction. Example: latestOnly=true

sort
string (optional)
Sort direction; Will return newest first if set to “desc”.

limit
int (optional)
Number of elements to return (defaults to 50).

offset
int (optional)
offset into dataset to return elements from (defaults to 0)

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Response 200ShowHide

Headers

Content-Type: application/json

Body

[
  { ... transaction ... }, { ... transaction ... }
]

Response 400ShowHide

Headers

Content-Type: application/json

Body

connectId or chargeToken must be given to this method

Response 401ShowHide

If the user is unauthorized.

Headers

Content-Type: application/json

Body

{
  "errorNamespace": "null",
  "errorCode": null,
  "errorMessage": "Unauthorized access"
}

Response 403ShowHide

Body

If you do not have the credentials to access this endpoint.

Response 500ShowHide

Headers

Content-Type: application/json

Body

{
    "errorNamespace" : "telenordigital.payment",
    "errorCode" : {code},
    "errorMessage" : {message}
}

Transaction by transactionId

Get payment flow (http) [GET]

The end user should be redirected here to complete the transaction. The “PAYMENT” link in the links section of the transaction points here.

Response 200 (text/html)
- Header
- Body
```
The first page of the payment flow.
```
Response 403 If you do not have the credentials to access this endpoint.

Get transaction

GET

/transactions/{transactionId}

Get the transaction based on the transactionId.

Requires OAuth scope value “payment.transactions.read”.

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Response 200ShowHide

Headers

Content-Type: application/json
Location: https://payment.telenordigital.com/transactions/wYRR_DeITSuqGwiG7JsTPA

Body

{
  "orderId": "4d35310c",
  "purchaseDescription": "Purchase for TestMerchant",
  "amount": "USD 99.98",
  "vatRate": "0.10",
  "successRedirect": "http://example.com/receipt/4d35310c",
  "cancelRedirect": "http://example.com/products",
  "connectId": "584xxxx72",
  "allowedPaymentMethods": null,
  "products": [
    {
      "name": "Red Unicorn",
      "price": "USD 49.99",
      "vatRate": "0.10"
    },
    {
      "name": "Blue Unicorn",
      "price": "USD 49.99",
      "vatRate": "0.10"
    }
  ],
  "vatAmount": "USD 9.99",
  "id": "wYRR_DeITSuqGwiG7JsTPA",
  "startTime": "2010-01-02T03:05:06.000Z",
  "state": "STARTED",
  "chargedPaymentMethod": "NOT_SELECTED",
  "chargingAgreement": null,
  "previousTransactionId": null,
  "links": [
    {
      "rel": "PAYMENT",
      "href": "https://payment.telenordigital.com/transactions/wYRR_DeITSuqGwiG7JsTPA"
    }
  ],
  "type": "CHARGE"
}

Response 401ShowHide

If the user is unauthorized.

Headers

Content-Type: application/json

Body

{
  "errorNamespace": "null",
  "errorCode": null,
  "errorMessage": "Unauthorized access"
}

Response 403ShowHide

Body

If you do not have the credentials to access this endpoint.

Refunds

Refund transaction

POST

/transactions/{transactionId}/refunds

Issue a refund for a transaction based on the transactionId.

Requires HTTP Basic Auth or OAuth scope value “payment.transactions.write”.

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Body

{
  "refundIssuer": "refundissuer@example.com",
  "refundReason": "Reason for issuing refund."
}

Response 200ShowHide

A new Refund Transaction will be returned, referencing the transactionId of the refunded transaction.

Refunds do not work for Direct Operator Billing (DOB) transactions.

Headers

Content-Type: application/json

Body

{
        "amount": "NOK 1.00",
        "orderId": "RefundExample",
        "purchaseDescription": "Unlimited Access to Refunds",
        "successRedirect": "http://example.com/success",
        "cancelRedirect": "http://example.com/cancel",
        "merchantName": "friendly_merchant",
        "allowedPaymentMethods": [],
        "products": [],
        "id": "xYRR_DeITSuqGwiG7JsXXX",
        "startTime": "2017-08-28T11:26:15.229Z",
        "state": "COMPLETED",
        "returnCode": "OK",
        "chargedPaymentMethod": "CREDIT_CARD",
        "completedTime": "2017-08-28T11:26:16.363Z",
        "sourceOfFundsCode": "CREDIT_CARD_PROCESSOR",
        "refundReason": "Reason for issuing refund.",
        "refundIssuer": "refundissuer@example.com",
        "refundForTransactionId": "wYRR_DeITSuqGwiG7JsTPA",
        "type": "REFUND",
        "paymentInstrument": {
            "id": "flIuusz4Qp233_333333fA",
            "paymentInstrumentInfo": {
                "type": "CARD_ISSUER",
                "first6": "424242",
                "last4": "4242",
                "expiryYear": "2017",
                "expiryMonth": "08",
                "name": "My Card"
            },
            "paymentMethod": "CREDIT_CARD",
        }
    }

Recurring payment

Charging agreements

A charging agreement describes a recurring payment. It contains a transaction and information about how often this payment should be performed.

To check if a charging agreement is active and valid look for “hasActiveRight”: true on Get Transaction by ID.

Prepare Charging agreement

POST

/agreements

Create a recurring transaction. The user completes the transaction and activates the agreement at the “PAYMENT” link given in the response.

When the charging agreement is created it will be in the state “CREATED”. When the user has started the payment process it will be set to “PENDING_VERIFICATION”. When the user has payed, it will be set to “ACTIVE”.

Requires basic auth credentials, or OAuth access token of a CONNECT ID user. The OAuth scope required is “payment.agreements.write”.

Parameters
connectId
string (optional)
Must be unique. Required if not using basic auth.

The CONNECT ID of the only user who can activate this charging agreement.

recurrenceTimeSpec
string (required)
ISO8601 repeating intervals specifying when the products will be charged for. If it starts in the past, it will be adjusted to start now.

Examples:
- R/P1M (Monthly payment, starting now)
- R/2041-01-02/P1W (Weekly payment, starting 2. january 2041)
- R/1999-01-01/P1Y (Yearly payment set to start in the past, will be adjusted to start now)
verificationTransaction
object (required)
The transaction object that will be charged when payment is due. This object is the same as used for single payment.

trial.period
string (optional)
ISO8601 duration of a trial period. This makes the charging agreement start with a free trial period.

The first transaction will not charge, but only verify the payment instrument. When it is verified, the rights to the products are granted. They will start when the recurrenceTimeSpec starts. Then the recurrenceTimeSpec is moved so that charging starts when the trial period is over.

RequestShowHide

Headers

Content-Type: application/json
Authorization: Bearer <access token>
Accept: application/json

Body

{
  "connectId": "584xxxx72",
  "recurrenceTimeSpec": "R/P1M",
  "verificationTransaction": {
    "orderId": "4d35310c",
    "purchaseDescription": "Unlimited Access to Something",
    "amount": "USD 49.99",
    "vatRate": "0.10",
    "successRedirect": "https://example.com/receipt/4d35310c",
    "cancelRedirect": "https://example.com/products",
    "products": [
      {
        "name": "Red Unicorn",
        "price": "USD 49.99",
        "vatRate": "0.10",
        "sku": "CMO-UNI-1-R",
        "timeSpec": "P1M"
      }
    ]
  },
  "trial": {
    "period": "P1M"
  }
}

Response 201ShowHide

Headers

Content-Type: application/json
Location: https://payment.telenordigital.com/agreements/zU314qSETx-B3fUszBzssg

Body

{
  "id": "zU314qSETx-B3fUszBzssg",
  "verificationTransaction": {
    "amount": "NOK 1.00",
    "vatRate": 0.1,
    "orderId": "4d35310c",
    "purchaseDescription": "Unlimited Access to Something",
    "successRedirect": "https://example.com/receipt/4d35310c",
    "cancelRedirect": "https://example.com/products",
    "merchantName": "our-id-of-your-service",
    "connectId": "5986421484631891968",
    "chargingAgreementId": "zU314qSETx-B3fUszBzssg",
    "products": [
      {
        "name": "Red Unicorn",
        "price": "USD 49.99",
        "vatRate": "0.10",
        "sku": "CMO-UNI-1-R",
        "timeSpec": "P1M"
      }
    ],
    "allowedPaymentMethods": null,
    "id": "Dy-WcDx8T2iCMCy5RAdRqQ",
    "vatAmount": "NOK 0.09",
    "startTime": "2015-04-21T12:07:34.285Z",
    "state": "STARTED",
    "returnCode": null,
    "chargedPaymentMethod": "NOT_SELECTED",
    "previousTransactionId": null,
    "links": null,
    "completedTime": null,
    "sourceOfFundsId": null
  },
  "generation": "TV3gZTuiS8CBvh5ywVTBtQ",
  "state": "CREATED",
  "links": [
    {
      "rel": "PAYMENT",
      "href": "https://payment.telenordigital.com/transactions/Dy-WcDx8T2iCMCy5RAdRqQ"
    }
  ],
  "creationTime": "2015-04-21T12:07:34.284Z",
  "merchantName": "our-id-of-your-service",
  "verificationTransactionId": "Dy-WcDx8T2iCMCy5RAdRqQ",
  "connectId": "5986421484631891968",
  "recurrenceTimeSpec": "R/2015-05-21T12:07:34.284Z/P1M",
  "paymentMethod": null,
  "paymentMethodId": null,
  "trial": {
    "period": "P1W"
  },
  "hasActiveRight": false
}

Response 400ShowHide

If the request entity has errors.

Headers

Content-Type: application/json

Body

{
    "errorNamespace" : "telenordigital.payment",
    "errorCode" : {code},
    "errorMessage" : {message}
}

Response 401ShowHide

If the user is unauthorized.

Headers

Content-Type: application/json

Body

{
  "errorNamespace": "null",
  "errorCode": null,
  "errorMessage": "Unauthorized access"
}

Response 402ShowHide
If the request is malformed.

Headers
```
Content-Type: application/json
```
Response 403ShowHide

Body

If you do not have the correct credentials. This can be one of the following errors:

- The OAuth token was not provided properly.
- The OAuth token could not be validated.
- The OAuth token had the wrong scope for this user.
- Basic auth credentials were incorrect.
- Basic auth credentials did not have the privileges to access this endpoint.

Response 500ShowHide

Headers

Content-Type: application/json

Body

{
    "errorNamespace" : "telenordigital.payment",
    "errorCode" : {code},
    "errorMessage" : {message}
}

Get charging agreements

GET

/agreements

Get all transactions filtered by the parameters.

Example: /agreements?connectId=123456789&state=ACTIVE

Requires OAuth scope value “payment.agreements.read”.

RequestShowHide

Headers

Authorization: Bearer <access token>
Accept: application/json

Response 200ShowHide

Headers

Content-Type: application/json

Body

[
  { ... charging agreement ... }, { ... charging agreement ... }
]

Response 400ShowHide

Headers

Content-Type: application/json

Body

connectId cannot be null

Response 401ShowHide

If the user is unauthorized.

Headers

Content-Type: application/json

Body

{
  "errorNamespace": "null",
  "errorCode": null,
  "errorMessage": "Unauthorized access"
}

Response 403ShowHide

Body

If you do not have the credentials to access this endpoint.

Charging agreement by ID

Get charging agreement

GET

/agreements/{id}

Get Charging Agreement by ID.

Requires OAuth scope value “payment.agreements.read”.

RequestShowHide

Headers

Authorization: Bearer <access token>
Accept: application/json

Response 200ShowHide

Headers

Content-Type: application/json
Location: https://payment.telenordigital.com/agreements/zU314qSETx-B3fUszBzssg

Body

{
  "id": "zU314qSETx-B3fUszBzssg",
  "verificationTransaction": {
    "amount": "NOK 1.00",
    "vatRate": 0.1,
    "orderId": "4d35310c",
    "purchaseDescription": "Unlimited Access to Something",
    "successRedirect": "https://example.com/receipt/4d35310c",
    "cancelRedirect": "https://example.com/products",
    "merchantName": "our-id-of-your-service",
    "connectId": "5986421484631891968",
    "chargingAgreementId": "zU314qSETx-B3fUszBzssg",
    "products": [
      {
        "name": "Red Unicorn",
        "price": "USD 49.99",
        "vatRate": "0.10",
        "sku": "CMO-UNI-1-R",
        "timeSpec": "P1M"
      }
    ],
    "allowedPaymentMethods": null,
    "id": "Dy-WcDx8T2iCMCy5RAdRqQ",
    "vatAmount": "NOK 0.09",
    "startTime": "2015-04-21T12:07:34.285Z",
    "state": "STARTED",
    "returnCode": null,
    "chargedPaymentMethod": "NOT_SELECTED",
    "previousTransactionId": null,
    "links": null,
    "completedTime": null,
    "sourceOfFundsId": null
  },
  "generation": "TV3gZTuiS8CBvh5ywVTBtQ",
  "state": "CREATED",
  "links": [
    {
      "rel": "PAYMENT",
      "href": "https://payment.telenordigital.com/transactions/Dy-WcDx8T2iCMCy5RAdRqQ"
    }
  ],
  "creationTime": "2015-04-21T12:07:34.284Z",
  "merchantName": "our-id-of-your-service",
  "verificationTransactionId": "Dy-WcDx8T2iCMCy5RAdRqQ",
  "connectId": "5986421484631891968",
  "recurrenceTimeSpec": "R/2015-05-21T12:07:34.284Z/P1M",
  "paymentMethod": null,
  "paymentMethodId": null,
  "trial": {
    "period": "P1W"
  },
  "hasActiveRight": false
}

Response 401ShowHide

If the user is unauthorized.

Headers

Content-Type: application/json

Body

{
  "errorNamespace": "null",
  "errorCode": null,
  "errorMessage": "Unauthorized access"
}

Response 403ShowHide

Body

If you do not have the credentials to access this endpoint.

Stop charging agreement

POST

/agreements/{id}/stop

This will remove the subscription of this charging agreement. The charging agreement state becomes STOPPED. Generated rights are not affected, but no new rights will be generated by this agreement.

Response 200ShowHide

Stopped charging agreement.

Headers

Content-Type: application/json

Body

{
  "id": "fMnTBWJMQ6yKMis2DQ4QNA",
  "verificationTransaction": {
    "amount": "NOK 1.00",
    "vatRate": 0.10,
    "orderId": "4d35310c",
    "purchaseDescription": "Unlimited Access to Something",
    "successRedirect": "https://example.com/receipt/4d35310c",
    "cancelRedirect": "https://example.com/webshop",
    "merchantName": "our-id-of-your-service",
    "connectId": "584xxxx72",
    "chargingAgreementId": "fMnTBWJMQ6yKMis2DQ4QNA",
    "products": [
      {
        "name": "Red Unicorn",
        "price": "USD 49.99",
        "vatRate": "0.10",
        "sku": "CMO-UNI-1-R",
        "timeSpec": "P1M"
      }
    ],
    "id": "5dOJ-ER6SlyHlh1Wd1W8QQ",
    "vatAmount": "NOK 0.10",
    "startTime": "2015-01-13T15:05:56.000Z",
    "state": "COMPLETED",
    "chargedPaymentMethod": "CREDIT_CARD"
  },
  "generation": "2iMFH1XuTSqrUY9UW0aoiQ",
  "state": "STOPPED",
  "links": [
    {
      "rel": "PAYMENT",
      "href": "https://payment.telenordigital.com/transactions/5dOJ-ER6SlyHlh1Wd1W8QQ"
    }
  ],
  "creationTime": "2015-01-13T15:05:55.000Z",
  "merchantName": "our-id-of-your-service",
  "verificationTransactionId": "5dOJ-ER6SlyHlh1Wd1W8QQ",
  "connectId": "584xxxx72",
  "recurrenceTimeSpec": "R/2015-01-10/P1M",
}

Response 401ShowHide

Headers

Content-Type: application/json

Body

If the user is unauthorized.

Response 403ShowHide

Body

If you do not have the credentials to access this endpoint.

Single payment

Transactions

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body

Transaction by transactionId

Get payment flow (http) [GET] ¶

Headers

Headers

Body

Headers

Body

Body

Refunds

Headers

Body

Headers

Body

Recurring payment

Charging agreements

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Headers

Body

Headers

Body

Headers

Body

Body

Charging agreement by ID

Headers

Headers

Body

Headers

Body

Body

Stop charging agreement

Headers

Body

Headers

Body

Body

Get payment flow (http) [GET]