How may we help?

Welcome to the support universe of OnlineFundraising where you will find help and guidance through our articles and videos. Please have a look and use the search function as needed. You are always welcome to contact our support in case there are any questions left unanswered.

Payment Session Handler API

Payment Session Handler API

Senest redigeret:

A uniform checkout flow

The following diagram describes the uniform checkout sequence for all payment gateways:

Payment_Session_Handler.png

 

Initial options of a Payment Session

Please also see our documentation of DataSet API.
Please note the Payment Session Handler is authorised by the Payment Engine API key.

Name

Type

Mandatory

Example

Description

paymentMethodType

STRING

YES

Test, Betalingsservice, MobilePayOnline, MobilePaySubscriptions, Card

Definition of how payment will be made.
Test is a SMS based solution for testing various outcomes.

paymentType

STRING

YES

Recurring, OneOff, Single

Definition of whether payment is recurring, single or a combination (OneOff).

amount

DOUBLE

YES

100.0

Amount charged

taxDeductable

BOOLEAN

NO

true

Provided for Single payments to mark payment taxDeductable

oneOffAmount

DOUBLE

(YES)

100.0

Amount charged. Required if paymentMethodType is OneOff.

currencyCode

STRING

YES

DKK

ISO formatted Currency Code (wiki)

purposeAccountingCode

STRING(32)

NO

 

A code that identifies the purpose of this agreement, with respect to accounting.

plan

STRING(30)

(YES)

 

Mandatory for MobilePay Subscriptions. Appears in MobilePay Subscriptions

description

STRING(60)

NO

 

Appears in MobilePay Subscriptions

oneOffDescription

STRING

NO

 

Optional for MobilePay Subscriptions

nextPaymentDate

STRING

NO

2021-09-23

Opitonal for mobilePay Subscription. Format must be yyyy-MM-dd.

msisdn

STRING

(YES)

4535294855

Phone with Country Code (wiki on Country Code) with 1-3 digits reserved for country code without prefixes, such as 00 (wiki on MSISDN). Required by MobilePay Subscriptions and optional for Betalingsservice.

cpr

STRING

(YES)

0101601234

National ID. Required by Betalingsservice, if individual.

cvr

STRING

(YES)

37273457

Business code, i.e. VAT number. Required by Betalingsservice, if business.

sortCode

STRING

(YES)

1234

Sort code for bank account. Required by Betalingsservice

accountNumber

STRING

(YES)

1234567890

Account number for bank account. Required by Betalingsservice

frequency

STRING

(YES)

Yearly, Halfyearly, Quarterly, Monthly, Custom

Required by MobilePay Subscriptions

communicationCollectionGuid

STRING(64)

NO 

 

Unique Guid of existing Communication. Please see Communication documentation.

dataSetGuid

STRING(64)

NO

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

Unique Guid of existing DataSet. Please see DataSet documentation.

contact

OBJECT

NO

 

Please see Contact documentation for properties

agreement

OBJECT

(YES)

 

Please see Agreement documentation for properties.

Required if paymentMethodType is Recurring or OneOff.

subscription

OBJECT

(YES)

 

Please see Subscription documentation for properties.

Required if paymentMethodType is Recurring or OneOff.

errorReturnPageUrl

STRING

YES

https://domain.tld/error.html

Final Page URL for failed checkout sequence

successReturnPageUrl

STRING

YES

https://domain.tld/thanks.html

Final Page URL for successful checkout sequence

 

Advanced options of a Payment Session

The following are optional, but allows a customised checkout flow between your application, the chosen payment gateway and the receipt's landing page.

Name

Type

Mandatory

Example

Description

preWaitPageUrl

STRING

NO

https://domain.tld/preWait.html

URL for user interception before Gateway Landing Page.
The contents of preWaitPage given below.

postWaitPageUrl

STRING

NO

https://domain.tld/postWait.html

URL for user interception after Gateway Landing Page.
The contents of postWaitPage given below.

