Manage Payments

The platform exposes two APS types that allow external management systems to request the platform to pay some financial documents.

APS Types

Manager of Payment Methods

The PaymentMethodManagement APS type exposes custom operations for operating payment methods that a particular account can use for payments.

The APS type is used to create a singleton APS resource that you can identify by sending the following request:

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

The response will look as follows:

HTTP/1.1 200 OK

{ "aps": {
      "schema": "/aps/2/types/175",
      "package": {
         "id": "00917fa1-7321-4050-bc48-580e120db894",
         "href": "/aps/2/packages/00917fa1-7321-4050-bc48-580e120db894"
      },
      "modified": "2017-11-07T07:50:18Z",
      "id": "09c04f9e-ef78-483a-a840-50ef7ab6bf3f",
      "type": "http://www.odin.com/billing/payment-method-management/1.0",
      "status": "aps:ready",
      "revision": 3
}}

Using this manager, an external management system can monitor payment methods and change their status as explained later in the Manage Payment Methods section.

Payment Manager

The PaymentManagement APS type exposes the following operations to manage payments:

• The pay operation creates a payment document to pay specified financial documents of a specified account as explained later in the Pay Financial Documents section.
• The payments operation returns a list of payment documents of a specified account as explained in the Get Payment Documents section.

The type is used to create a singleton APS resource that you can identify by sending the following request:

GET /aps/2/services/payment-manager

The response will look as follows:

HTTP/1.1 200 OK

{ "aps": {
      "schema": "/aps/2/types/174",
      "package": {
         "id": "00917fa1-7321-4050-bc48-580e120db894",
         "href": "/aps/2/packages/00917fa1-7321-4050-bc48-580e120db894"
      },
      "modified": "2017-11-07T07:50:18Z",
      "id": "61f0f499-c486-410f-8fb8-bd2eb31075a5",
      "type": "http://www.odin.com/billing/payment-management/1.0",
      "status": "aps:ready",
      "revision": 3
}}

An external management system can call the above-listed operations exposed by the manager.

Initial Configuration

Ensure you have a customer for testing the payment API with the following configuration.

• The customer must have some payment methods, and at least one of them must use an automatic payment system, for example, Visa:

  

  Disallow auto-payment for all payment methods, otherwise the default method will be applied to every new order automatically.

• The customer must order at least one service plan. The respective sales orders must be waiting for payment with no payment methods attached:

  

  Pay attention to the order ID and its total amount.

• Add a debit memo that decreases the customer balance and thus must be paid similarly to an invoice:

  

  Pay attention to the document ID and its total amount.

Manage Payment Methods

With the platform built-in payment method manager, external systems can operate payments methods as specified by the PaymentMethodManagement APS type.

Get Payment Methods

An external management system can get a list of payment methods that a particular account can use to pay the acquired services. The following call of the paymentMethods operation contains the APS ID of an account identified in accordance with the Account Lookup section.

GET /aps/2/services/payment-method-manager/paymentMethods?accountId=c0f26f33-0514-4be1-ad7e-3b5b50be56cb

The response will look similar to the following:

HTTP/1.1 200 OK

[
   {
      "id": 12,
      "paymentSystemId": "Visa",
      "paymentSystem": "Visa",
      "number": "****1111",
      "name": "Visa ****1111",
      "type": "CREDIT_CARD",
      "perCustomer": true,
      "status": "ACTIVE",
      "defaultMethod": false
   },
   {
      "id": 0,
      "paymentSystemId": "Check/Cash",
      "paymentSystem": "Check/Cash",
      "number": null,
      "name": "Check/Cash",
      "type": "MANUAL",
      "perCustomer": false,
      "status": "ACTIVE",
      "defaultMethod": false
   },
   ...
]

From the above response, the system identifies that there is a Visa card for online payment.

The paymentMethods operation supports a custom filter that allows selecting payment methods by the following parameters (all parameters are optional):

• accountUuid is the APS ID of an account whose payment methods are required. The requester must be assigned the admin role on the requested account to use that parameter in the filter. For example, a requester is a reseller’s staff member that is getting payment methods of a subordinate customer. If that parameter is missed in the custom filter, the platform returns a list of payment methods belonging to the account the authenticated requester is working for.
• paymentSystemId is the ID of a payment system, for example, paymentSystemId=Visa.
• externalId is the payment method ID in the external payment system. This is used only by custom payment methods, type=CUSTOM.

Update Payment Methods

With the updatePaymentMethod operation, an external management system can change the status of a payment method, as in the following example:

PUT /aps/2/services/payment-method-manager/paymentMethods/12

{
   "id": 12,
   "status": "EXPIRED"
}

The normal response is “HTTP/1.1 200 OK”.

Pay Financial Documents

A request for payment must contain a JSON representation of the APSPaymentCreationRequest structure declared in the PaymentManagement APS type:

PROPERTY	Type	Sample value	Notes
total	Number	31.00	Total amount to pay.
paymentMethodId	Integer	10	Internal ID of the payment method to use for payment. It must be one of the methods identified by the Get Payment Methods operation.
documents	Array	[{“docType”: “INVOICE”, “docId”: 1000005, “amount”: 17.00 }]	A list of financial documents to pay.
docType	String enum: [“INVOICE”, “ORDER”]	“ORDER”	Defines if the document to pay is an order (“ORDER”) or an account receivable document (“INVOICE”), such as invoice or debit memo.
docId	String	“1000005”	Internal ID of the document to pay.
amount	Number	17.00	In the specified financial document, the amount to pay.

With the collected properties, a request to pay the customer’s order and debit memo created earlier will look as follows:

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

"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 similarly to the following:

HTTP/1.1 200 OK

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

The platform accepted the request for payment and assigned the ID #10 to it. In the provider control panel, you will find the following documents with zero balance:

• A new payment that covers the other two documents, the debit memo and the new invoice.
• The debit memo specified in the payment operation.
• A new invoice generated automatically when the required order was paid.

Get Payment Documents

To get a list of payments, send a GET request for those payments. For example, the following is a request for payments #6 and #10:

GET /aps/2/services/payment-manager/payments?paymentIds=6,10

The APS controller returns an array of APS payment structures, each including a payment ID and payment status.

HTTP/1.1 200 OK

[
   {
      "accountId": 1000002,
      "paymentId": 6,
      "currency": "USD",
      "tokenizedCardNumber": "****1111",
      "transactionNumber": "1510220159",
      "authorizationDate": "2017-11-09T09:35:59Z",
      "amount": 21.65,
      "status": "MONEY_CAPTURED",
      "paymentCardType": "Visa"
   },
   {
      "accountId": 1000002,
      "paymentId": 10,
      "currency": "USD",
      "tokenizedCardNumber": "****1111",
      "transactionNumber": "1510224944",
      "authorizationDate": "2017-11-09T10:55:44Z",
      "amount": 21.65,
      "status": "MONEY_CAPTURED",
      "paymentCardType": "Visa"
   }
]

Conclusion

Service providers can integrate their own management system with the platform to manage payments using the described interface.

← Synchronize Fees

Manage Accounts →