PaymentManagement

Singleton APS resource with methods for operations with payments.

GraphViz

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "PaymentManagement",
  "id": "http://www.odin.com/billing/payment-management/1.2",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "payDeprecated": {
      "path": "/payment",
      "verb": "POST",
      "response": {
        "type": "APSPaymentCreationResult"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "params": {
          "kind": "body",
          "type": "APSPaymentCreationRequest"
        }
      }
    },
    "update": {
      "path": "/payments/{paymentId}",
      "verb": "PUT",
      "response": {
        "type": "APSPayment"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "paymentId": {
          "kind": "path",
          "type": "integer"
        },
        "params": {
          "kind": "body",
          "type": "APSPaymentUpdateRequest"
        }
      }
    },
    "pay": {
      "path": "/payments",
      "verb": "POST",
      "response": {
        "type": "APSPaymentCreationResult"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "params": {
          "kind": "body",
          "type": "APSPaymentCreationRequest"
        }
      }
    },
    "payments": {
      "path": "/payments",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "APSPayment"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "accountId": {
          "kind": "query",
          "type": "string"
        },
        "paymentIds": {
          "kind": "query",
          "type": "string"
        }
      }
    }
  },
  "structures": {
    "RedirectData": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "description": "method"
        },
        "message": {
          "type": "string",
          "description": "message"
        },
        "redirectURL": {
          "type": "string",
          "description": "redirect url"
        },
        "postArguments": {
          "type": "array",
          "description": "post arguments",
          "items": {
            "type": "PostArgument"
          }
        }
      }
    },
    "PostArgument": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Redirect argument id"
        },
        "value": {
          "type": "string",
          "description": "Redirect argument value"
        }
      }
    },
    "ModalFormData": {
      "type": "object",
      "properties": {
        "checkoutScriptSrc": {
          "type": "string",
          "description": "checkoutScriptSrc"
        },
        "checkoutScriptSection": {
          "type": "string",
          "description": "checkoutScriptSection"
        },
        "checkoutScriptHandler": {
          "type": "string",
          "description": "checkoutScriptHandler"
        },
        "checkoutScriptHtml": {
          "type": "string",
          "description": "checkoutScriptHtml"
        },
        "hints": {
          "type": "string",
          "description": "hints"
        }
      }
    },
    "APSPaymentCreationResult": {
      "type": "object",
      "properties": {
        "paymentId": {
          "type": "integer",
          "description": "PaymentID"
        },
        "redirectData": {
          "type": "RedirectData",
          "description": "Redirect payment result"
        },
        "modalForm": {
          "type": "ModalFormData",
          "description": "Modal Form"
        }
      }
    },
    "PaymentContext": {
      "type": "object",
      "properties": {
        "originUrl": {
          "type": "string"
        },
        "callbackUrl": {
          "type": "string"
        },
        "callbackUrl3D": {
          "type": "string"
        },
        "callbackUrlOk": {
          "type": "string"
        },
        "callbackUrlFail": {
          "type": "string"
        },
        "notifyUrl": {
          "type": "string"
        },
        "ccpViewID": {
          "type": "string"
        }
      }
    },
    "Document": {
      "type": "object",
      "properties": {
        "docType": {
          "type": "string",
          "required": true,
          "enum": [
            "INVOICE",
            "ORDER"
          ]
        },
        "docId": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        }
      }
    },
    "APSPaymentCreationRequest": {
      "type": "object",
      "properties": {
        "total": {
          "type": "number",
          "required": true
        },
        "paymentMethodId": {
          "type": "integer"
        },
        "paymentContext": {
          "type": "PaymentContext"
        },
        "useAvailableCredit": {
          "type": "boolean"
        },
        "documents": {
          "type": "array",
          "items": {
            "type": "Document"
          }
        }
      }
    },
    "APSPaymentMethod": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "paymentSystemId": {
          "type": "string"
        },
        "paymentSystem": {
          "type": "string"
        },
        "ownerAccountId": {
          "type": "string"
        },
        "number": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "readonly": true
        },
        "type": {
          "type": "string",
          "enum": [
            "CREDIT_CARD",
            "BANK_ACCOUNT",
            "EXTERNAL",
            "MANUAL",
            "CUSTOM",
            "MODAL"
          ]
        },
        "perCustomer": {
          "type": "boolean",
          "required": true
        },
        "status": {
          "type": "string",
          "required": true,
          "enum": [
            "ACTIVE",
            "NOT_INSTANTIATED",
            "EXPIRED",
            "SUSPENDED",
            "PENDING",
            "FAILED",
            "CANCELLED",
            "DISABLED",
            "DELETED"
          ]
        },
        "ratified": {
          "type": "string",
          "required": true,
          "enum": [
            "YES",
            "NO",
            "NOT_REQUIRED"
          ]
        },
        "defaultMethod": {
          "type": "boolean",
          "required": true
        },
        "consentStatus": {
          "type": "string",
          "enum": [
            "CONSENT_NOT_REQUIRED",
            "CONSENT_NOT_PROVIDED",
            "CONSENT_PROVIDED"
          ]
        },
        "consentDate": {
          "type": "string",
          "format": "date"
        },
        "deletionDate": {
          "type": "string",
          "format": "date"
        },
        "whoAgreedId": {
          "type": "string"
        },
        "agreementURL": {
          "type": "string"
        },
        "parameters": {
          "type": "array",
          "items": {
            "type": "PaymentMethodParameter"
          }
        }
      }
    },
    "PaymentMethodParameter": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "required": true
        },
        "name": {
          "type": "APSMLString"
        },
        "type": {
          "type": "string"
        },
        "value": {
          "type": "object",
          "required": true
        }
      }
    },
    "APSMLString": {
      "type": "object"
    },
    "APSPayment": {
      "type": "object",
      "properties": {
        "accountId": {
          "type": "string",
          "required": true
        },
        "paymentId": {
          "type": "integer",
          "required": true
        },
        "paymentNumber": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        },
        "paymentType": {
          "type": "string"
        },
        "tokenizedCardNumber": {
          "type": "string"
        },
        "transactionNumber": {
          "type": "string"
        },
        "authorizationDate": {
          "type": "string"
        },
        "date": {
          "type": "string"
        },
        "amount": {
          "type": "number"
        },
        "status": {
          "type": "string",
          "enum": [
            "IN_PROGRESS",
            "SUCCESS",
            "FAILED"
          ]
        },
        "paymentMethod": {
          "type": "APSPaymentMethod"
        },
        "invoices": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        }
      }
    },
    "APSPaymentUpdateRequest": {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "required": true,
          "enum": [
            "RELEASE",
            "VOID"
          ],
          "enumTitles": [
            "Release payment",
            "Void payment"
          ]
        }
      }
    }
  }
}

