Manage Payments

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

APS Types

Payment Method Manager

The PaymentMethodManagement APS type exposes custom operations for operating payment methods that a particular account can use for payments. Through the platform built-in service based on that APS type, 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 payments operation returns a list of payment documents of a specified account as explained in the Get Payment Documents section.

• The pay operation creates a payment document to fulfil specific financial requests of a specified account as explained later in the Fulfil Financial Requests section.

• The update operation changes an existing payment document.

An external management system can call the above-listed operations exposed by the platform built-in service based on that APS type.

Initial Configuration

The platform must be configured for the use of at least one automatic payment system, such as Visa. If customer consent is required to store customer payment methods, the platform-wide configuration of the corresponding payment system must require that consent, as in the following sample Visa 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 therefore 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 an 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",
      "ownerAccountId": "8349472a-efe8-417f-a7be-ef6b900ed9c6",
      "number": "****1111",
      "name": "Visa ****1111",
      "type": "CREDIT_CARD",
      "perCustomer": true,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": false,
      "consentStatus": "CONSENT_NOT_REQUIRED",
      "consentDate": null,
      "deletionDate": null,
      "whoAgreedId": null,
      "agreementURL": null,
      "parameters": []
   },
   {
      "id": 0,
      "paymentSystemId": "Check/Cash",
      "paymentSystem": "Check/Cash",
      "ownerAccountId": null,
      "number": null,
      "name": "Check/Cash",
      "type": "MANUAL",
      "perCustomer": false,
      "status": "ACTIVE",
      "ratified": "NOT_REQUIRED",
      "defaultMethod": false,
      "consentStatus": "CONSENT_NOT_REQUIRED",
      "consentDate": null,
      "deletionDate": null,
      "whoAgreedId": null,
      "agreementURL": null,
      "parameters": []
   },
   /* ... */
]

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 external systems to select 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"
}

For a payment method created before the request for customer consent is added in the platform-wide configuration, the following call will require the owner’s consent for that method:

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

{
   "consentStatus": "CONSENT_NOT_PROVIDED",
   "deletionDate": "2019-05-25"
}

The customer can give their consent using the user panel or another way outside of the platform facilities. In the latter case, the external management system can change the consent status by the following request:

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

{
   "consentStatus": "CONSENT_PROVIDED",
   "consentDate": "2019-05-22"
}

After the last change, the response to the Get Payment Methods operation will change as in the following example:

{
   //...,
   "consentStatus": "CONSENT_PROVIDED",
   "consentDate": "2019-05-22",
   "deletionDate": null,
   "whoAgreedId": "2d4d3969-6595-4412-ac6b-a0b5d99ff432",
   "agreementURL": "https://ingrammicrocloud.com/marketplace-legal/general-terms-of-service/"
}

Fulfil Financial Requests

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/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"
      }
   ]
}

If successful, the response will look similar 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 a balance of zero:

• 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 payment manager returns an array of payments:

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 systems with the platform to manage payments using the described interface. For more details and examples on using the above considered operations, refer to the corresponding sections in the PaymentManagement API reference.

← Synchronize Fees

Manage Accounts →