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.
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/jsonBody
{ "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
ShowHide Headers
Content-Type: application/json
Location: https://payment.telenordigital.com/transactions/wYRR_DeITSuqGwiG7JsTPABody
{ "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
ShowHide If the request entity has errors.
Headers
Content-Type: application/json
Body
{ "errorNamespace" : "telenordigital.payment", "errorCode" : {code}, "errorMessage" : {message} }
- Response
401
ShowHide If the user is unauthorized.
Headers
Content-Type: application/json
Body
{ "errorNamespace": "null", "errorCode": null, "errorMessage": "Unauthorized access" }
- Response
402
ShowHide If the request is malformed.
Headers
Content-Type: application/json
- Response
403
ShowHide 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
ShowHide Headers
Content-Type: application/json
Body
{ "errorNamespace" : "telenordigital.payment", "errorCode" : {code}, "errorMessage" : {message} }
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
200
ShowHide Headers
Content-Type: application/json
Body
[ { ... transaction ... }, { ... transaction ... } ]
- Response
400
ShowHide Headers
Content-Type: application/json
Body
connectId or chargeToken must be given to this method
- Response
401
ShowHide If the user is unauthorized.
Headers
Content-Type: application/json
Body
{ "errorNamespace": "null", "errorCode": null, "errorMessage": "Unauthorized access" }
- Response
403
ShowHide Body
If you do not have the credentials to access this endpoint.
- Response
500
ShowHide 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 the transaction based on the transactionId.
Requires OAuth scope value “payment.transactions.read”.
- RequestShowHide
Headers
Accept: application/json
Authorization: Bearer <access token>- Response
200
ShowHide Headers
Content-Type: application/json
Location: https://payment.telenordigital.com/transactions/wYRR_DeITSuqGwiG7JsTPABody
{ "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
ShowHide If the user is unauthorized.
Headers
Content-Type: application/json
Body
{ "errorNamespace": "null", "errorCode": null, "errorMessage": "Unauthorized access" }
- Response
403
ShowHide Body
If you do not have the credentials to access this endpoint.
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
200
ShowHide 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", } }
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.
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/jsonBody
{ "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
ShowHide Headers
Content-Type: application/json
Location: https://payment.telenordigital.com/agreements/zU314qSETx-B3fUszBzssgBody
{ "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
ShowHide If the request entity has errors.
Headers
Content-Type: application/json
Body
{ "errorNamespace" : "telenordigital.payment", "errorCode" : {code}, "errorMessage" : {message} }
- Response
401
ShowHide If the user is unauthorized.
Headers
Content-Type: application/json
Body
{ "errorNamespace": "null", "errorCode": null, "errorMessage": "Unauthorized access" }
- Response
402
ShowHide If the request is malformed.
Headers
Content-Type: application/json
- Response
403
ShowHide 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
ShowHide Headers
Content-Type: application/json
Body
{ "errorNamespace" : "telenordigital.payment", "errorCode" : {code}, "errorMessage" : {message} }
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
200
ShowHide Headers
Content-Type: application/json
Body
[ { ... charging agreement ... }, { ... charging agreement ... } ]
- Response
400
ShowHide Headers
Content-Type: application/json
Body
connectId cannot be null
- Response
401
ShowHide If the user is unauthorized.
Headers
Content-Type: application/json
Body
{ "errorNamespace": "null", "errorCode": null, "errorMessage": "Unauthorized access" }
- Response
403
ShowHide Body
If you do not have the credentials to access this endpoint.
Charging agreement by ID
Get Charging Agreement by ID.
Requires OAuth scope value “payment.agreements.read”.
- RequestShowHide
Headers
Authorization: Bearer <access token>
Accept: application/json- Response
200
ShowHide Headers
Content-Type: application/json
Location: https://payment.telenordigital.com/agreements/zU314qSETx-B3fUszBzssgBody
{ "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
ShowHide If the user is unauthorized.
Headers
Content-Type: application/json
Body
{ "errorNamespace": "null", "errorCode": null, "errorMessage": "Unauthorized access" }
- Response
403
ShowHide Body
If you do not have the credentials to access this endpoint.
Stop charging agreement
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
ShowHide 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
ShowHide Headers
Content-Type: application/json
Body
If the user is unauthorized.
- Response
403
ShowHide Body
If you do not have the credentials to access this endpoint.