The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:

POST  /aps/2/services/payment-manager/<operation-path>?<query-params>

{/*<body params>*/}

In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.

Custom Operations

OPERATION

VERB

PATH

RETURNS

Description

payDeprecated

POST

/payment

Created payment info APSPaymentCreationResult

Creates standalone payment

update

PUT

/payments/{paymentId}

Updated payment info APSPayment

Proceed operation on a payment

pay

POST

/payments

Created payment info APSPaymentCreationResult

Creates standalone payment

payments

GET

/payments

List of payments

Get list of payments.

payDeprecated

HTTP Request

POST /aps/2/services/payment-manager/payment

Description

Creates standalone payment

Parameters

PARAMETER

TYPE

DESCRIPTION

params

APSPaymentCreationRequest

APSPaymentCreationRequest

Returns

Created payment info APSPaymentCreationResult

update

HTTP Request

PUT /aps/2/services/payment-manager/payments/{paymentId}

Description

Proceed operation on a payment

Parameters

PARAMETER

TYPE

DESCRIPTION

paymentId

Integer

params

APSPaymentUpdateRequest

APSPaymentUpdateRequest

Returns

Updated payment info APSPayment

pay

HTTP Request

POST /aps/2/services/payment-manager/payments

Description

Creates standalone payment

Parameters

PARAMETER

TYPE

DESCRIPTION

params

APSPaymentCreationRequest

APSPaymentCreationRequest

Returns

Created payment info APSPaymentCreationResult

payments

HTTP Request

GET /aps/2/services/payment-manager/payments

Description

Get list of payments.

Parameters

PARAMETER

TYPE

DESCRIPTION

accountId

String

APS UID of the reseller/account

paymentIds

String

List of paymentIds separated with comma

Returns

List of payments

Structures

RedirectData

Payment redirect data

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

method

String

Not Required

Payment redirect method

message

String

Not Required