Endpoints

GET /paymentSession/{paymentSessionGuid}

Get a single Payment Session.

Response

HTTP

Description

200

OK

404

Payment not found

HTTP 200 Example of a processed Payment Session

{
  "paymentSessionGuid": "a2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "createdTs": "2019-08-16 15:26:49 +0200",
  "state": "Complete",
  "initialUserRedirectUrl": "https://domain.tld/preWait.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "redirectToGatewayUrl": "https://epay.onlinefundraising.dk/ToGatewayRedirect?sessionGuid\u003d2fbba6f6-021b-4b92-b3d5-xxxxxxxxxxxx",
  "redirectReturnFromGatewayUrl": "https://domain.tld/postWait.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "finalRedirectUrl": "https://domain.tld/tak.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "finalRedirectUrl": "https://domain.tld/error.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "dataSetGuid": "9cacc900-cc06-4447-bc0f-xxxxxxxxxxxx",
  "paymentGatewayPaymentReferenceId": "d38fd4fa-8561-4296-9b82-xxxxxxxxxxxx",
  "paymentGatewayTransactionId": "224841XXX",
  "contactGuidResult": "8d51dff8-c12b-4949-bc24-xxxxxxxxxxxx",
  "paymentMethodGuidResult": "162e7168-0d0f-4367-8804-xxxxxxxxxxxx",
  "paymentGuidResult": "66620d86-bf43-4a75-b2d6-xxxxxxxxxxxx"
}

POST /paymentSession

Initiate a Payment Session.

Request examples

A single payment of 100 DKK paid by Card, including a DataSet reference and a new Contact.

{
  "contact": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "address": "St. Kongensgade 59B, 3.",
    "postCode": "1264",
    "city": "K\u00f8benhavn",
    "countryCode": "DK",
    "msisdn": "4511223344",
    "email": "noreply@yourdomain.tld"
  },
  "paymentMethodType": "Card",
  "paymentType": "Single",
  "amount": 100.0,
  "currencyCode": "DKK",
  "taxDeductable": true,
  "dataSetGuid": "003705cc-42c8-4250-a666-xxxxxxxxxxxx",
  "communicationCollectionGuid": "18c281b2-2efe-4765-8dc0-xxxxxxxxxxxx",
  "preWaitPageUrl": "https://domain.tld/preWait.html",
  "postWaitPageUrl": "https://domain.tld/postWait.html",
  "errorReturnPageUrl": "https://domain.tld/error.html",
  "successReturnPageUrl": "https://domain.tld/thanks.html"
}

 

A subscription of a personal monthly Agreement of 50 DKK paid by Card, starting on 2023-09-01, including a DataSet reference and a new Contact.

{
  "contact": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "address": "St. Kongensgade 59B, 3.",
    "postCode": "1264",
    "city": "K\u00f8benhavn",
    "countryCode": "DK",
    "msisdn": "4511223344",
    "email": "noreply@yourdomain.tld"
  },
  "agreement": {
    "name": "Membership",
    "description": "Membership of the club",
    "agreementType": "Personal",
    "defaultQuantity": 1,
    "unit": "pcs",
    "unitPrice": 50.0,
    "amount": 50.0,
    "amountVat": 0.0,
    "amountTotal": 50.0,
    "taxDeductable": true,
    "vatPercentage": 0.0,
    "currencyCode": "DKK",
    "paymentRequired": false,
    "scheduleType": "Monthly",
    "scheduleBaseTier": 9,
    "scheduleFixedDay": 1,
    "scheduleEveryOther": 1,
    "scheduleCalendarUnit": "Month",
    "purposeAccountingCode": "test",
    "dataSetGuid": "351b0f2d-07fb-4e85-a033-xxxxxxxxxxxx",
    "communicationCollectionGuid": "93383565-801a-4dce-992f-xxxxxxxxxxxx"
  },
  "subscription": {
    "quantity": 1,
    "dataSetGuid": "351b0f2d-07fb-4e85-a033-xxxxxxxxxxxx",
    "startDate": "2023-09-01"
  },
  "paymentMethodType": "Card",
  "paymentType": "Recurring",
  "currencyCode": "DKK",
  "frequency": "Monthly",
  "plan": "Donation",
  "description": "Donation to the club",
  "dataSetGuid": "e945a145-3fc2-469e-a3ff-xxxxxxxxxxxx",
  "communicationCollectionGuid": "18c281b2-2efe-4765-8dc0-xxxxxxxxxxxx",
  "preWaitPageUrl": "https://domain.tld/preWait.html",
  "postWaitPageUrl": "https://domain.tld/postWait.html",
  "errorReturnPageUrl": "https://domain.tld/error.html",
  "successReturnPageUrl": "https://domain.tld/thanks.html"
}

 

