Payment API

Payment

API Documentation

Senest redigeret:

Introduction

A Payment represents a single payment request by a set Contact.

Properties

Name

Type

Example

Description

paymentGuid

STRING

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

Unique GUID

createdTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of Payment creation

paymentType

STRING

Single

Please see list of Payment Types below

contactGuid

STRING(64)

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

GUID of Contact

amount

DOUBLE

100.0

Amount charged

amountPaid

DOUBLE

100.0

The actual amount paid by the end user. It may diverse from amount on rare occasions.

state

STRING

Charged

Please see list of Payment States below

paymentMethodType

STRING

 

Please see list of Payment Method Types below

paymentRequired

BOOLEAN

false

Is the Payment required for the Subscription to be valid?

taxDeductable

BOOLEAN

true

Defines basis for tax deductibility

dueDateTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of expected charge

chargedTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of successful charge

failedTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of charge failure

rejectedTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of charge rejection

refundedTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of successful refund

cancelledTs

DATETIME

2019-01-01 00:00:00 +0100

Timestamp of cancellation

errorCode

STRING

10001

Please see list of Payment Error Codes below

errorDescription

STRING

This is a friendly description

User friendly description of the provided error

currencyCode

STRING

DKK

ISO formatted Currency Code (wiki)

paymentGatewayProvider

STRING

Betalingsservice

Please see list of Payment Gateway Providers below

paymentGatewayReferenceId

STRING

 

Gateway reference GUID

paymentGatewayTransactionId

STRING

 

Gateway transaction ID (only relevant for ePay/Bambora)

metaData

JSON Object

 

Contains metadata such as card type, masked card number etc.

purposeAccountingCode

STRING(32)

 

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

paymentMethodAccountingCode

STRING(32)

 

Accounting Code defined by Payment Method. Please see example list under Payment Method.

amountRefunded

DOUBLE

0.0

Amount refunded

agreementGuid

STRING(64)

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

GUID of Agreement

subscriptionGuid

STRING(64)

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

GUID of Subscription

paymentMethodGuid

STRING(64)

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

GUID of Payment Method

paymentSessionGuid

STRING(64)

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

GUID of Payment Session used internally to identify the initial payment session

dataSetGuid

STRING(64)

a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx

A DataSet GUID containing metadata

externalId

STRING

 

An external ID to eg. CRM

externalLink

STRING

 

An external URL to e.g. CRM

Endpoints

GET /payments?pageNumber={x}&pageSize={y}&startDate={yyyy-mm-dd}&endDate={yyyy-mm-dd}&state={z}

Get a list of Payments with a given state, at a given size by a given offset and date limitation. All parameters are optional.

Response

HTTP

Description

200

OK

HTTP 200 Example

{
  "pageNumber": {x},
  "pageSize": {y},
  "startDate": {yyyy-mm-dd},
  "endDate": {yyyy-mm-dd},
  "list": [
    {
      "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "...": "..."
    },
    {
      "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
      "...": "..."
    }
  ]
}

 

GET /payments?search={paymentGatewayReferenceId}

Get an array of Payments by a given search string matching the paymentGatewayReferenceId.

Response

HTTP

Description

200

OK

HTTP 200 Example

