Introduction
A Payment represents a single payment request by a set Contact.
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": 1,
"pageSize": 50,
"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.
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 |
INTEGER |
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 order id, 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 |
Payment Gateway Providers
|
Payment Gateway Provider |
Description |
|---|---|
|
ePay |
Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Online etc. |
|
QuickPay |
Delivers payments methods: Dankort, Visa, MasterCard, MobilePay Online etc. |
|
DIBS |
NETS Easy (formerly DIBS) delivers payments methods: Dankort, Visa, MasterCard, MobilePay Online etc. |
|
SaltPay |
Teya (formerly SaltPay) delivers payments methods: Visa and MasterCard |
|
MobilePay |
Vipps MobilePay |
|
Betalingsservice |
Betalingsservice (Basis and Total Solution) |
|
DirectDebit |
Direct Debit via Arion Bank |
|
SMSCPH |
Delivers SMS payment method |
|
PaymentReceiver |
System handling external payments received via various integrations |
|
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 |
Payments via Dankort, Visa, MasterCard etc. |
|
MobilePayOnline |
Single payments via Vipps MobilePay Online |
|
MobilePaySubscriptions |
OneOff and Recurring payments via Vipps MobilePay Recurring (formerly Subscriptions) |
|
MobilePayExternal |
Single payments via Vipps MobilePay Number (formerly MyShop) |
|
Betalingsservice |
Recurring payments via Betalingsservice, inclusive Payment Slips (Indbetalingskort) |
|
DirectDebit |
Recurring payments with Direct Debit via Arion Bank |
|
SMS |
Payments via SMS keywords |
|
Test |
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 for single payments
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 |