Payment redirect message

redirectURL

String

Not Required

Payment redirect URL

postArguments

Array of PostArgument

Not Required

Payment redirect post arguments

PostArgument

Payment redirect post argument

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

key

String

Not Required

Payment redirect key

value

String

Not Required

Payment redirect value

ModalFormData

Payment redirect data

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

checkoutScriptSrc

String

Not Required

Checkout script source

checkoutScriptSection

String

Not Required

Checkout script section

checkoutScriptHandler

String

Not Required

Checkout script handler

checkoutScriptHtml

String

Not Required

Checkout script html

hints

String

Not Required

Hints.

APSPaymentCreationResult

APS structure for payment creation result.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

paymentId

Integer

Not Required

Payment identifier.

redirectData

RedirectData

Not Required

Redirect payment callback result.

modalForm

ModalFormData

Not Required

Redirect payment callback form data.

PaymentContext

APS structure for payment context.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

originUrl

String

Not Required

Original request url.

callbackUrl

String

Not Required

Result callback url.

callbackUrl3D

String

Not Required

Callback url for payment 3DSecure.

callbackUrlOk

String

Not Required

Result callback url for successfull payment request.

callbackUrlFail

String

Not Required

Result callback url for failed payment request.

notifyUrl

String

Not Required

Callback url for payment notify.

ccpViewID

String

Not Required

View ID for return. Used as return URL for CCP

Document

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

docType

Enum

Required

Type of document.

docId

String

Not Required

Document identifier.

amount

Number

Not Required

Document amount.

APSPaymentCreationRequest

APS structure for payment creation request.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

total

Number

Required

Total amount of payment

paymentMethodId

Integer

Not Required

Payment method for payment

paymentContext

PaymentContext

Not Required

Payment method for payment

useAvailableCredit

Boolean

Not Required

Use available customer credit

documents

Array of Document

Not Required

Payment documents

APSPaymentMethod

APS structure for payment methods.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

Integer

Not Required

Optional payment method identifier.

paymentSystemId

String

Not Required

Payment system identifier.

paymentSystem

String

Not Required

Localized name of the payment system.

ownerAccountId

String

Not Required

Owner Account identifier.

number

String

Not Required

Optional payment method number.

name

String

Not Required Read Only

Name of the payment method that combines the name of its payment system and its number.

type

Enum

Not Required

Payment method type.
Type of a payment method.
CREDIT_CARD - Locally processed and stored credit card.
BANK_ACCOUNT - Bank account.
EXTERNAL - External payment site.
MANUAL - Manual payment.
CUSTOM - Custom payment method.
MODAL - Modal form.

perCustomer

Boolean

Required

Flag that indicates if a separate payment method should be created for every customer.

status

Enum

Required

Status of the payment method.
Status of a payment method.
ACTIVE - Payment method is active.
NOT_INSTANTIATED - Payment method is not instantiated.
EXPIRED - Payment method has expired.
SUSPENDED - Payment method is suspended.
PENDING - Payment method creation in 3rd-party system is in progress.
FAILED - Payment method creation in 3rd-party system is failed.
CANCELLED - Payment method is cancelled by 3rd-party system.
DISABLED - Payment method is disabled by vendor.
DELETED - Not used, as API neither returns deleted payment methods nor allows to set this status.

ratified

Enum

Required

Ratification status of the payment method.
Ratification status of a payment method.
YES - Payment method is ratified.
NO - Payment method is not ratified.
NOT_REQUIRED - Ratifications is not required.

defaultMethod

Boolean

Required

Flag that indicates if the payment method is default.

consentStatus

Enum

Not Required

Consent status for this payment method. See ConsentStatus
Consent status for specified payment method.
‘’CONSENT_NOT_REQUIRED’’ - Consent is not required for the payment method.
‘’CONSENT_NOT_PROVIDED’’ - Consent is required but not provided by user for the payment method.
‘’CONSENT_PROVIDED’’ - Consent is provided by user for the payment method.

consentDate

String

Not Required

Date, when user agreed on storing his/her credential for payment method

deletionDate

String

Not Required

The date when the payment method will be deleted. This field is retrieved from table PayToolConsent

whoAgreedId

String

Not Required

agreementURL

String

Not Required

Link to the page on provider’s web site with consent conditions

parameters

Array of PaymentMethodParameter

Not Required

Payment method parameters.