A subscription of a personal monthly Agreement of 50 DKK, with a OneOff payment of 250 DKK, paid by MobilePay Subscriptions, starting on 2023-07-01:

{
  "contact": {
    "name": "xxx",
    "address": "xxx",
    "postCode": "xxx",
    "city": "xxx",
    "countryCode": "xxx",
    "msisdn": "xxx"
  },
  "agreement": {
    "name": "Membership",
    "description": "Membership of the club",
    "agreementType": "Personal",
    "defaultQuantity": 1,
    "unit": "pcs",
    "unitPrice": 50.0,
    "amount": 50.0,
    "amountVat": 0.0,
    "amountTotal": 50.0,
    "taxDeductable": true,
    "vatPercentage": 0.0,
    "currencyCode": "DKK",
    "paymentRequired": false,
    "scheduleType": "Monthly",
    "scheduleBaseTier": 7,
    "scheduleFixedDay": 1,
    "scheduleEveryOther": 1,
    "scheduleCalendarUnit": "Month",
    "purposeAccountingCode": "test",
    "dataSetGuid": "351b0f2d-07fb-4e85-a033-xxxxxxxxxxxx",
    "communicationCollectionGuid": "93383565-801a-4dce-992f-xxxxxxxxxxxx"
  },
  "subscription": {
    "quantity": 1,
    "dataSetGuid": "351b0f2d-07fb-4e85-a033-xxxxxxxxxxxx",
    "startDate": "2023-07-01"
  },
  "amount": 50.0,
  "oneOffAmount": 250.0,
  "currencyCode": "DKK",
  "paymentType": "OneOff",
  "frequency": "Monthly",
  "paymentMethodType": "MobilePaySubscriptions",
  "msisdn": "xxx",
  "plan": "Membership",
  "description": "Membership of the club",
  "oneOffDescription": "First payment",
  "dataSetGuid": "351b0f2d-07fb-4e85-a033-xxxxxxxxxxxx",
  "communicationCollectionGuid": "93383565-801a-4dce-992f-xxxxxxxxxxxx",
  "preWaitPageUrl": "https://domain.tld/preWait.html",
  "postWaitPageUrl": "https://domain.tld/postWait.html",
  "errorReturnPageUrl": "https://domain.tld/error.html",
  "successReturnPageUrl": "https://domain.tld/thanks.html"
}

 

A subscription of a personal yearly Agreement of 50 DKK paid by Betalingsservice starting on 2023-02-01:

{
  "contact": {
    "address": "xxx",
    "city": "xxx",
    "countryCode": "xxx",
    "email": "xxx",
    "externalId": "xxx",
    "firstName": "xxx",
    "lastName": "xxx",
    "msisdn": "xxx",
    "name": "xxx",
    "nationalId": "xxx",
    "postCode": "xxx"
  },
  "agreement": {
    "name": "Membership",
    "description": "Membership of the club",
    "agreementType": "Personal",
    "defaultQuantity": 1,
    "unit": "pcs",
    "unitPrice": 50.0,
    "amount": 50.0,
    "amountVat": 0.0,
    "amountTotal": 50.0,
    "taxDeductable": true,
    "vatPercentage": 0.0,
    "currencyCode": "DKK",
    "paymentRequired": false,
    "scheduleType": "Yearly",
    "scheduleBaseTier": 2,
    "scheduleFixedDay": 1,
    "scheduleEveryOther": 12,
    "scheduleCalendarUnit": "Month",
    "purposeAccountingCode": "test",
    "dataSetGuid": "351b0f2d-07fb-4e85-a033-xxxxxxxxxxxx",
    "communicationCollectionGuid": "93383565-801a-4dce-992f-xxxxxxxxxxxx"
  },
  "subscription": {
    "quantity": 1,
    "dataSetGuid": "a75083de-ac8d-4946-bb08-xxxxxxxxxxxx",
    "startDate": "2023-02-01"
  },
  "amount": 50.0,
  "currencyCode": "DKK",
  "paymentType": "Recurring",
  "frequency": "Yearly",
  "paymentMethodType": "Betalingsservice",
  "cpr": "xxx", // nationalId
  "cvr": "xxx", // businessCode
  "sortCode": "xxx",
  "accountNumber": "xxx",
  "plan": "Membership",
  "description": "Membership of the club",
  "dataSetGuid": "a75083de-ac8d-4946-bb08-xxxxxxxxxxxx",
  "communicationCollectionGuid": "db2ed250-46fa-4cf1-b74e-xxxxxxxxxxxx",
  "preWaitPageUrl": "https://domain.tld/preWait.html",
  "postWaitPageUrl": "https://domain.tld/postWait.html",
  "errorReturnPageUrl": "https://domain.tld/error.html",
  "successReturnPageUrl": "https://domain.tld/thanks.html"
}

 

Response

HTTP

Description

201

Created

400

Something's wrong with request body.

HTTP 201 Example

{
  "paymentSessionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "initialUserRedirectUrl": "https://domain.tld/preWait.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "redirectToGatewayUrl": "https://epay.onlinefundraising.dk/ToGatewayRedirect?sessionGuid\u003d2fbba6f6-021b-4b92-b3d5-xxxxxxxxxxxx",
  "redirectReturnFromGatewayUrl": "https://domain.tld/postWait.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "finalRedirectUrl": "https://domain.tld/tak.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx",
  "finalRedirectUrl": "https://domain.tld/error.html?paymentSessionGuid=da2ddec67-2795-4dc8-bc78-xxxxxxxxxxxx"
}

Resulting properties of a Payment Session

Name

Type

Description

state

STRING

Please see list of Payment Session States below

initialUserRedirectUrl

STRING

URL to defined preWaitPageUrl

redirectToGatewayUrl

STRING

URL to chosen Payment Gateway

finalRedirectUrl

STRING

URL to either defined successReturnPageUrl or errorReturnPageUrl depending on session state

paymentGatewayPaymentReferenceId

STRING

Unique internal Guid

paymentGatewayTransactionId

STRING

Transaction ID from chosen Payment Gateway. Only applies to Bambora (Card) and MobilePay Subscriptions

contactGuidResult

STRING

Unique Guid of resulting Contact

paymentMethodGuidResult

STRING

Unique Guid of resulting Payment Method

paymentGuidResult

STRING

Unique Guid of resulting Payment

Payment Session States

Following is a list of Payment Session states:

State

Description

SentToGateway

Session has been handed over to chosen Payment Gateway

Complete

Session is complete and user should be redirected to finalRedirectUrl

Rejected

Session was rejected by user

SoftError

Session was rejected by user closing payment window

Failed

Session failed with chosen Payment Gateway

SessionExpired

Session expired due to missing user or gateway action

Contents of preWait and postWait

You may wish to use the preWait and postWait landing pages as they are defined in OnlineFundraising, but you can replace them entirely adding e.i. your own branding, tracking or some custom logic to the checkout flow.

To get started, please see example files attached below.

 

Was this article helpful?

0 out of 0 found this helpful

Related articles