Singleton APS resource with methods for operations with payments.
In this document:
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.
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
POST |
/payment |
Created payment info APSPaymentCreationResult |
Creates standalone payment |
|
PUT |
/payments/{paymentId} |
Updated payment info APSPayment |
Proceed operation on a payment |
|
POST |
/payments |
Created payment info APSPaymentCreationResult |
Creates standalone payment |
|
GET |
/payments |
List of payments |
Get list of payments. |
HTTP Request
POST /aps/2/services/payment-manager/payment
Description
Creates standalone payment
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
params |
Returns
Created payment info APSPaymentCreationResult
HTTP Request
PUT /aps/2/services/payment-manager/payments/{paymentId}
Description
Proceed operation on a payment
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
paymentId |
Integer |
|
params |
Returns
Updated payment info APSPayment
HTTP Request
POST /aps/2/services/payment-manager/payments
Description
Creates standalone payment
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
params |
Returns
Created payment info APSPaymentCreationResult
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
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 |
Payment redirect post argument
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
key |
String |
Not Required |
Payment redirect key |
|
value |
String |
Not Required |
Payment redirect value |
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. |
APS structure for payment creation result.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
paymentId |
Integer |
Not Required |
Payment identifier. |
|
redirectData |
Not Required |
Redirect payment callback result. |
||
modalForm |
Not Required |
Redirect payment callback form data. |
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 |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
docType |
Enum |
Required |
Type of document. |
|
docId |
String |
Not Required |
Document identifier. |
|
amount |
Number |
Not Required |
Document amount. |
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 |
Not Required |
Payment method for payment |
||
useAvailableCredit |
Boolean |
Not Required |
Use available customer credit |
|
documents |
Array of Document |
Not Required |
Payment documents |
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. |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
id |
String |
Required |
The ID of a payment method parameter. |
|
name |
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 |
A structure in the key-value format used to create a string in multiple languages.
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 |
Not Required |
Optional payment method for payment |
||
invoices |
Array of Integer |
Not Required |
List of payment’s invoices IDs |
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 |
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.
The PaymentManagement API exposes its operations for the payment
documents only. It does not support
refunds or void checks.
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:
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.
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.
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.
Restrict the scope by an RQL statement as described in the RQL Statements section.
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.
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).
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 |
---|---|---|---|
|
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
|
|
|
|
Payment status |
|
|
|
Requires the payment manager to return the representation of the payment method associated with the payment. |
|
|
|
Sorts the returned list of payments by payment ID; this is best used together with |
|
Offset and 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 |
|
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.
To get payments for a certain day, the request must be sent after the DailyBillingProcessing task for this day is finished in the platform.
To omit calculation of the total number of payments for a faster response, use the APS-Skip-Content-Range HTTP header.
The following sections illustrate how to receive, create, and update payment documents.
In this section:
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.
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
}
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 }
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.