PaymentMethodParameter

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

id

String

Required

The ID of a payment method parameter.

name

APSMLString

Not Required

A multi-lang string that represents the name of a payment method parameter.

type

String

Not Required

The type of a payment method parameter.

value

Object

Required

The value of a payment method parameter. The value type depends on the type of this parameter. If the field type is “ENUM”, the value is an APSOptionValue structure. Otherwise, the value is a string.

APSMLString

A structure in the key-value format used to create a string in multiple languages.

APSPayment

APS structure for payment.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

accountId

String

Required

Account UUID

paymentId

Integer

Required

Payment ID

paymentNumber

String

Not Required

Payment number

currency

String

Not Required

Currency key of payment

paymentType

String

Not Required

Payment card type

tokenizedCardNumber

String

Not Required

Payment card tokenized number

transactionNumber

String

Not Required

Payment transaction number

authorizationDate

String

Not Required

Payment card authorization date

date

String

Not Required

Payment creation date

amount

Number

Not Required

Payment card authorized amount

status

Enum

Not Required

Payment status

paymentMethod

APSPaymentMethod

Not Required

Optional payment method for payment

invoices

Array of Integer

Not Required

List of payment’s invoices IDs

APSPaymentUpdateRequest

APS structure for payment update.

NAME

TYPE

ATTRIBUTES

DEFAULT

DESCRIPTION

operation

Enum

Required

Requested operation ‘’RELEASE’’ - Payment should be released ‘’VOID’’ - Payment should be voided

Limitations

Operations and Properties

The payment management service fully complies with the schema if you upgrade the platform with the following two patches:

Warning

Without the above patches, the following API components are not available:

  • The update operation.

  • The query parameter accountId in the pay operation.

  • The paymentNumber, date, and paymentMethod properties in the APSPayment structure.

Document Types

The PaymentManagement API exposes its operations for the payment documents only. It does not support refunds or void checks.

Scopes of GET Requests

The payments collection is one of the biggest collections in the platform. Therefore, GET requests for payments can substantially affect platform performance. If there are too many payments in the platform, we advise reducing the number of returned payments to only the most necessary by adding various scope restrictions described in this section.

When receiving a GET request for payments, the platform must define the requested scope in the following order:

  1. If the paymentIds query parameter is specified, the platform uses its value as the initial list of requested payments. The following steps can reduce this scope.

  2. Restrict the scope by account, which is specified by the accountId query parameter or identified by the authentication credentials. For more details about query parameters, refer to the Query Parameters section.

  3. If the account defined in the previous step is a reseller, define the scope for that reseller through the APS-Actor-Scope HTTP header as described in the Actor Scope section.

  4. Restrict the scope by an RQL statement as described in the RQL Statements section.

Query Parameters

The payments operation enables you to use these two query parameters:

  • paymentIds is a string containing a comma-separated list of payment IDs, for example:

    paymentIds=6,7,10
    
  • accountId is the APS ID used by a reseller to specify a sub-reseller or a customer whose payments must be returned, for example:

    accountId=47b9b-e827-437f-9e4a-d0acd9469a78
    

    Note

    1. If accountId is not specified, the platform defines the account by using the authentication credentials provided in the API call.

    2. In addition to this parameter, the scope of the returned payments is restricted by the APS-Actor-Scope header as described in the Actor Scope section.

Actor Scope

If the APS-Actor-Scope HTTP header is not used, the platform returns those payment documents whose owner is the account defined explicitly or implicitly.

Note

An account (reseller or customer) owns those payment documents that they use to pay to their sales vendor.