[
  {
    "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

 

GET /payment/{guid}

Get a single Payment.

Response

HTTP

Description

200

OK

404

Payment not found

HTTP 200 Example

{
  "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "createdTs": "2019-01-01 00:00:00 +0100",
  "paymentType": "",
  "contactGuid": "",
  "agreementGuid": "",
  "amount": 100.0,
  "taxDeductable": true,
  "state": "",
  "dueDateTs": "",
  "chargedTs": "",
  "failedTs": "",
  "errorCode": "",
  "errorDescription": "",
  "currencyCode": "DKK",
  "paymentGateway": "",
  "paymentGatewayReferenceId": "",
  "paymentGatewayTransactionId": "",
  "purposeAccountingCode": "",
  "paymentMethodAccountingCode": "",
  "amountRefunded": 0.0,
  "paymentMethodGuid": "",
  "subscriptionGuid": "",
  "paymentRequired": true,
  "paymentSessionGuid": "",
  "dataSetGuid": "",
  "externalLink": "",
  "metaData": {
    "card": {
      "type": "Dankort",
      "cardNumber": "457150XXXXXX7478",
      "acquirer": "Nets/Teller",
      "orderId": "4200xxxxx",
      "transactionId": "88821321"
    },
    "bs": {
      "customerNumber": "605XXX",
      "mandate": "956964XXX",
      "ocr": "1231352356235",
      "dataSupplierReferenceId": "GSFDGSERG",
      "paymentSlipDispatchMethod": "195",
      "transactionCode": "297"
    },
    "mps": {
      "externalId": "1568581537XXX"
    },
    "sms": {
      "msisdn": "4512345678"
    }
  }
}

 

GET /payment/{guid}/receipt

Get a single Payment's Receipt Planned

Response

HTTP

Description

200

OK

404

Payment not found

HTTP 200 Example

{
  "receiptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "...": "..."
}

 

GET /payment/{guid}/transactions

Get a list of Transactions for a single Payment.

Response

HTTP

Description

200

OK

404

Payment not found

HTTP 200 Example

[
  {
    "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "transactionType": "charge",
    "amount": 100.0,
    "...": "..."
  },
  {
    "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "transactionType": "refund",
    "amount": 100.0,
    "...": "..."
  }
]

 

GET /payment/{guid}/chargeAttempts

Get a list of Charge Attempts for a single Payment.

Response

HTTP

Description

200

OK

404

Payment not found

HTTP 200 Example

[
  {
    "chargeAttemptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "chargeAttemptGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

 

GET /payment/{guid}/orderLines

Get a list of Order Lines for a single Payment Planned

Response

HTTP

Description

200

OK

404

Payment not found

HTTP 200 Example

[
  {
    "orderLineGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  },
  {
    "orderLineGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
    "...": "..."
  }
]

 

PATCH /payment/{guid}

Update a single Payment using add, replace or remove operations.

Request

The following must be provided as the request body:

[
  {
    "op": "add|replace|remove",
    "path": "/externalId",
    "value": "1001"
  }
]

Response

HTTP

Description

200

OK

400

Something's wrong with request body.

404

Payment was not found

 

POST /payment/{guid}/Refund

Refund a Payment.

Request

The following must be provided as the request body:

{
  "amount": 100.0,
  "callbackUrl": "https://yourdomain.tld/"
}

Response

HTTP

Description

202

Accepted

400

Bad Request

404

Payment not found

A callback is sent when the refund operation either fails or succeeds. Please see Refund for entity properties.

POST body example

{
  "paymentGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "transactionGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx",
  "refundGuid": "a863d62e-d53b-4651-9b7b-xxxxxxxxxxxx"
}

 

POST /payment/{guid}/Cancel

Cancel a Pending Payment.

Response

HTTP

Description

202

Accepted

400

Bad Request

404

Payment not found

A callback is sent when the cancel operation either fails or succeeds.

 

Payment Gateway Providers

Payment Gateway Provider

Description

ePay

Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Online etc. (recently bought by Bambora)

MobilePay

MobilePay Subscriptions

Betalingsservice

Betalingsservice (Basis and Total Solution)

LinkMobility

Delivers SMS payment method

SMSCPH

Delivers SMS payment method

Test

Used for testing purposes

Log

Only used in Sandbox for testing purposes

Payment Types

Payment Type

Description

Single

A single Payment without connection to any Subscription

Recurring

A recurring Payment adjacent to a Subscription

OneOff

An initial Payment adjacent to a Subscription

Payment Method Types

Payment Method

Description

Card

Single and Recurring payments via Dankort, Visa, MasterCard etc.

MobilePayOnline

Single payments via MobilePay Online

MobilePaySubscriptions

OneOff and Recurring payments via MobilePay Subscriptions

Betalingsservice

Recurring payments via Betalingsservice, inclusive Payment Slips (Indbetalingskort)

SMS

Single payments via SMS keywords

Test

Single and Recurring payments as Test

Log

Only used in Sandbox for testing purposes

Payment States

Following is a list of Payment states:

State

Description

Ready

Result from processing a pending subscription. A short state.

AwaitingRetry

Charge attempt failed. The charge attempt will retry if possible.

AwaitingCharge

Charge attempt has been created but has not yet been sent to Payment Gateway.

Pending

The charge attempt has been sent to payment gateway (e.g. MobilePay) and awaits a result.

SessionExpired

Payment is expired. Used for MobilePay Subscriptions one-off that was not accepted in time.

Charged

The payment was successfully charged.

Failed

Payment failed. (Error codes)

Rejected

Payment request was rejected by Contact.

Cancelled

Payment was cancelled by merchant after the payment request was sent to Payment Gateway and prior to the expected due date (with Payment Gateway limitations in mind).

Refunded

Payment was successfully refunded.

Payment State Diagram for recurring payments

Payment_State_Diagram-Payment_Recurring.png

Payment State Diagram for single payments

Payment_State_Diagram-Payment.png

Payment Cancel Codes

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code

Description

State

200101

Cancelled by Debtor

Cancelled

200102

Cancelled by Creditor

Cancelled

 

Payment Error Codes

For further examples and ties to other entities, please see: Error and Cancel Codes

Error Code

Description

Examples

State

200001

Payment Method signup failed

Invalid data provided for either National ID, Business Number, Sort Code or Account Number with Betalingsservice.

Failed

200002

Payment Method was rejected during sign up

Involves Debtor rejection of a request i.e. in a mobile app.

Rejected

200003

Payment Method signup expired

Debtor did not approve request in mobile app in time.

SessionExpired

200004

Payment Method has expired

Involves expiration of Card or requirement of new SCA.

Expired

200005

Payment Method has failed

Errors with the Gateway without options to retry or reactive.

Failed