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

  • Request
  • 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  201
  • 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  400
  • If the request entity has errors.

    Headers
    Content-Type: application/json
    Body
    {
        "errorNamespace" : "telenordigital.payment",
        "errorCode" : {code},
        "errorMessage" : {message}
    }
  • Response  401
  • If the user is unauthorized.

    Headers
    Content-Type: application/json
    Body
    {
      "errorNamespace": "null",
      "errorCode": null,
      "errorMessage": "Unauthorized access"
    }
  • Response  402
  • If the request is malformed.

    Headers
    Content-Type: application/json
  • Response  403
  • 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  500
  • Headers
    Content-Type: application/json
    Body
    {
        "errorNamespace" : "telenordigital.payment",
        "errorCode" : {code},
        "errorMessage" : {message}
    }
Get transactions
/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)

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
      { ... transaction ... }, { ... transaction ... }
    ]
    
  • Response  400
  • Headers
    Content-Type: application/json
    Body
    connectId or chargeToken must be given to this method
    
  • Response  401
  • If the user is unauthorized.

    Headers
    Content-Type: application/json
    Body
    {
      "errorNamespace": "null",
      "errorCode": null,
      "errorMessage": "Unauthorized access"
    }
  • Response  403
  • Body
    If you do not have the credentials to access this endpoint.
  • Response  500
  • 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
/transactions/{transactionId}

Get the transaction based on the transactionId.

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

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • 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  401
  • If the user is unauthorized.

    Headers
    Content-Type: application/json
    Body
    {
      "errorNamespace": "null",
      "errorCode": null,
      "errorMessage": "Unauthorized access"
    }
  • Response  403
  • Body
    If you do not have the credentials to access this endpoint.

Refunds 

Refund transaction
/transactions/{transactionId}/refunds

Issue a refund for a transaction based on the transactionId.

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

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
    Body
    {
      "refundIssuer": "refundissuer@example.com",
      "refundReason": "Reason for issuing refund."
    }
  • Response  200
  • 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
/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.

  • Request
  • 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  201
  • 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  400
  • If the request entity has errors.

    Headers
    Content-Type: application/json
    Body
    {
        "errorNamespace" : "telenordigital.payment",
        "errorCode" : {code},
        "errorMessage" : {message}
    }
  • Response  401
  • If the user is unauthorized.

    Headers
    Content-Type: application/json
    Body
    {
      "errorNamespace": "null",
      "errorCode": null,
      "errorMessage": "Unauthorized access"
    }
  • Response  402
  • If the request is malformed.

    Headers
    Content-Type: application/json
  • Response  403
  • 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  500
  • Headers
    Content-Type: application/json
    Body
    {
        "errorNamespace" : "telenordigital.payment",
        "errorCode" : {code},
        "errorMessage" : {message}
    }
Get charging agreements
/agreements

Get all transactions filtered by the parameters.

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

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

  • Request
  • Headers
    Authorization: Bearer <access token>
    Accept: application/json
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
      { ... charging agreement ... }, { ... charging agreement ... }
    ]
    
  • Response  400
  • Headers
    Content-Type: application/json
    Body
    connectId cannot be null
  • Response  401
  • If the user is unauthorized.

    Headers
    Content-Type: application/json
    Body
    {
      "errorNamespace": "null",
      "errorCode": null,
      "errorMessage": "Unauthorized access"
    }
  • Response  403
  • Body
    If you do not have the credentials to access this endpoint.

Charging agreement by ID 

Get charging agreement
/agreements/{id}

Get Charging Agreement by ID.

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

  • Request
  • Headers
    Authorization: Bearer <access token>
    Accept: application/json
  • Response  200
  • 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  401
  • If the user is unauthorized.

    Headers
    Content-Type: application/json
    Body
    {
      "errorNamespace": "null",
      "errorCode": null,
      "errorMessage": "Unauthorized access"
    }
  • Response  403
  • Body
    If you do not have the credentials to access this endpoint.

Stop charging agreement 

Stop charging agreement
/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  200
  • 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  401
  • Headers
    Content-Type: application/json
    Body
    If the user is unauthorized.
  • Response  403
  • Body
    If you do not have the credentials to access this endpoint.

© 2017 Telenor Digital AS