Assuming that the account is a reseller that has sub-resellers and customers, the APS-Actor-Scope HTTP header affects the scope of payments by the following values assigned to it:

  • OWN (default): return only the reseller`s own payments.

  • FULL: return payments owned by this reseller and payments owned by all subordinate accounts (sub-resellers and customers).

RQL Statements

You can add an RQL statement after query parameters separating it with the & sign. An RQL statement contains functions and relational operators with payment properties as presented in the following table.

PARAMETER

Operator or function

Description

Example

date

Operators:
eq
gt
ge
lt
le
Select payments by creation date:
- On the specified date
- After the specified date
- On the specified date or later
- Earlier than the specified date
- On the specified date or earlier

eq(date,2019-12-30)

status

eq

Payment status

eq(status,IN_PROGRESS)

paymentMethod

select

Requires the payment manager to return the representation of the payment method associated with the payment.

select(paymentMethod)

paymentId

sort

Sorts the returned list of payments by payment ID; this is best used together with limit after all other query parameters.

sort(paymentId),limit(2000,1000)

Offset and limit

limit

Specifies a range of items from the total list of selected payments to be returned in the response. The first parameter is the offset (the index of the first payment in the total list), and the second one is the upper limit on the number of returned payments. This is best used together with sort after all other RQL functions and operators.

sort(paymentId),limit(2000,1000)

In a GET request, an RQL statement looks like a single complex parameter separated from HTTP query parameters or from the URI by the & sign.

General Search Recommendations

Daily Billing Processing

To get payments for a certain day, the request must be sent after the DailyBillingProcessing task for this day is finished in the platform.

Skipping Content Range

To omit calculation of the total number of payments for a faster response, use the APS-Skip-Content-Range HTTP header.

Examples

The following sections illustrate how to receive, create, and update payment documents.

Get Payment Documents

To get the first 1000 payments with the status IN_PROGRESS of a specified reseller for a certain period and get the associated payment methods, send a GET request with the corresponding query parameters as in the following example:

GET /aps/2/services/payment-manager/payments?accountId=e1e47b9b-e827-437f-9e4a-d0acd9469a78&eq(date,2019-10-31),select(paymentMethod),sort(paymentId),limit(0,1000)"

The payment management service returns a list of payments similar to the following:

HTTP/1.1 200 OK

[
    {
        "accountId": "e1e47b9b-e827-437f-9e4a-d0acd9469a78",
        "amount": 100.0,
        "date": "2019-10-31",
        "authorizationDate": "",
        "currency": "EUR",
        "invoices": [ 44 ],
        "paymentId": 28,
        "paymentMethod": {
            "agreementURL": null,
            "consentDate": null,
            "consentStatus": "CONSENT_NOT_REQUIRED",
            "defaultMethod": true,
            "deletionDate": null,
            "id": 20,
            "name": "SEPA DirectDebit ****0300",
            "number": "****0300",
            "ownerAccountId": "e1e47b9b-e827-437f-9e4a-d0acd9469a78",
            "parameters": [
                {
                    "id": "BankNumber",
                    "value": "BAERDEF1XXX"
                },
                {
                    "id": "AccountNumber",
                    "value": "DE83514203000051420300"
                },
                {
                    "id": "AccHolderName",
                    "value": "ANDREW Berge, Cole a"
                }
            ],
            "paymentSystem": "SEPA DirectDebit",
            "paymentSystemId": "SEPA DirectDebit",
            "perCustomer": true,
            "ratified": "NOT_REQUIRED",
            "status": "ACTIVE",
            "tokenizable": false,
            "type": "BANK_ACCOUNT",
            "whoAgreedId": null
        },
        "paymentType": "SEPA DirectDebit",
        "status": "IN_PROGRESS",
        "tokenizedCardNumber": "****0300",
        "transactionNumber": ""
    },
    { /* Other payments */ }
]

The paymentMethod section is the APSPaymentMethod structure defined in the PaymentMethodManagement APS type.

Pay Financial Documents

A request to pay a customer’s order and a debit memo will look as follows:

POST /aps/2/services/payment-manager/payments

"Content-Type": "application/json"

{
   "total": "21.65",
   "paymentMethodId": 12,
   "documents": [
      {
         "docType": "ORDER",
         "docId": 1000007,
         "amount": "6.25"
      },
      {
         "docType": "INVOICE",
         "docId": 9,
         "amount": "15.40"
      }
   ]
}

In case of success, the response will look similar to the following:

HTTP/1.1 200 OK

{
   "paymentId": 10,
   "redirectData": null,
   "modalForm": null
}

Release Payments

When a payment is in the hold status, continue its processing by calling the RELEASE operation as in the following example:

PUT /aps/2/services/payment-manager/payments/22

{  "operation": "RELEASE" }

If successful, the returned payload contains the payment ID, for example:

HTTP/1.1 200 OK

{ "paymentId": 22 }

Void Payments

To void a payment, call the VOID operation as in the following example:

PUT /aps/2/services/payment-manager/payments/23

{  "operation": "VOID" }

The response is the same as in the RELEASE operation. For more details about void operations, refer to Voiding Payments.